API REFERENCE
COSMOS API
Raw contracts: openapi.yaml (OpenAPI 3.1) and asyncapi.yaml (AsyncAPI 3.0). Errors are RFC 9457 problem+json with a COSMOS error code; every answer carries X-Request-Id.
HTTP operations
| Method | Path | Area | What it does |
|---|---|---|---|
POST | /mcp | mcp | Send one JSON-RPC message (MCP Streamable HTTP) |
GET | /mcp | mcp | Open the server-to-client SSE stream (notifications/tools/list_changed, notifications/resources/updated) |
DELETE | /mcp | mcp | End the MCP session |
GET | /.well-known/oauth-protected-resource | oauth | Protected resource metadata (RFC 9728) |
GET | /.well-known/oauth-protected-resource/mcp | oauth | Protected resource metadata for /mcp (RFC 9728 path-suffixed form) |
GET | /.well-known/oauth-authorization-server | oauth | Authorization server metadata (RFC 8414) |
GET | /oauth/authorize | oauth | Start authorization (redirects to TheOneApp sign-in) |
GET | /oauth/callback | oauth | Sign-in provider callback; shows the consent page |
POST | /oauth/consent | oauth | Approve or deny the authorization |
POST | /oauth/token | oauth | Exchange a code or refresh token (RFC 6749, PKCE RFC 7636, resource RFC 8707) |
POST | /oauth/register | oauth | Dynamic client registration (RFC 7591); new clients start pending |
POST | /oauth/revoke | oauth | Revoke a token (RFC 7009) |
GET | /signin | pages | Sign in to COSMOS's own pages |
GET | /confirm/{id} | pages | Show a pending confirmation (what the agent wants to do) |
POST | /confirm/{id} | pages | Approve or deny (CSRF-protected form) |
GET | /v1/tools | tools | List the tools you can call (same use case as MCP tools/list) |
POST | /v1/tools/{name}/calls | tools | Call a tool (same pipeline as MCP tools/call) |
GET | /v1/jobs/{id} | jobs | Job status and result |
POST | /v1/jobs/{id}/cancel | jobs | Cancel a job (idempotent) |
GET | /v1/plugins | plugins | List plugins (cursor-paginated) |
POST | /v1/plugins | plugins | Create a plugin (plugins:admin) |
GET | /v1/plugins/{name} | plugins | |
PUT | /v1/plugins/{name}/versions/{version} | plugins | Publish an immutable manifest version (plugins:admin; idempotent by URL) |
POST | /v1/plugins/{name}/versions/{version}/distributions/{target} | plugins | Render the package for one client target and record it as pending |
PATCH | /v1/admin/clients/{id} | admin | Activate, pend or disable an OAuth client; set redirect URIs (cosmos:admin) |
PATCH | /v1/admin/models/providers/{id} | admin | Models leg kill switch for one provider (cosmos:admin) |
GET | /v1/admin/audit/verify | admin | Re-compute the audit hash chain (cosmos:admin) |
GET | /errorlord | pages | ErrorLord console (admins) |
GET | /bridge/connect | mcp | Browser bridge WebSocket upgrade (AsyncAPI channel bridge) |
GET | /{$} | site | Public front page (gateway story |
GET | /docs | site | Developer docs index |
GET | /docs/quickstart | site | Quick start per client plus bridge and extension downloads |
GET | /docs/auth | site | OAuth 2.1 guide (metadata URLs |
GET | /docs/tools | site | Tool catalog from the live registry (no endpoints) |
GET | /docs/api | site | This API reference |
GET | /docs/changelog | site | Changelog |
GET | /status | site | Friendly status page (readiness checks and leg health) |
GET | /tools.json | site | Public tool catalog as JSON (namespace, status, tools with input schemas; never endpoints) |
GET | /openapi.yaml | site | This document |
GET | /asyncapi.yaml | site | The AsyncAPI document |
GET | /downloads/{file} | site | A release artifact of this build (allow-listed names only) |
GET | /assets/{file} | site | Page stylesheet and script |
GET | /favicon.svg | site | Favicon |
GET | /site.webmanifest | site | Web app manifest (site name cosmic-mcp) |
GET | /favicon.ico | site | Favicon (same SVG) |
GET | /robots.txt | site | Robots rules (allow / and /docs) |
GET | /sitemap.xml | site | Sitemap of the public pages |
GET | /home | site | Signed-in home (connections, legs and health, tools, own activity; admins - pending clients and audit verify) |
POST | /home/connections/{family}/revoke | site | Disconnect one of your own clients (revokes its refresh and access tokens) |
POST | /home/clients/{id}/decision | site | Admins approve (active) or deny (disabled) a pending client |
POST | /home/audit/verify | site | Admins re-compute the audit hash chain (first 10,000 entries) |
POST | /signout | site | Sign out of COSMOS's pages |
POST | /v1/veritas/verify | veritas | Anonymous public verify of one Veritas receipt (spec - Verify needs no account) |
GET | /extensions/privacy | site | Privacy policy of the Cosmic Unicorn and Cosmic Chariot browser extensions |
GET | /healthz | ops | Liveness |
GET | /readyz | ops | Readiness (database, legs, config) |
GET | /errors | site | Public error code registry (problem+json type URLs point here) |
GET | /metrics | ops | Prometheus text metrics (loopback / tunnel only) |
Channels and events
| Channel | Address | About |
|---|---|---|
| bridge | /bridge/connect | |
| auditRecorded | cosmos.audit.recorded.v1 | One per audited call. Key user_id (per-user ordering). Retry topic cosmos.audit.recorded.v1.retry, DLQ cosmos.audit.recorded.v1.dlq. |
| jobUpdated | cosmos.job.updated.v1 | Job status changes. Key job_id. Retry + DLQ as above. |
gRPC for internal services
Services on the TheOne network can call the same use cases over gRPC (cosmos.gateway.v1.Gateway) with a client-credentials token. Ask a COSMOS administrator for a service client.