# HTTP API reference format

Use when an engineer publishes the reference for an HTTP API so teammates can look up an endpoint and try it.
For a generic parameter/field lookup that isn't HTTP, use `reference.md` instead.

## Great instance

- Lets a reader find one endpoint and call it correctly without reading the whole page.
- Models HTTP honestly: method + path, separate request and response bodies, status codes, auth per endpoint.
- Pairs each endpoint with a copy-pasteable request and its real response.
- Groups endpoints by resource so the section reader's sidebar mirrors the API's shape.

## Cut

- Narrative tutorials and design rationale (link a how-to or design doc instead).
- One giant flat table that flattens method, path, params, and bodies into cells they don't fit.

## Skeleton

```markdown
# <API> reference

## Overview
<what the API does; base URL; content type>

## Authentication and scopes
<scheme (bearer, key), how to send it, and the scopes each call needs>

## Conventions
<versioning, pagination, error shape, rate limits>

## <Resource> — `GET /things/{id}`
<one line on what it does>

| Param | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| id | path | string | yes | |

Response `200`:

| Field | Type | Notes |
| --- | --- | --- |
| id | string | |

| Status | Meaning |
| --- | --- |
| 200 | ok |
| 404 | no such thing |

```bash
curl -H "authorization: Bearer $TOKEN" https://api.example.com/things/42
```

## Error catalog
| Code | When | Fix |
| --- | --- | --- |

## Changelog
- <date>: <what changed>
```

## Section prompts

- One `h2` per endpoint (or per resource with `h3` endpoints) so each is its own sidebar entry and comment target.
- Keep request-body and response-body as separate tables — reviewers comment on one field.
- Show a real curl + a real JSON response; a reader copies these first.

## Renderer moves

Catalog: ../building-artifacts.md#what-each-file-type-becomes - md doc reader sections; param/body/status table cell anchors; fenced curl/JSON blocks.