Platform API v1

Status: live contract for the implemented Platform API resources.

The Platform API is the JSON surface under /api/v1 for Human personal settings and system settings. System settings under /api/v1/admin are visible and usable only by an active Human owner/admin; personal settings do not require that role. The resource pages below describe the implemented requests, responses, authority rules, and lifecycle behavior of each endpoint family.

In browser interfaces, this family serves settings pages only. Conversation and other Agent work use the Agent application's control surface and its Agent API client. cmctl is a CLI consumer of the Platform API's settings capabilities. Each caller still uses the credentials and authority required by the resource; the page displaying a setting does not grant access.

Requests

Examples use Authorization: Bearer <credential> and Accept: application/json. Requests with JSON bodies also send Content-Type: application/json. The platform family uses Rails HTTP-token grammar, so Token is accepted as an alternative scheme; Bearer is the recommended form.

Resource public_id fields and member IDs in routes are UUIDv7 strings. Provider IDs and model references are catalog names, such as openrouter and openrouter/provider/model. Fields ending in *_at are ISO8601 UTC timestamps.

Authentication

The live Platform API accepts these credentials:

• An API-kind Session bearer beginning with sk-cybros-session-v1-.
• A member access token beginning with sk-cybros-api-v1- only when its mint-frozen credential plane is platform and its owning member is currently an active Human. Application OAuth and personal tokens use this plane; /api/v1/admin additionally requires the current owner/admin role.
• A same-origin browser Session cookie for safe GET and HEAD requests only. Cookie authentication never authorizes a Platform API mutation because this JSON family has no CSRF protection. A browser Session whose Identity still requires a password change is rejected with 401; Platform JSON responses never redirect to the web password-change page.

Application OAuth login is documented in Application login. A member-plane access token belongs to /agent_api/v1, not this family. The plane is one value fixed at mint, so no token can ever authorize both families, and a later role change never re-aims an existing token.

Authentication is evaluated on every request. Expired, revoked, authority- fenced, recovery-fenced, wrong-family, and otherwise unusable credentials return 401 Unauthorized. When an Authorization header is present, it is the authoritative authentication attempt: failure returns 401 immediately and never falls back to a browser cookie. A safe request considers its browser cookie only when the header is absent.

Protected-resource authentication failures include WWW-Authenticate: Bearer realm="Nexus" and the unauthorized JSON error. Session creation reports its own credential and policy failures as documented on the Session page.

Errors

Controller-handled failures use one JSON envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

Malformed JSON returns the JSON 400 bad_request envelope. Malformed query strings fail in Rails before controller dispatch; Rails returns 400, but the body and media type are not a stable Platform API contract. An endpoint may document additional stable codes. A transport rate-limit response is 429 with code rate_limited and a Retry-After header whose value is a whole number of seconds.

Unhandled application failures and proxy failures may return a JSON, non-JSON, or empty 5xx body. Clients must tolerate each representation and use the HTTP status to recognize the failure. A failed connection or 5xx does not prove that a write was rejected: follow the resource's documented readback or idempotency behavior before repeating a mutation.

Read semantics

Platform GET resource actions are observational and operationally bounded. Successful member access-token authentication may refresh the token's non-authoritative last_used_at sample at most once per hour; the resource action itself does not extend or rotate credentials, perform external I/O, repair state, or drive background work. Reading a Session never extends its fixed absolute expiry.

Deployment administration is a bounded local-IPC exception: its reads observe the separate installation owner's durable state through a private Unix socket. They do not contact a registry, run Docker, or advance an upgrade.

Resources

• Session — create, inspect, and revoke the presented API Session.
• Profile — inspect the acting member and the presented credential's plane.
• Persona: the authenticated Human's durable prompt document.
• Admin Users — Human-authorized member removal.
• Admin Deployment — inspect Nexus releases and accepted Nexus upgrades.
• Admin Budgets — the budget ledger's three doors (open, adjust, revoke) and the configure-once account cost unit they require.
• Admin Models — provider and model definitions, model availability and visibility, provider enablement, and write-only API-key management.
• Account Retention — configurable execution-detail cleanup while retaining conversation text.
• Admin Model Usage — recorded usage and cost statistics; reports do not change budgets or settlement.
• Provider subscription authorization: current/exact session reads, start/resume, explicit restart and clear through Human administration.