f1fbe0e29a
Archived 4 completed OpenSpec changes (2026-04-02): - phase-3-enterprise (100/100 tasks) — 6 Phase 3 capabilities synced - devops-documentation (48/48 tasks) — 3 new + 1 merged capability - bedroom-developer-docs (33/33 tasks) — 4 new capabilities synced - engineering-docs (superseded by 2026-03-29 archive) — no tasks Main spec library grows from 21 → 35 capabilities (+14 new): federation, multi-tenancy, oidc, soc2, w3c-dids, webhooks, database, operations, system-overview, api-reference, core-concepts, developer-guides, quick-start + deployment (merged additive requirements) Active changes: 0 — project board is clear for Phase 4 planning. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.4 KiB
ADDED Requirements
Requirement: API reference exists at docs/developers/api-reference.md
The system SHALL provide a human-readable API reference at docs/developers/api-reference.md covering all 14 endpoints across the four services: Agent Registry, OAuth 2.0 Token, Credential Management, and Audit Log.
Scenario: Developer finds any endpoint within 10 seconds
- WHEN the developer opens the API reference
- THEN they SHALL find a table of contents at the top linking to each of the four service sections
Requirement: Every endpoint is documented with method, path, description, and auth requirements
For each of the 14 endpoints, the reference SHALL document: HTTP method, path, one-sentence description, and whether Bearer token auth is required.
Scenario: Developer knows which endpoints require authentication
- WHEN the developer scans the reference
- THEN they SHALL clearly see which endpoints require a Bearer token (all except POST /token) and which do not
Requirement: Every endpoint includes a complete curl example
For each endpoint, the reference SHALL include at least one complete, runnable curl example with real placeholder values.
Scenario: Developer copies a curl example and runs it
- WHEN the developer copies a curl example from the reference
- THEN the command SHALL be complete — no ellipses, no
..., no missing flags — requiring only substitution of their own agentId, token, and base URL
Requirement: Every endpoint documents all request parameters and body fields
For each endpoint that accepts a request body or query parameters, the reference SHALL list every field with: name, type, required/optional, description, and validation constraints.
Scenario: Developer knows what fields are required for POST /agents
- WHEN the developer reads the POST /agents section
- THEN they SHALL see a table listing every field, its type, whether it is required, and any constraints (e.g. email format, max length)
Requirement: Every endpoint documents all response codes and response body schemas
For each endpoint, the reference SHALL document every possible HTTP response code (2xx and 4xx/5xx) with a description and example response body.
Scenario: Developer understands a 429 response
- WHEN the developer reads the rate limit error documentation
- THEN they SHALL understand what triggered it, what the X-RateLimit-* headers mean, and when they can retry
Requirement: API reference includes a base URL and versioning section
The reference SHALL include a section at the top explaining the base URL convention, port configuration, and that all endpoints are unversioned in Phase 1.
Scenario: Developer knows where to send requests
- WHEN the developer reads the base URL section
- THEN they SHALL see the default base URL (http://localhost:3000), how to change the port via environment variable, and a note that versioning will be introduced in Phase 2
Requirement: API reference includes an errors section
The reference SHALL include a dedicated errors section listing all standard error response shapes, all custom error codes, and their HTTP status code mappings.
Scenario: Developer handles an AgentNotFoundError
- WHEN the developer reads the errors section
- THEN they SHALL see the exact JSON shape of the error response, the error code string, and the HTTP status (404)