API documentation template

A free API documentation template: overview, authentication, quickstart, errors, pagination, rate limits, webhooks and an endpoint reference format with request and response examples.

Best for

SaaS teams with a public or partner API, platform teams documenting internal APIs

Length

A guide section plus one page per resource

Sections

9

1. 01

   Overview

   What the API lets developers do, the base URL, the format (JSON over HTTPS) and the versioning scheme. Three or four sentences.

   textCopy

   Base URL: https://api.harbor-analytics.com/v2
   Format:   JSON over HTTPS, UTF-8
   Version:  set in the path; v1 is supported until 2027-06-30

2. 02

   Authentication

   How to get a key, where it goes in the request and how to keep it safe. Show the exact header. Say what scopes exist and what a 401 and a 403 mean.

   bashCopy

   curl https://api.harbor-analytics.com/v2/projects \
     -H "Authorization: Bearer $HARBOR_API_KEY"

3. 03

   Quickstart

   One complete task in five minutes or less: create a key, make a request, read the response. Use a real endpoint and show the real response, trimmed.

   • Create an API key in Settings, then API keys
   • Export it as an environment variable
   • Call GET /projects and read the id of your first project
   • Send one event to POST /events and see it in the dashboard

4. 04

   Errors

   One error format used everywhere, a table of status codes and what to do about each, and a list of the error codes your API returns. Developers search this page more than any other.

   jsonCopy

   {
     "error": {
       "code": "project_not_found",
       "message": "No project with id prj_8f2k exists in this workspace.",
       "request_id": "req_01HF3Z9Q"
     }
   }

5. 05

   Pagination

   Say which style you use (cursor or offset), the parameter names, the default and maximum page size, and how to tell that you reached the last page.

   textCopy

   GET /v2/events?limit=100&starting_after=evt_7Hk2
   
   # response includes
   "has_more": true,
   "next_cursor": "evt_9Lp4"

6. 06

   Rate limits

   The limits per key, the headers that report usage, what happens when a client goes over (usually a 429 with Retry-After) and the recommended retry strategy.

   • Requests per minute per key
   • X-RateLimit-Remaining and X-RateLimit-Reset headers
   • 429 responses include Retry-After in seconds
   • Retry with exponential backoff and jitter

7. 07

   Webhooks

   Which events you send, the payload shape, how to verify the signature, the retry schedule and how to replay a delivery. Include a verification snippet in at least one language.

8. 08

   Endpoint reference

   One entry per endpoint with the same layout every time: method and path, a one-line description, parameters with types and whether they are required, an example request, an example response, and the errors it can return.

   markdownCopy

   ## Create a project
   POST /v2/projects
   
   | Field    | Type   | Required | Description            |
   |----------|--------|----------|------------------------|
   | name     | string | yes      | Shown in the dashboard |
   | timezone | string | no       | IANA name, default UTC |
   
   Returns 201 with the project object.
   Errors: 400 invalid_timezone, 409 name_taken

9. 09

   Changelog and deprecations

   Dated entries for every change that a client might notice, with breaking changes marked clearly and a migration note. State your deprecation policy (for example, twelve months notice).