How do I start integrating with the Ditto external API?

Start with the Quickstart guide, follow the six-step workflow, and use the OpenAPI spec at /docs/api/openapi.yaml for request and response contracts.

Where can I find the full OpenAPI contract?

Use the OpenAPI link on /docs/api or fetch the spec directly from /docs/api/openapi.yaml.

How do I retrieve results for asynchronous requests?

Submit the workflow request, capture job_id from the response, and poll GET /v1/jobs/{job_id} until status reaches a terminal state.

Does the API support direct questions without creating a study?

Yes. The docs cover direct question paths for single agents and research groups in addition to the full study workflow.

Where are the Claude Code workflow guides?

The /docs/api page links to the Claude Code hub and use-case workflow guides for segmentation, pricing, messaging, VoC, GTM, and launch research.

Public API

Ditto External API

Production-ready endpoints for recruiting research groups, creating studies, asking questions, completing workflows, and sharing results.

OpenAPI spec Quickstart guide Changelog notes Workflow guides Jump to docs

Status: Public

Version: v1

Quickstart Canonical 6-step implementation sequence with extraction and polling notes. Async Polling Status model and wait strategy for `GET /v1/jobs/{job_id}`. Common Mistakes Frequent integration mistakes and exact corrections. Workflow Diagram Branching map for study, direct question, curation, and media workflows. Postman Collection Runnable request collection for the primary flow and branch scenarios. What Changed Dated release notes labeled by breaking vs non-breaking impact.

Workflow Branching Overview

Use this branch map to choose the correct flow before making your first API call.

Diagram showing core 6-step study flow, direct agent question flow, direct group question flow, over-recruit and curate flow, and media upload attachment branch.

Core study flow: recruit group -> create study -> ask question -> poll job -> complete study -> enable share link.
Direct agent question: ask one recruitable agent directly without creating a study.
Direct group question: ask an existing group directly without creating a study.
Over-recruit and curate: recruit larger initial group, ask a screening question, remove mismatched agents, continue study questions.
Media branch: upload assets once and reference `media_asset_id` from direct or study question endpoints.

Claude Code Guides

Workflow-first tutorials for AI agents and developers. Use these when you want complete end-to-end examples by use case, not just endpoint reference details.

Get Started

Claude Code Hub Entry point with capability overview, quick links, and endpoint tables. Install Ditto Skill Skill installation, API key setup, filters, troubleshooting, and FAQ. Install PMM Skill Product-marketing focused setup and study-type decision support. Why Ditto AI-agent decision brief and capability gap rationale.

Use-Case Workflows

API Workflow Hub Index of all workflow guides with endpoint references. Customer Segmentation Multi-group segment comparison and prioritization workflow. Competitive Intelligence Perception gaps, switching triggers, and battlecard-ready outputs. Pricing Research Willingness-to-pay and pricing framework workflows. Positioning Validation Positioning clarity and differentiation validation workflows. Product Messaging A/B/C messaging test loops and decision templates. Sales Enablement Objection handling, quote banks, and sales collateral workflows. Voice of Customer Always-on VoC loops and monthly pulse-check workflow. GTM Strategy Go-to-market motion and channel strategy validation flow. Product Launch Pre-launch concept validation and post-launch sentiment checks. Content Marketing One-study to multi-format content production workflow. Question Design Playbook Question frameworks, patterns, and anti-patterns by study type. Recruitment Strategies Audience selection, over-recruit-and-curate, and balancing guidance.