API Council

Last updated Jun 14, 2026

The Matter API Council is the human design-review forum for every new or modified endpoint. Its job is to defend the ten design principles and ensure consistency across the surface area. CI gates catch the mechanical cases (Spectral spec lint, oasdiff backwards-compat, drift gates); the Council catches the judgment cases that only a human can.

Three gates an endpoint passes through before it sees production traffic:

1. Spec draft review — asynchronous PR review on the spec change.
2. Council weekly forum — synchronous discussion for non-trivial endpoints.
3. Production-readiness review — before any endpoint promotes Preview → Beta or Beta → GA.

Gate 1 — Spec draft review

Every endpoint starts with a spec PR — apps/docs/api-reference/openapi.yaml is updated before any code is written. The PR triggers:

• Automated checks. Spectral lint, oasdiff backwards-compat, codegen drift, request-validator generation. Must all be green.
• Asynchronous reviewers. At least one reviewer from each bounded context the endpoint touches. The bounded-context owner has primary review responsibility.
• Review focus. Naming, shape, idempotency semantics, error codes, lifecycle phase placement, MCP exposure decision, explainer quality, data classification per field, encryption per field, cost budget, SLO class, cache layer, rate limit, quota tier.

Reviewers comment on the PR. If the endpoint is straightforward and reviewers approve, the PR merges without going to the Council. If reviewers raise non-trivial design questions, the PR is escalated to the Council forum.

The author may also voluntarily request Council review for any endpoint they judge non-trivial.

Gate 2 — Council weekly forum

A 30-minute synchronous slot per week. Format:

• Attendees. At least one engineer per bounded context. The CTO chairs (or delegates).
• Agenda. Spec PRs escalated from gate 1 plus open architectural questions.
• Process per endpoint. Author walks through the spec PR. Reviewers ask questions, propose changes, or vote.
• Outcomes. approve (merge as-is), revise (author iterates on specific changes), escalate (deeper architectural discussion needed, often becomes an RFC), reject (endpoint not approved).
• Minutes. Recorded at apps/docs/process/council-minutes/<yyyy-mm-dd>.mdx. Decisions and their reasoning are durable.

Endpoint authors do not need to attend the Council if their spec PR passes gate 1 without escalation.

Gate 3 — Production-readiness review

Before any endpoint promotes from Preview → Beta or Beta → GA, it passes a production-readiness review. The review is documented at apps/api/__gates__/prod-readiness/<operation_id>.md. Checklist:

1. SLO measurement. Endpoint has been load-tested under realistic concurrency; measured p50/p99/p999/p9999 sit at or below the operation class budget.
2. Cost budget. Endpoint's measured cost-per-request is at or below the declared budget in apps/api/lib/cost-budgets.ts.
3. Error-rate baseline. Endpoint's measured error rate is at or below its SLO.
4. Test coverage. All ten test layers from the per-resource pattern are present and green.
5. MCP exposure decision. Either exposed with documented tier or marked x-matter-mcp.never_expose: true with rationale.
6. Deprecation plan. If the endpoint replaces an existing one, the deprecation plan for the old endpoint is documented with the Sunset date.
7. Runbook. For high-stakes endpoints (composite atomic flows, dissolution, rotation), a runbook exists at apps/docs/content/docs/runbooks/.
8. Known failure modes. Each documented with the alert + the runbook + the recovery procedure.
9. Customer comms. For Beta → GA, the announcement plan (status page entry, customer email, changelog entry, docs cross-links).
10. Sign-off. CTO + bounded-context owner + on-call lead.

Promotion happens only after sign-off. The endpoint's x-matter-maturity is updated in the spec.

Endpoint maturity ladder

The maturity ladder is enforced by the maturity-gate middleware:

Promotion direction is one-way: Preview → Beta → GA. Demotion (e.g., a GA endpoint discovered to have an architectural flaw) is a SEV3 event with explicit customer comms.

RFC process

Cross-team architectural changes (a new bounded context, splitting an existing context, introducing a new external dependency, changing a load-bearing primitive) are captured as RFCs at apps/docs/rfcs/<yyyy-mm-dd>-<slug>.mdx.

RFC structure:

• Motivation. Why this change. What problem it solves. What goes wrong if we do not.
• Proposal. Concrete change. New files. Modified files. New invariants. Removed invariants.
• Alternatives considered. What was considered and rejected, and why.
• Implementation plan. Phased rollout. Test plan. Migration plan.
• Risk + mitigation. What might go wrong. How we recover.

RFC approval requires ≥ 3 reviewers including ≥ 2 from affected bounded contexts. The Council discusses the RFC in a weekly slot before approval.

Why we have this process

Three reasons.

1. Consistency across 272+ operations. Without a forum, every endpoint becomes a snowflake. The shape of the API drifts. Customers lose the muscle memory of "I already know how to use this endpoint family." With the forum, every new endpoint inherits the conventions; the surface stays predictable.

2. Catch design problems before code. Spec PRs are cheap to revise; code PRs are expensive. The Council exists to catch the "this should be POST /entities/{id}/dissolve, not POST /entities/{id}/dissolution, because dissolution is the verb and dissolution-the-noun-resource is Dissolution" disagreements early.

3. Build institutional design knowledge. The Council minutes accumulate. New engineers read past decisions to understand why the API looks the way it does. The bus factor of "what is the right shape for this endpoint" goes from 1 (the original API designer) to N (every Council attendee).

See also

• API design philosophy — what the Council defends.
• API review checklist — the ~80-item mechanical checklist.
• Deprecation policy — how the Sunset side of the maturity ladder works.
• Ownership matrix — who's a Council attendee.