Skip to content

API Changelog

C.O.S. API v1

All notable changes to the C.O.S. API contract are documented here. This changelog covers the public API surface only. Internal implementation changes are recorded in the C.O.S. governance log (INSTALL_LOG.md).

v1-stable — 2026-06-10

Status: Active. This is the current production version.

Frozen at Gate 58-5A (CAND-2026-147)

The C.O.S. Public API spec (COS_PUBLIC_API_SPEC.yaml) was frozen at Gate 58-5A on 2026-06-10. No breaking changes are permitted against this frozen contract. All subsequent gate work targets implementation conformance and developer tooling.

Endpoints

  • GET /health — service health check (unauthenticated)
  • GET /version — API version info (unauthenticated)
  • GET /organisations — list organisations (platform key required)
  • POST /organisations — create organisation (platform key required)
  • GET /organisations/{id} — get organisation
  • PUT /organisations/{id} — full update
  • PATCH /organisations/{id} — partial update
  • GET /organisations/{id}/members — list members
  • GET /organisations/{id}/api-keys — list API keys
  • POST /organisations/{id}/api-keys — issue API key
  • GET /organisations/{id}/api-keys/{key_id} — get key record
  • DELETE /organisations/{id}/api-keys/{key_id} — revoke key

Authentication

API keys use the format cos_live_<48 chars> (production) or cos_test_<48 chars> (test). Keys are org-scoped. Both prefixes are registered with GitHub secret scanning.

Rate limiting

  • Authenticated: 60 requests/minute per organisation (fixed-window, per-org).
  • Unauthenticated (/health, /version): 60 requests/minute global. Added at Gate 59-2 (CAND-2026-151, 2026-06-10).
  • 429 responses use RFC 7807 Problem Details (application/problem+json) with cos_error_code: RATE_LIMIT_EXCEEDED and retry_after field.
  • Redis fail-open: limits are unenforced during Redis unavailability.

Error format

  • All errors except 429: application/json with error, message, details.
  • 429: application/problem+json (RFC 7807) with type, title, status, detail, cos_error_code, retry_after, instance.

Known implementation limitations

ID Severity Description
BUG-005 LOW Unauthenticated rate limit is global-only; no per-IP limit. Phase 60 deadline.
BUG-006 MEDIUM CLOSED (CAND-2026-155, 2026-06-10). cos_app INSERT GRANT was already present on cos_governance_events; register was not updated when fix was applied. Confirmed resolved.

Pre-stable history

API development history prior to v1-stable is preserved in the C.O.S. governance archive (09_archive/). The stable contract freeze at Gate 58-5A supersedes all prior draft versions.