API docs, properly

Ditto's API documentation has been rewritten — copy-pasteable quickstart, request and response examples on every live endpoint, common-mistakes guide, error-handling reference, workflow diagram, Postman collection, and brand-aware rendering.

The Ditto API documentation has been rewritten end to end — proper quickstart, real examples on every endpoint, an error guide that names the actual failures, a workflow diagram, and a Postman collection.

The Ditto API has shipped useful documentation for some time. It was not, however, particularly *good* documentation. Endpoints listed without examples; planned endpoints rendered identically to live ones; filter values that had to be guessed by trial and error; rate limits undocumented; pagination handled three different ways depending on which page you landed on. Reasonable for an early API. Embarrassing now. The whole thing has been rewritten. ### What's new - **A real quickstart.** Step through the canonical workflow — recruit a panel, create a study, ask a question, poll, complete, share — with copy-pasteable curl on every step. Ten minutes from "I have an API key" to "I have a finished study with a share link". - **Examples on every endpoint.** Every live endpoint now has at least one request and one response example. Most have several. Real shapes, anonymised values. - **A common-mistakes section.** The mistakes we actually see in support tickets — `size` vs `group_size`, `id` vs `uuid`, full state names vs 2-letter codes, `income` filter that silently returns zero — are now called out by name, with the fix. - **Error-handling guidance.** A page covering the failures you'll hit (429, 409, job status `failed`, 500/502/504), what they mean, and what to do. - **Workflow diagram and Postman collection.** Visual reference for how the endpoints fit together, plus a Postman collection you can import in one click. - **Brand-aware rendering.** The docs now know which brand you arrived from (FishDog or Ditto / `fish.dog` or `askditto.io`) and render accordingly. Same content, the right name on it. ### Where to find it [`https://app.askditto.io/docs/api`](https://app.askditto.io/docs/api). Bookmark it; the Postman collection link is at the top. If you find a gap, the docs have an inline "report this" link on every page. We mean it. ---

New quickstart walks the canonical workflow (recruit → create → ask → poll → complete → share) with copy-pasteable curl on every step.

Every live endpoint has request and response examples; planned-but-not-yet-live operations are now visually distinguished.

A common-mistakes section names the recurring support-ticket patterns (`size` vs `group_size`, `id` vs `uuid`, state codes, unsupported filters) with the fix.

Workflow diagram and Postman collection are linked from the docs landing page.

Docs now render brand-aware — same content, the right brand name depending on which domain you arrived from.

The Ditto API has shipped useful documentation for some time. It was not, however, particularly *good* documentation.

Ten minutes from 'I have an API key' to 'I have a finished study with a share link'.

If you find a gap, the docs have an inline 'report this' link on every page. We mean it.

DOCUMENT TYPE: Product Release Note TOPIC: Comprehensive overhaul of the Ditto API documentation Release: API docs, properly, 2026-03-04 Version: (none) Release type: Improvement Breaking change: No Summary: The Ditto API documentation has been rewritten end to end. New copy-pasteable quickstart, request and response examples on every live endpoint, a common-mistakes section addressing the recurring support-ticket patterns, error-handling reference, a visual workflow diagram, a Postman collection, and brand-aware rendering for both fish.dog and askditto.io. What changed: - Quickstart walks the canonical workflow (recruit → create → ask → poll → complete → share) with curl on every step. - Every live endpoint has at least one request and one response example. Most have several. - Planned-but-not-yet-live operations now carry an x-implementation-status marker and render distinctly from live operations. - New common-mistakes page names the recurring patterns: size vs group_size, id vs uuid, full state names vs 2-letter codes, unsupported filters (income, ethnicity, employment status). - Error-handling guide covers 429, 409, job status failed, 500/502/504, with what each means and what to do. - Workflow diagram (visual) and Postman collection (one-click import) are linked from the docs landing page. - Docs render brand-aware: same content, FishDog or Ditto branding depending on the domain the request arrived from. Why we built this: The docs had grown organically and accumulated debt. Customers were guessing filter values by trial and error, hitting 404s on planned endpoints they thought were live, and asking the same questions in support over and over. The overhaul addresses each of those. How to use: Visit https://app.askditto.io/docs/api. The Postman collection link is at the top. Migration impact: None. The API surface is unchanged; only the documentation has changed. Author: Phillip Gales, FishDog Platform: FishDog (fish.dog)