Providing an OpenAPI Spec
An OpenAPI (or Swagger) spec is the most precise description of your backend you can give Claude. With one, Claude knows exactly which endpoints exist, what they accept, what they return, and which errors are possible.
Claude treats the spec as the source of truth, so the app calls your real endpoints rather than invented ones.
How to provide it
Section titled “How to provide it”Put your spec file in documentation/ before you type /start:
documentation/└── api.yaml # or api.json, openapi.yaml, swagger.yamlAny .yaml or .json file that contains openapi: or swagger: is detected, whatever its name.
If your spec defines authentication
Section titled “If your spec defines authentication”If your spec declares securitySchemes, Claude runs a connection test against your backend at the end of Intake. It also adds the credential variable names to web/.env.local as placeholders. Fill in the values yourself. They stay on your machine and are never committed.
See Environment Configuration for the variables.
Endpoints that aren’t in your spec
Section titled “Endpoints that aren’t in your spec”Claude doesn’t invent API calls. If a story needs an endpoint, parameter, header or request shape that your spec doesn’t document, Claude stops and asks you:
| Option | What happens |
|---|---|
| Add it to the spec | You describe the operation, Claude adds it to the spec, and the build continues. |
| Use a documented alternative | Claude works within the existing spec, for example by fetching a list and filtering it. |
| Defer the story | Claude skips the story for now and moves on. It comes back on the next /continue. |
| Proceed and record it | Claude builds it as an acknowledged extension and records the gap in generated-docs/architecture.md to close later. |
If you don’t have a spec
Section titled “If you don’t have a spec”Claude works out a reasonable API shape from your requirements and sample data. It writes the result to generated-docs/specs/api-spec.yaml, marking each endpoint it inferred.
If your backend is still being built, the manual test asks you to confirm the inferred endpoints match it. You may still need to adjust some responses when you connect to the real backend.
Adding or changing a spec later
Section titled “Adding or changing a spec later”Add or update the spec in documentation/, then type /api-mock-refresh. Claude updates its working copy of the spec and regenerates the mock handlers for the endpoints that changed.