A well-designed API needs to communicate with at least three distinct audiences: tools that consume the API programmatically, developers who are learning or debugging, and AI systems that need to understand the API surface to generate correct code or plan tool calls. Each audience has different requirements, and a single document format can't serve all three optimally. We solve this by exposing three ways to consume the same API documentation, each targeting a different consumer.
The three layers are not maintained separately. They all derive from the same source of truth, so adding a new endpoint or changing a field propagates automatically to all three layers without any manual documentation work.
The full API surface is available as a machine-readable OpenAPI 3.1 specification. This is the layer consumed by code generators, linting tools, SDK generators, and any other tooling that needs precise type information. Because the spec is generated directly from the API's own definitions rather than written by hand, it can never drift out of sync with what the API actually does.
The spec covers all public and authenticated endpoints, with security schemes declared for API key and Bearer token authentication. It is the authoritative reference for anyone building a client integration or testing the API with tools like Postman or Insomnia. You'll find it linked from docs.crowdee.ai.
Alongside the spec, we publish a polished, interactive API explorer where developers can read endpoint documentation, inspect request and response schemas, and send live requests directly from the browser. Authentication credentials can be entered once and applied to all requests in the session.
We chose an explorer that renders nested schema objects and complex, real-world data structures cleanly, since our API surface makes heavy use of both. The explorer is the first thing a developer sees when they open our API documentation — a working, interactive reference rather than a static page or a plain JSON blob. You can try it yourself at docs.crowdee.ai.
We also publish a plain-text summary of the API, structured for consumption by LLMs and AI coding assistants, following the emerging llms.txt convention. The idea is simple: give language models a compact, human-readable description of an API or documentation site, without requiring them to parse a large JSON document.
Our llms.txt covers the full scope of the API: every endpoint group, its purpose, the key request and response fields, and the authentication requirements. It's public and requires no authentication to fetch. An AI assistant that reads it before generating API calls has the context it needs to produce correct code for the most common integration patterns — a genuinely useful shortcut if you're building with AI coding tools against the Crowdee API. It's linked alongside the rest of our developer documentation at docs.crowdee.ai.
The three documentation layers are the visible output of a type safety discipline that we apply from the database all the way to the browser in our own applications. Definitions live in one place, and everything downstream — validation, API documentation, and the client libraries our own frontend teams use — is derived from that single source rather than kept in sync by hand.
What this means in practice: when our internal teams call the API from our own applications, they get autocompletion for every request parameter and response field. If the underlying data model changes, the validation rules, the API documentation, and the internal client libraries all update together, in one step. The three documentation endpoints reflect the same change without any manual intervention.
This discipline also means the OpenAPI spec is never stale. It's generated from the live API definitions, not from a checked-in file that someone forgot to update. The interactive explorer and the llms.txt endpoint consume those same live definitions. What you see in the explorer is always what the API actually does.
Share this article:
