Product Release

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.

4 March 2026

Phillip Gales

By Phillip Gales

Improvement
Ditto's Quick Start documentation page, with the four-step bash setup for installing the Ditto Claude Code skill and acquiring a free API key.
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)

Key Takeaways

  • 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. 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`. 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.

---

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.

Frequently Asked Questions

Where do I find the new docs?

At https://app.askditto.io/docs/api. The Postman collection link is at the top of the landing page; the quickstart is the first navigation entry.

Do the docs distinguish live endpoints from planned ones?

Yes. Live endpoints render with full request/response examples and the standard reference layout. Planned endpoints are now visually distinguished with an x-implementation-status marker, so you can tell at a glance which calls will work today.

What's in the common-mistakes section?

The mistakes we actually see in support tickets: using size instead of group_size in recruit payloads, using id instead of uuid for studies, using full state names instead of 2-letter codes, and using filter parameters (income, ethnicity, employment status) that aren't supported. Each mistake is paired with the fix.

Is there a Postman collection?

Yes. A Postman collection is linked from the docs landing page. Import it in one click and every endpoint is preconfigured with the right URL and headers — bring your own API key.

What does brand-aware rendering mean?

Following the rebrand from Ditto to FishDog, some customers still arrive via the askditto.io domain and others via fish.dog. The docs now detect which brand you came from and render the right brand name throughout. Content is identical.

About the Author

Phillip Gales

Phillip Gales

Phillip is a serial tech entrepreneur that specializes in applying AI and machine learning solutions to antiquated and heavy industries. He has been a senior leader or founder at a number of successful startups.

Phillip holds an MBA from Harvard Business School, an MEng from the University of Cambridge, and is a Y-Combinator alum

LinkedIn

More Releases

The v1 API is now CORS-friendly

Browser-side JavaScript can now call the v1 API directly. CORS shipped this week — preflight handled, allowlist plus regex on Origin, rate-limit headers exposed. One restriction: `/v1/billing/*` stays server-only.

Read Release