[alukach]

Follows #667, now merged. Writes down the API conventions this round of PRs settled on, so the next endpoint follows them without anyone reconstructing them from the code.

What

• API.md at the repository root, beside CONTRIBUTING.md:
  • One operation, thin adapters: what an operation decides, what a route and a server action may do, and the exceptions for routes no session can call.
  • Documented where it's defined: registerPath beside the handler, the coverage test and its UNREGISTERED allowlist, published prose, explicit HEAD, bearer and optionalBearer, internal, and deprecated.
  • Resources and methods: URL and field naming, and a table of what each method means and answers. Deactivating is PATCH { "disabled": true }, never DELETE, and one resource has one edit endpoint.
  • Lists: {items, next_cursor}, never a bare array.
  • Errors: the shared shape and when each status applies, the 500 internal error and the trust exchange's {trusted: false} 403, authorizing before validating where the permission doesn't depend on the input, and answering 404 for things the caller may not know of.
  • Writes: carry only the fields that changed, and what accountsTable.update always writes.
  • Compatibility: the data proxy is pinned by a test, the CLI follows the reference, and anyone else gets a traffic check, then deprecation rather than removal.
• CLAUDE.md (and AGENTS.md, which links to it) gets a short API section telling an agent to read API.md before touching /api/v1.
• CONTRIBUTING.md's "Server Actions & API Routes" paragraph said both call isAuthorized() themselves. It now describes them as adapters over one operation and points at API.md.

Where it lives

A root API.md rather than more of CLAUDE.md: these are conventions for whoever writes an endpoint, person or agent, and much of it is visible in the code once you know where to look, which is what CLAUDE.md says it isn't for. CLAUDE.md carries the pointer, so agents still load it at the right moment. CONTRIBUTING.md links to it.

Merge order

The guide describes the API as it stands once the open PRs from this round merge, and names things they add:

• optionalBearer, internal and deprecated endpoints (feat(api): accounts, whoami and the internal routes on the ops layer #667)
• data-proxy-contract.test.ts (test(api): pin the endpoints the data proxy calls #671)
• explicit HEAD (feat(api): document HEAD /products/{account_id}/{product_id} #672)
• pageSchema and onePage (feat(api): answer the membership lists a page at a time #673)
• one PATCH per account (feat(api): edit every account with PATCH /accounts/{account_id} #674)
• DELETE that only deletes (feat(api)!: one endpoint per account: DELETE only deletes; profile and flags fold into /accounts/{account_id} #675)

Merge it after them, or trim the line that names whichever of them doesn't land.

Where the code doesn't follow the guide yet

The guide states the conventions, not the code's progress toward them. Known gaps, tracked outside the docs:

• The /data-connections routes and the data-connection actions still read tables and call isAuthorized() directly: API: data connections, including account-owned ones #593.
• The credentials, profile-image and createAccount actions still call isAuthorized() directly: API: accounts, organizations and profiles #592 and API: service accounts and their trusts #594.
• updateProduct, deleteProduct and updateMembership validate the body before authorizing, so a caller who may not act sees field errors instead of a 403.
• accountsTable.update always writes name, type and whole metadata maps, so updateAccount can undo a concurrent edit.

Docs, ADRs and llms.txt

Repository-internal guidance only: no user-facing flow changes, so docs.source.coop and llms.txt are unaffected, and it records no decision shared with the data proxy beyond the existing contract test, so no data.source.coop ADR changes.

Testing

Documentation only; no code changed. Each claim in API.md was checked against the code after a review pass found several the code didn't hold to (route-coverage.test.ts, accountsTable.update, withApiSession's error handling, the revocations and trust-exchange routes). Checked that AGENTS.md still resolves to CLAUDE.md and that the prose in API.md wraps at 80, as the repository's Markdown does.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
source-coop-ui	Ready	Preview	Oct 16, 2026 2:55am UTC
source-cooperative	Ready	Preview	Oct 16, 2026 2:55am UTC

[claude]

Claude finished @alukach's task in 16s —— View job

---

✅ No blocking issues — safe to merge.

This is a documentation-only PR (API.md, plus pointers in CLAUDE.md and CONTRIBUTING.md). I read the diff but did not check each API.md claim against the code. The PR description says that was done.

• Merge order. API.md names things from feat(api): accounts, whoami and the internal routes on the ops layer #667, test(api): pin the endpoints the data proxy calls #671, feat(api): document HEAD /products/{account_id}/{product_id} #672, feat(api): answer the membership lists a page at a time #673, feat(api): edit every account with PATCH /accounts/{account_id} #674 and feat(api)!: one endpoint per account: DELETE only deletes; profile and flags fold into /accounts/{account_id} #675. The PR description already says to merge it after them, or trim the lines for any that don't land. Check that before merging.
• CONTRIBUTING.md:87 (non-blocking). The rewritten paragraph drops two pieces of guidance the old one had. Server actions validate with Zod and call revalidatePath() after mutations, and API routes use http-status-codes. If the first still applies to the adapters, it is worth one clause. Otherwise the loss is fine, since validation now lives in the operations.
• API.md Writes section (non-blocking). It documents the known accountsTable.update race, which is honest. It will go stale once the helper is fixed. The same applies to the "naming the operations that don't yet" note in Errors. Both are present-tense descriptions of current behaviour, so they fit CLAUDE.md's comment rule, but they need updating when the code changes.

Simplify (ponytail)

• API.md Documented-where-defined, HEAD bullet: the export { GET as HEAD } slips-past-the-test aside describes a test gap. Fix the coverage test to catch it and drop the sentence.
• CLAUDE.md API section: the second sentence only restates the API.md headings. Cut it to the first sentence.
  · branch docs/api-conventions

---

💰 Estimated review cost: $0.11 · 0m16s · 4 turns