0006 · The headless API reads and does not write
- Status: Accepted
- Date: 2026-10-04
Context
Systems and agents need the record without a browser: status for a portal, events for an automation, the agreement for a consumer, the ontology for an agent. A token that could also write would be a way around every gate in 0005.
Decision
/api/v1 is GET-only, plus MCP's single POST whose tools read. It sits behind its own
door — a service token, required on every deployment, that opens nothing outside
/api/v1. Tokens are shown once, stored as SHA-256, one live per name, and their
issue and revocation are audit events. One list, api_v1.ENDPOINTS, builds the routes,
the OpenAPI document and the in-app documentation.
Consequences
Integrations can poll status and events and agents can query the record safely. Anything that should act still happens in the application. Writes, when they come, need a decision of their own: agents propose, only people close gates.