---
# collection: one file = one collection; use kebab-case
collection: <kebab-name>
# protocol: rest | graphql  (v1; mcp reserved for v1.1)
protocol: rest
# vault: secret store backend — keychain (macOS default) | age | op | env
vault: keychain
# env: base URLs, selected with --env (default: first key)
env:
  prod: https://api.example.com
  staging: https://staging.api.example.com
# vars: non-secret defaults, overridable with --var NAME=value
vars:
  per_page: 20
---

<!--
🤖 Agent: read first — delete this block and all per-section guidance comments once the
collection is real.

Copy this file to <name>.api.md, fill the placeholders, and delete this header.
See MISSIVE.md for the full contract.
Pick your protocol shape and auth scheme from `MISSIVE-PATTERNS.md` and drop them into the Request block below.

  • One file = one collection.  Each ## heading = one endpoint.

Three reference types — the only forms that belong in Request blocks:
  {{env}}         — base URL for the selected --env; renders before the request fires.
  {{var:NAME}}    — non-secret input; renders from --var / frontmatter vars: / prompt.
  {{vault:NAME}}  — secret; NEVER renders into the file, diff, or transcript.

THE VAULT RULE — non-negotiable:
  The Markdown holds references, never values. Fire authenticated requests with:

    scripts/vault.sh exec NAME -- sh -c '...curl..."$NAME"...'

  The secret is injected into the subprocess and never lands in a file, diff, or transcript.
  Never paste a secret value into a collection.
  Never run a bare `scripts/vault.sh get` and capture its output into context.

Fill in: Request (required) + Checks; keep Mock for offline dev; grow the Notebook as you learn.
Delete this header and the per-section guidance comments once the collection is real.
-->

# <Service> — <Area>

> One line: what this collection covers and the auth it needs (e.g. Bearer API token, scope X).

---

<!-- This is the one canonical shape. The Request fence + auth line are swappable — see MISSIVE-PATTERNS.md for REST/GraphQL/webhook/Action shapes and the auth recipes. -->
## GET /path — <short label>

<!-- Request: required. Use {{env}} for the base URL, {{var:NAME}} for non-secrets,
     and {{vault:NAME}} for secrets — a reference only, never a literal value. -->
**Request**
```http
GET {{env}}/path?page={{var:per_page}}
Authorization: Bearer {{vault:API_TOKEN}}
```

<!-- Checks: jq-style assertions run after a Run. One per line. -->
**Checks**
- `status` == 200
- `.result` is an array
- `.result | length` > 0

<!-- Mock: canned JSON served by "missive mock" on this route for offline dev. No vault access needed. -->
**Mock**
```json
{ "result": [{ "id": "1", "name": "example" }] }
```

<!-- Notebook: append-only log — never delete or edit existing lines.
     Entry shape: - <emoji> <bucket> <YYYY-MM-DD[Thh:mm:ssZ]> — <text>
     Buckets: state | caveat | outcome  (see MISSIVE.md §Maintaining the Notebook). -->
**Notebook**
- 📋 state <YYYY-MM-DD> — collection scaffolded; pending first live run.
- ✅ outcome <YYYY-MM-DD> — <what a run proved about the response shape>
- ⚠️ caveat <YYYY-MM-DD> — <something surprising or environment-specific>

<!-- Base (optional): per-endpoint base URL override — overrides the frontmatter env map for
     this endpoint only. Include as a bold paragraph if needed:
     **Base** https://special.api.example.com -->

---