A normal PRD says what a user should be able to do. An API PRD has to additionally say what a caller is allowed to rely on — which is a much stronger promise.
Structure, adapted specifically for API work:
# | Section | What goes in it |
|---|---|---|
1 | Who calls this, and why | The specific caller (internal team, partner, developer segment) and the job they're trying to do |
2 | Resources and actions | The nouns (what data/objects exist) and verbs (what can be done to them) — in plain language before it becomes endpoints |
3 | Request/response examples | Real, worked examples for the happy path and every important error case — write the actual JSON, don't describe it abstractly |
4 | Authentication and authorization model | Who can call this, what they need to prove, what they're allowed to do once authenticated |
5 | Rate limits and quotas | What they are, whether they vary by tier, what happens when a caller hits them |
6 | Versioning commitment | Is this additive-only, or will there be a v2 someday — and what's the deprecation policy if so |
7 | Non-functional requirements | Latency expectations, uptime target, expected volume at launch and at scale |
8 | Documentation plan | Quickstart, reference, guides — who writes what, and by when |
9 | Success metrics | Time to first call, adoption, error rate, support ticket volume — the things a customer would actually feel |
10 | Rollout plan | Internal dogfood, private beta, public beta, GA — with explicit exit criteria for each stage |
The section most PMs skip, and the one that saves the most pain later, is section 3. Write the actual JSON for three real scenarios — the happy path, a validation failure, and a not-found case — before engineering starts building. An engineer can build against real examples. Nobody can build against "return an appropriate error."
YOUR MOVE THIS WEEK
Take the PRD for your next API feature. Add section 3 — real worked request/response JSON for three scenarios — even if nothing else in the doc changes. Send it to your engineering lead and ask "does this change anything for you?" It usually does.