Skip to main content
OpenCluster serves JSON over the versioned /api/v1 product API. The canonical contract is api/openapi.yaml; generated operation pages provide request builders, schemas, responses, and cURL examples. Set the base URL for your deployment:

​
Authentication

Normal product routes authenticate with the opaque __Host-oc_session cookie issued by local sign-in or generic OIDC. General bearer API tokens are not shipped in OSS v0.1. Do not write the session value to generated-client logs. Bootstrap is the only product setup request that accepts the one-time deployment credential as an Authorization: Bearer value. Webhook credentials authenticate only their /webhooks/v1 routes. Unsafe cookie-backed requests also require an Origin header exactly matching the configured public URL. Same-origin browser clients let the cookie jar manage the HttpOnly, Secure session cookie.
Generated cURL examples currently omit this header because the canonical OpenAPI contract records the requirement only as an extension. For POST, PUT, PATCH, and DELETE product requests authenticated by the session cookie, add --header "Origin: $OPENCLUSTER_URL". Without it, OpenCluster returns 403.

​
Organization identity

Each authenticated User belongs to one Organization. The server resolves that Organization and Role from the current session before it serves a protected operation. You can inspect the resolved identity with:
Then call an Organization-owned operation without supplying an Organization selector:
The Organization is never selected by a request header, body, query, or path value.

​
Versioning

Public product operations use /api/v1. Inbound provider routes use /webhooks/v1 and have separate authentication, payload, and retry contracts. Health, readiness, metrics, and Relay gRPC traffic are not part of the product OpenAPI surface. OSS v0.1 is pre-release. Use the OpenAPI document shipped with the exact source or release you deploy; do not assume compatibility from a latest URL.

​
Pagination

Collection operations document a bounded limit and an opaque cursor such as after or cursor. Pass the returned next value unchanged to the parameter named by that operation. An empty or null next means the collection is complete. Do not decode a cursor or construct one from a resource ID.

​
Errors

JSON errors contain a safe error message and may include a stable reason or required Permission. Use the HTTP status and request identifier for diagnosis; do not parse the message text to make authorization decisions. Responses containing Organization data use Cache-Control: no-store.

​
Webhooks

The canonical alert path is POST /webhooks/v1/integrations/{integration}/alert-events. The Integration selects the provider adapter. Generic Webhook and Alertmanager use the one-time X-OpenCluster-Token; Slack uses its signed provider request. 202 Accepted means a delivery is durable, and an exact retry of an accepted lifecycle phase returns 200 OK. Correct 400, 401, and 413 responses before retrying. Alert webhooks use 503 for temporary admission pressure so Alertmanager retries them; retry with bounded backoff and honor Retry-After when present. Slack admission pressure remains 429. Use Generic Webhook or Prometheus Alertmanager for sender setup. Alert deliveries finish during admission. Admins can recover terminal Slack processing by Conversation and Message sequence through the Slack recovery operation.

​
Investigation event streams

Investigation activity uses increasing sequence identifiers. SSE clients reconnect with Last-Event-ID; comment frames are heartbeats and carry no product event. Store the last processed sequence only after handling its event successfully. Streams send an idle heartbeat every 15 seconds and can stay open beyond ordinary HTTP request timeouts. Each event batch has a 10-second write deadline; a stalled connection is dropped and can reconnect using its last processed sequence. Streams close on a terminal event, an already processed terminal cursor, or server shutdown. Reconnect after shutdown to resume from durable activity. Reverse proxies must disable response buffering and allow at least 60 seconds between upstream reads. The supplied nginx configuration uses proxy_buffering off, proxy_read_timeout 60s, and send_timeout 10s to bound stalled downstream clients. Terminal events are concluded, failed, and cancelled. Ignore an unknown future event type while retaining its envelope so a newer server remains compatible with an older client. The generated stream operation documents the seven currently shipped event payloads: started, progress, Tool started, Tool completed, concluded, failed, and cancelled. These payloads carry operational display data only; hypotheses appear in the final Investigation conclusion. A refused unavailable Tool is reported as a failed read without claiming it started against an Integration. Browse the API surface or select an individual generated method/path entry in the navigation.