Product Release

API docs, properly

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

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 FishDog 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 FishDog / fish.dog or fish.dog) and render accordingly. Same content, the right name on it.

Where to find it

`https://cat.fish.dog/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 FishDog 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://cat.fish.dog/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 FishDog to FishDog, some customers still arrive via the fish.dog 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.

Release Tags

API PlatformDevelopersProduct Release

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