2.4 KiB
API Documentation
Status: Scaffold only. The canonical gateway contract has not yet been migrated into this directory.
This directory is the single API documentation boundary. OPENAPI.yaml will be the machine-readable contract, and ENDPOINTS.md will provide the human-readable endpoint, authentication, permission, and error index. Neither file exists here yet; do not describe this scaffold as a complete API reference.
Start here
- Documentation atlas — placement rules and source-of-truth boundaries.
- Documentation sitemap — current API transition status and authority-gated backlog.
- Documentation catalog audit — current API artifact inventory and migration evidence.
Contract map
| Artifact | Purpose | Status |
|---|---|---|
OPENAPI.yaml |
Canonical machine-readable HTTP/WebSocket API contract. | Planned; not present yet. |
ENDPOINTS.md |
Human index for endpoint behavior, auth, permissions, and errors. | Planned; not present yet. |
../openapi-tess.yaml |
Legacy Tess-scoped OpenAPI artifact with 17 paths. | Migration candidate; not the complete gateway contract. |
A contract migration must verify paths, schemas, authentication, permissions, error behavior, and generated/client references before the legacy artifact is retired. Keep scoped contracts explicitly labeled if they remain alongside the consolidated contract.
Authoring boundary
New API contracts belong here. Use OPENAPI.yaml for machine-readable authority and ENDPOINTS.md for human-readable constraints that OpenAPI cannot fully express. Guide books may explain usage workflows, but must link back to this directory rather than copying endpoint definitions.