API spec
For any interface another team — or agent — will build against. An API spec is a treaty between producer and consumer: endpoints, schemas, errors, versioning, and exactly what changes for existing consumers.
New services, new endpoints on existing services, breaking changes, public or partner APIs, and any webhook contract. If someone outside your head will call it, spec it. Pair with the feature spec when the API is part of a larger feature.
Section-by-section, annotated
§1 Purpose & consumers
What this API does and who calls it — internal teams, partners, agents, the public. Consumers determine how strict the contract must be. Good looks like: named consumers with named contact people.
§2 Endpoints
Method, path, and purpose for every endpoint. Purpose matters as much as path: it tells the consumer which endpoint to reach for. Good looks like: a consumer can implement their integration reading only this section.
§3 Schemas
Request and response bodies field by field: types, required vs optional, constraints, examples. Ambiguity here becomes production incidents. Good looks like: every field has a type, a requiredness, and at least one example.
§4 Error contract
Every failure mode: status code, error body shape, and whether the consumer should retry. Errors are part of the API, not an afterthought. Good looks like: a consumer can write their error handling from this table alone.
§5 Versioning & compatibility
What counts as a breaking change, how versions are communicated, deprecation windows. This section is the API's promise about the future. Good looks like: a breaking-change checklist the team actually runs.
§6 Non-functional requirements
Latency budgets, rate limits, availability targets, auth model. Consumers build their own SLAs on top of yours — state them honestly. Good looks like: numbers with measurement methods, not adjectives.
§7 Consumer impact & rollout
What changes for each consumer, migration steps, dual-run or canary plans, rollback triggers. Good looks like: each consumer knows exactly what to do and by when.
Copy it, fill it, publish it
# API Spec: [API / service name]
| Field | Value |
|---------|--------------------|
| Owner | [Name] |
| Status | Draft / In review / Approved / Live |
| Version | [e.g. v2] |
| Created | [YYYY-MM-DD] |
## Revision block
| Rev | Date | Author | Description |
|-----|------------|--------|------------------------|
| 0.1 | [YYYY-MM-DD] | [Name] | Initial draft |
## 1. Purpose and consumers
[What this API does, in one paragraph.]
| Consumer | Contact | Usage |
|----------|---------|-------|
| [Team / partner / agent] | [Name] | [What they call and why] |
## 2. Endpoints
### `METHOD /path`
- **Purpose:** [What this endpoint is for; when to use it vs. siblings]
- **Auth:** [Required scopes / keys]
- **Idempotency:** [Safe to retry? Idempotency key?]
### `METHOD /path`
- **Purpose:** [One line]
## 3. Schemas
### Request: `METHOD /path`
| Field | Type | Required | Constraints | Example |
|-------|------|----------|-------------|---------|
| [name] | [string] | yes | [max length, format] | [example] |
### Response: `200 OK`
| Field | Type | Notes |
|-------|------|-------|
| [name] | [string] | [description] |
### Response: `201 Created`
[Same table shape as needed.]
## 4. Error contract
| Status | Code | Meaning | Retry? |
|--------|------|---------|--------|
| 400 | [invalid_field] | [What the client did wrong] | No — fix the request |
| 401 | [unauthorized] | [Auth missing/invalid] | No — re-authenticate |
| 404 | [not_found] | [Resource doesn't exist] | No |
| 409 | [conflict] | [State conflict] | Maybe — see notes |
| 429 | [rate_limited] | [Quota exceeded] | Yes — honor Retry-After |
| 500 | [internal] | [Server error] | Yes — with backoff |
Error body shape:
```json
{ "code": "[code]", "message": "[human-readable]", "details": {} }
```
## 5. Versioning and compatibility
- **Breaking change definition:** [What counts: field removal, type change, ...]
- **Versioning scheme:** [URL path / header / ...]
- **Deprecation policy:** [Notice period, sunset headers, changelog location]
- **Support window:** [How long old versions live, e.g. 12 months]
## 6. Non-functional requirements
- **Latency:** [p50/p95/p99 targets and measurement method]
- **Rate limits:** [Requests per key per window; burst policy]
- **Availability:** [Target, e.g. 99.9% monthly]
- **Auth model:** [How clients authenticate and authorize]
## 7. Consumer impact and rollout
| Consumer | Impact | Action required | Deadline |
|----------|--------|-----------------|----------|
| [Name] | [Breaking / additive / none] | [Migrate / nothing] | [Date] |
- **Rollout plan:** [Canary, dual-run, flag, cutover steps]
- **Rollback triggers:** [Metrics or events that trigger rollback]
- **Comms:** [Changelog entry, consumer notification plan]
## 8. Open questions
- [ ] [Question] — Owner: [name], due [date]
| Rev | Date | Description |
|---|---|---|
| 1.0 | 2026-09-20 | Initial publication. |