Phase 3 — Architecture & Engineering
API Specification
Every endpoint, typed and contracted, before the AI writes a single route handler
2 min read · Document 10 of 30
What is this document?
The API Specification lists every endpoint with its method, path, authentication, request schema, response schemas (success and every error), rate limits and performance target.
Frontend and backend are built against the same contract, so they fit together the first time.
Why does it matter?
- When the API lives only in a developer’s head, every frontend build involves guessing.
- Typed error responses mean the UI can show the right message for every failure.
- Auth rules per endpoint prevent accidental public routes.
What's inside?
- Endpoints — Grouped by space, with auth and rate limits.
- Schemas — Request and response shapes, including errors.
- Conventions — Pagination, versioning, idempotency.
Request schemaAuth checkValidationBusiness logicResponse schema
How CREAH generates it
CREAH builds this document from your Stage 0 answers and interview. Questions that shape it include:
- Which actions must be safe to retry?
- Who may call each endpoint?
- Which responses need pagination?
Example excerpt
## GET /api/projects/{id}/cart
Auth: signed-in owner only — 401 JSON otherwise
Response 200:
{ subtotal_usd: number, line_items: LineItem[], currency: "USD" | "INR" }
Response 404:
{ error: "Project not found" }
SLA: < 500ms (deterministic, no AI call)