Technical / API PRD Template

A Technical or API PRD picks up once the product decision is already made and the open question is how the system behaves: the endpoints, what happens when a call fails, and what breaks for an existing integration when something changes. You write one for anything another team, or an external developer, will build against.

When you need one

Write this when the feature exposes an API, changes an existing one, or is backend-heavy enough that the interesting decisions are about data model and failure behavior rather than screens. If the feature is UI-only with no new endpoint and no schema change, the Standard PRD template covers it better — this one asks about rate limits and versioning that do not apply. The test: if the builders need to agree on a request/response shape before writing code, you need this template.

The template

# [API / system name] — Technical PRD
Owner: [name] · Status: [draft/review/approved] · Last updated: [date]

## TL;DR
[2-3 sentences: what this API/system does, who consumes it, why now.]

## Problem & context
[What exists today, what is changing, and why now. Link the Standard PRD or decision doc that justified the "should we build this" question, if one exists.]

## Goals & non-goals
Goals: [2-4 outcomes this system is accountable for]
Non-goals: [explicitly out of scope, so no consumer assumes it]

## API surface
| Endpoint | Method | Request | Response | Notes |
| --- | --- | --- | --- | --- |
| [/v1/resource] | [GET/POST/...] | [shape] | [shape] | [auth required, idempotency, etc.] |

## Data model & schema changes
[New or changed tables/fields. Migration approach for existing data — backfill, dual-write, or none.]

## Auth, permissions & rate limits
Auth: [scheme — API key, OAuth, service token]
Permissions: [who/what can call this, and at what scope]
Rate limits: [limit per key/user, and behavior when exceeded]

## Error handling
| Status code | Meaning | When it fires | Retry-safe? |
| --- | --- | --- | --- |
| [4xx/5xx] | [meaning] | [condition] | [yes/no] |

## Versioning & backward compatibility
[Versioning scheme. What counts as a breaking change. Deprecation window for the previous version, if one exists.]

## Performance & scale requirements
[Latency target (e.g. p95), expected volume, and the volume at which this needs to be revisited.]

## Security & privacy
[Data classification, encryption in transit/at rest, and any regulation that applies, by name.]

## Observability & rollout plan
Logging & metrics: [what gets logged, what gets alarmed]
Rollout: [phased by %, by account tier, or all-at-once] with rollback plan: [how to revert]

## Dependencies, integrations & open questions
Dependencies: [other systems/teams this needs, with owner and status]
Open questions: [question] — Owner: [name] — Needed by: [date]

Section by section

TL;DR and problem & context

Say what kind of work this is before asking anyone to evaluate it — a new API reads differently from a breaking change to one three teams already call.

Goals & non-goals

Non-goals matter more here than in most PRDs, because an API's consumers will build against whatever you do not explicitly rule out.

API surface

The table other teams actually build against. Everything downstream — error handling, versioning, rate limits — is a rule about what this table is allowed to do.

Data model & schema changes

Schema changes outlive this feature. The migration plan matters as much as the new fields, because existing rows do not update themselves.

Auth, permissions & rate limits

Where the domain-specific gotchas hide. Generic auth advice will not catch that this API's scoping model does not match the rest of the platform's.

Error handling

The status code table is a contract. A consumer's retry logic depends on getting this right more than it depends on the happy path being fast.

Versioning, backward compatibility, and performance & scale

Three non-functional questions, one theme: what this system owes to the callers it already has.

Security & privacy

Say what data this touches and what regulation, if any, applies by name — silence here reads as unchecked, not as not applicable.

Observability & rollout plan

How you will know this is working once it ships, and how you back out if it is not.

Dependencies, integrations, and open questions

The logistics tail: what this needs from other systems or teams, and what is still unresolved. No pass maps to this group directly — it is where a reviewer checks the document is finishable, not where they check it is well-argued.

Worked example

Here are two sections from an endpoint that exports a workspace's audit log.

API surface

| Endpoint | Method | Request | Response | Notes | | --- | --- | --- | --- | --- | | /v1/audit-log/export | POST | { from_date, to_date, format } | { export_id, status: "queued" } | Auth: service token, scoped to one workspace. Async — result arrives via the export_id below. | | /v1/audit-log/export/{export_id} | GET | — | { status, download_url? } | download_url expires after 24h. |

Error handling

| Status code | Meaning | When it fires | Retry-safe? | | --- | --- | --- | --- | | 400 | Invalid date range | to_date before from_date, or range exceeds 90 days | No — fix the request | | 403 | Scope mismatch | Token does not carry export scope for this workspace | No | | 429 | Rate limited | More than 5 export requests per workspace per hour | Yes, after Retry-After header | | 500 | Export failed | Unhandled failure during async processing | Yes, once |

Both sections do a lot right — the async pattern is stated, error codes are specific, and retry-safety is marked per code instead of assumed.

The deliberate weakness: the 90-day range limit in the 400 error has no stated reason, and nothing else explains why 90 rather than 30 or 365. A reviewer will ask whether that number comes from a query timeout, a storage cost decision, or a guess, and "invalid date range" is not an answer. The honest version names the source: [TBD: 90-day cap based on current query timeout at p99, confirm after the async worker migration lands, sign off by 20 Aug]. That survives review. An unexplained constant reads as arbitrary even when it is not.

Common mistakes

• A response shape described in prose instead of fields. "Returns the export status" is not a contract. List every field, type, and nullable.
• No idempotency answer on a POST. A retried request after a timeout either creates a duplicate export or it does not — decide which before a client finds out by accident.
• Rate limits with no source. A bare number in the error table is a guess wearing the shape of a decision. Say where it came from, or mark it [TBD: reason, date].
• Versioning deferred to "when we need it." By the time a breaking change is needed, there is no time left to define one. Decide now.

Run it through a review

An API spec gets reviewed by the same eleven passes as any other draft — Thinkr's critique does not run a separate rubric for backend work. If the error table or the versioning policy is thin, that is usually the first thing that comes back.