Skip to main content
API reference
DocumentationAudit · console.us.ccsio.ai

Audit events

Reads of the audit chain: one event with its correlation view, a page of the chain, the head of a stream, an organization's streams and the facts of operator support access. They need `audit.read`.

Documentation menu

The descriptions of the operations and fields are the contract’s own, in English.

GET/audit/v1/events

Read one audit event with its correlation view

Credential
API key
Permission
audit.read

Reads the durable C3 audit record back by tenant and event id, served alongside the eight-dimension correlation view. An unknown event is 404 (client category).

curl
curl "https://console.us.ccsio.ai/audit/v1/events?tenant_id=<tenant_id>&event_id=<event_id>" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

tenant_id
required
querystring

The tenant identifier (C3 slug pattern).

event_id
required
querystring

The audit event identifier (C3 slug pattern).

Responses

  • 200

    The audit event and its correlation view.

    Schema
    AuditEventReadResponse
    • eventobjectrequired
      • kindstringrequired

        always "audit"

      • headerobjectrequired
        • schema_versionstringrequired

          always "c3/v1"

        • event_idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • tenant_idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • plane_instance_idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • occurred_atstringrequired

          pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

        • seqAuditSeqViewrequired
        • stream_epochstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

      • gate_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • run_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • policy_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • actor_refstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • agent_spec_digeststringrequired

        pattern ^[a-f0-9]{64}$

      • operation_digeststringrequired

        pattern ^[a-f0-9]{64}$

      • evidence_digeststringrequired

        pattern ^[a-f0-9]{64}$

      • chain_headstringrequired

        pattern ^[a-f0-9]{64}$

      • decided_atstringrequired

        pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

      • previous_chain_headstring or nullrequired

        pattern ^[a-f0-9]{64}$

      • outcomestringrequired

        Allowed values: "approved""denied""canceled""failed""observed"

    • correlationobjectrequired
      • request_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • trace_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • organization_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • session_idstring or nullrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • residencystringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • regionstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • model_idstring or nullrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • deployment_idstring or nullrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

  • 400

    Client refusal unrelated to authentication, including malformed input, a denied or failed request.

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.

    Read more

    Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)

  • 404

    The requested resource or path was not found.

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure, rendered without internal cause details.

GET/audit/v1/events/page

Read a page of the event chain

Credential
API key
Permission
audit.read

Reads a page of the event chain for a stream scope, keyset-paginated by the opaque after cursor. An unobserved scope renders an empty page, never 404.

curl
curl "https://console.us.ccsio.ai/audit/v1/events/page?tenant_id=<tenant_id>&stream_id=<stream_id>&stream_epoch=<stream_epoch>&limit=<limit>" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

tenant_id
required
querystring

The tenant identifier (C3 slug pattern).

stream_id
required
querystring

The stream identifier (C3 slug pattern).

stream_epoch
required
querystring

The stream epoch identifier (C3 slug pattern).

limit
required
queryinteger

Required. A positive integer page size. A non-integer limit renders 400 invalid-request; a value outside 1..128 renders 400 invalid-filter (the read model's page bound).

from
optional
querystring

Optional. The half-open range lower bound, [from, to): from must precede to; from-after-to renders 400 invalid-time-range, and a malformed C3 second-precision UTC form renders 400 invalid-request.

to
optional
querystring

Optional. The half-open range upper bound, [from, to): from must precede to; from-after-to renders 400 invalid-time-range, and a malformed C3 second-precision UTC form renders 400 invalid-request.

after
optional
querystring

Optional. The opaque page cursor returned by a previous page (given at most once; a second occurrence renders 400 invalid-request). A cursor minted for the other read renders 400 invalid-cursor - never a silent restart from the genesis.

Responses

  • 200

    The event chain page (an empty page for an unobserved scope).

    Schema
    AuditEventPageResponse
    • eventsarray of AuditEventReadResponserequired
      • eventobjectrequired
        • kindstringrequired

          always "audit"

        • headerAuditHeaderViewrequired
        • gate_idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • run_idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • policy_idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • actor_refstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • agent_spec_digeststringrequired

          pattern ^[a-f0-9]{64}$

        • operation_digeststringrequired

          pattern ^[a-f0-9]{64}$

        • evidence_digeststringrequired

          pattern ^[a-f0-9]{64}$

        • chain_headstringrequired

          pattern ^[a-f0-9]{64}$

        • decided_atstringrequired

          pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

        • previous_chain_headstring or nullrequired

          pattern ^[a-f0-9]{64}$

        • outcomestringrequired

          Allowed values: "approved""denied""canceled""failed""observed"

      • correlationobjectrequired
        • request_idstringrequired

          pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

        • trace_idstringrequired

          pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

        • organization_idstringrequired

          pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

        • session_idstring or nullrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • residencystringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • regionstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • model_idstring or nullrequired

          pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

        • deployment_idstring or nullrequired

          pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

    • nextstring or nullrequired
  • 400

    Client refusal unrelated to authentication, including malformed input, a denied or failed request.

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.

    Read more

    Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure, rendered without internal cause details.

GET/audit/v1/chain-heads

Read the stream's chain head

Credential
API key
Permission
audit.read

Reads the current chain head (seq and digest) for a stream scope. An unknown scope is 404 (client category).

curl
curl "https://console.us.ccsio.ai/audit/v1/chain-heads?tenant_id=<tenant_id>&stream_id=<stream_id>&stream_epoch=<stream_epoch>" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

tenant_id
required
querystring

The tenant identifier (C3 slug pattern).

stream_id
required
querystring

The stream identifier (C3 slug pattern).

stream_epoch
required
querystring

The stream epoch identifier (C3 slug pattern).

Responses

  • 200

    The stream's chain head.

    Schema
    AuditChainHeadResponse
    • tenant_idstringrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • stream_idstringrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • stream_epochstringrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • seq_nintegerrequired

      1 to 9007199254740991

    • chain_headstringrequired

      pattern ^[a-f0-9]{64}$

  • 400

    Client refusal unrelated to authentication, including malformed input, a denied or failed request.

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.

    Read more

    Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)

  • 404

    The requested resource or path was not found.

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure, rendered without internal cause details.

GET/audit/v1/streams

List a tenant's event streams

Credential
API key
Permission
audit.read

Lists the event streams a tenant has recorded events on: one entry per distinct (stream_id, stream_epoch), with the stream's last chain position (seq_n) and the occurrence time of its last event, NEWEST FIRST by that time (ties broken by stream_id then stream_epoch), so the first entry is the most recently active stream.

Read more

It exists so a console can offer the streams to pick from instead of asking for their identifiers; the identifiers it returns are exactly what the chain-head read and the event chain page take. Bounded: at most the 200 most recently active streams are returned (a tenant records on a handful). A tenant that has recorded nothing renders an empty list, never 404. Same permission and tenant binding as the event chain page (audit.read at organization level; the tenant_id query parameter is the tenant binding source, a cross-organization value is 403 tenant-mismatch at the boundary). Reads are not sensitive and record nothing.

curl
curl "https://console.us.ccsio.ai/audit/v1/streams?tenant_id=<tenant_id>" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

tenant_id
required
querystring

The tenant identifier (C3 slug pattern).

Responses

  • 200

    The tenant's streams, newest first (an empty list for a tenant that recorded nothing).

    Schema
    AuditStreamListResponse
    • tenant_idstringrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • streamsarray of AuditStreamSummaryrequired

      The tenant's streams, newest first by last_event_at.

      at most 200 items

      • stream_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • stream_epochstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • seq_nintegerrequired

        The stream's last recorded chain position (the same value the chain-head read returns).

        1 to 9007199254740991

      • last_event_atstringrequired

        The occurrence time (occurred_at) of the stream's last event, C3 second-precision UTC form.

        pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

  • 400

    Client refusal unrelated to authentication, including malformed input, a denied or failed request.

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.

    Read more

    Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure, rendered without internal cause details.

GET/audit/v1/facts

Read a page of support-access facts

Credential
API key
Permission
audit.read

Reads a page of the support-access fact stream for an organization, keyset-paginated by the opaque after cursor. An unobserved organization renders an empty page, never 404.

curl
curl "https://console.us.ccsio.ai/audit/v1/facts?organization=<organization>&limit=<limit>" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

organization
required
querystring

Required. The organization identifier (C0 ref pattern); on the facts read it is the tenant binding source, so a cross-organization value is 403 tenant-mismatch at the deployment boundary.

limit
required
queryinteger

Required. A positive integer page size. A non-integer limit renders 400 invalid-request; a value outside 1..128 renders 400 invalid-filter (the read model's page bound).

grant_id
optional
querystring

Optional. The grant identifier (C0 ref pattern) the fact page is filtered to.

from
optional
querystring

Optional. The half-open range lower bound, [from, to): from must precede to; from-after-to renders 400 invalid-time-range, and a malformed C3 second-precision UTC form renders 400 invalid-request.

to
optional
querystring

Optional. The half-open range upper bound, [from, to): from must precede to; from-after-to renders 400 invalid-time-range, and a malformed C3 second-precision UTC form renders 400 invalid-request.

after
optional
querystring

Optional. The opaque page cursor returned by a previous page (given at most once; a second occurrence renders 400 invalid-request). A cursor minted for the other read renders 400 invalid-cursor - never a silent restart from the genesis.

Responses

  • 200

    The support-access fact page (an empty page for an unobserved organization).

    Schema
    AuditFactPageResponse
    • factsarray of AuditFactrequired
      • fact_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • organization_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • project_idstring or nullrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • grant_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • revisionintegerrequired

        at least 1

      • principal_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • resource_idstring or nullrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • actionstringrequired

        Allowed values: "created""approved""denied""expired""revoked""exercised"

      • resultstringrequired

        Allowed values: "permitted""denied""effective"

      • ticketstring or nullrequired

        1 to 240 characters

      • request_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • trace_idstringrequired

        pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

      • residencystringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • regionstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • recorded_atstringrequired

        pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

      • effective_atstring or nullrequired

        pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$

    • nextstring or nullrequired
  • 400

    Client refusal unrelated to authentication, including malformed input, a denied or failed request.

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.

    Read more

    Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure, rendered without internal cause details.

Generated from the platform contracts at commit 5f833620.

Explore the platform

Get your first API key

Registration is open. Four steps to your first call: create your account, create your organization, create your API key, and start using it.

  1. 01Create your account
  2. 02Create your organization
  3. 03Create your API key
  4. 04Start using it
Create accountTalk to us