{ "openapi": "3.1.0", "info": { "title": "Orkestera External Client API", "version": "v1", "description": "Live external client operations. Deployment availability is returned by discovery. Workflow APIs are documented separately on the reference page." }, "x-orkestera-contract": { "version": "v1", "status": "stable", "schema_version": 1, "owned_prefixes": [ "/client/", "/.well-known/" ], "event_family": "client.*", "pending_scopes": {}, "principal": "Every client-chosen id (session_id, run_id, event_id) is unique only within its principal: the verified org_id, client_id and user_id claims of the token that sent it (user_id absent is its own value). Every stream, idempotency record and read-back lookup is keyed under the principal or bounded to the token's org; no body value ever selects another principal's data." }, "servers": [ { "url": "https://auth.orkestera.test", "description": "Default; each operation names its own service." } ], "paths": { "/.well-known/oauth-authorization-server": { "get": { "summary": "RFC 8414 authorization server metadata", "description": "Public OAuth metadata: issuer, token and device authorization endpoints, supported grants and scopes, and the public signing-key URL.", "x-orkestera-surface": { "service": "auth", "status": "live", "issue": null, "gate": null, "audience": null }, "x-orkestera-errors": [], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://auth.orkestera.test" } }, "description": "Auth: identity and discovery." } ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationServerMetadata" } } } } } } }, "/.well-known/jwks.json": { "get": { "summary": "JSON Web Key Set", "description": "Public signing keys for Service Token verification. Services perform authoritative signature, issuer, audience and expiry checks.", "x-orkestera-surface": { "service": "auth", "status": "live", "issue": null, "gate": null, "audience": null }, "x-orkestera-errors": [], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://auth.orkestera.test" } }, "description": "Auth: identity and discovery." } ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWKS" } } } } } } }, "/.well-known/orkestera-client-contract": { "get": { "summary": "Client-contract discovery document", "description": "Discover supported contract versions and service endpoints for this deployment. A surface that is not advertised is null. Use these URLs instead of guessing hostnames. A non-null URL does not establish your account permissions, provider configuration or service health.", "x-orkestera-surface": { "service": "auth", "status": "live", "issue": null, "gate": null, "audience": null }, "x-orkestera-errors": [], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://auth.orkestera.test" } }, "description": "Auth: identity and discovery." } ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "./schemas/client-contract-document.schema.json" } } } } } } }, "/oauth/token": { "post": { "summary": "Token endpoint: client_credentials, refresh_token, device_code", "description": "Obtain a short-lived Service Token for one resource using client credentials or an approved device code, or rotate a refresh token. The requested posture can only lower the access allowed by policy. Inspect the OAuth error code as well as the HTTP status; token errors currently use 401.", "x-orkestera-surface": { "service": "auth", "status": "live", "issue": null, "gate": null, "audience": null }, "x-orkestera-errors": [ "invalid_client", "invalid_grant", "invalid_scope", "unsupported_grant_type", "unauthorized_client", "invalid_target", "unauthorized_audience", "unauthorized_org", "unauthorized_user", "rate_limit_exceeded", "authorization_pending", "slow_down", "access_denied", "expired_token" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://auth.orkestera.test" } }, "description": "Auth: identity and discovery." } ], "security": [ { "clientSecretBasic": [] }, {} ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "$ref": "#/components/responses/TokenError" }, "401": { "$ref": "#/components/responses/TokenError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/oauth/device_authorization": { "post": { "summary": "RFC 8628 device authorization request", "description": "Start interactive sign-in for a registered public client. Show the returned verification URI and user code, then poll the token endpoint at the returned interval. Approval is bound to the client's organization and the approving user.", "x-orkestera-surface": { "service": "auth", "status": "live", "issue": null, "gate": null, "audience": null }, "x-orkestera-errors": [ "invalid_client", "unauthorized_client", "invalid_target", "invalid_scope", "unauthorized_org", "rate_limit_exceeded", "server_error" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://auth.orkestera.test" } }, "description": "Auth: identity and discovery." } ], "security": [ {} ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string" }, "scope": { "type": "string" }, "posture": { "$ref": "./schemas/common.schema.json#/$defs/posture" }, "client_version": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationResponse" } } } }, "400": { "$ref": "#/components/responses/TokenError" }, "401": { "$ref": "#/components/responses/TokenError" }, "429": { "$ref": "#/components/responses/TokenError" }, "500": { "$ref": "#/components/responses/TokenError" } } } }, "/oauth/revoke": { "post": { "summary": "RFC 7009 token revocation", "description": "Revoke a token using confidential-client authentication. Public clients cannot call this revocation endpoint; a user or administrator can revoke their access through Auth.", "x-orkestera-surface": { "service": "auth", "status": "live", "issue": null, "gate": null, "audience": null }, "x-orkestera-errors": [ "invalid_client", "rate_limit_exceeded" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://auth.orkestera.test" } }, "description": "Auth: identity and discovery." } ], "security": [ { "clientSecretBasic": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/TokenError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/client/v1/sessions": { "post": { "summary": "Session handshake", "description": "Present the client\u2019s session descriptor, including client_kind and client_version matching the token claims. The response carries the effective posture and, for client_enforced sessions, the policy snapshot and its hash. The handshake does not change the token\u2019s posture. Use the reported batch limits and inspect truncation metadata; there is no released max_event_bytes field.", "x-orkestera-surface": { "service": "core", "status": "live", "issue": null, "gate": "client:session", "audience": "core" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "unsupported_contract_version", "invalid_descriptor", "client_kind_mismatch", "client_version_mismatch", "policy_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://core.orkestera.test" } }, "description": "Core: session handshake and org policy." } ], "security": [ { "serviceToken": [ "client:session" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "./schemas/session-descriptor.schema.json" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "./schemas/handshake-response.schema.json" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/client/v1/events": { "post": { "summary": "Ingest a batch of client.* events", "description": "Ingest client.* event batches under the token's organization, client and user. Requires client_enforced or observed posture. Event IDs make retries idempotent. Sequenced state updates require consecutive sequence numbers; gaps request a snapshot. Merge events carry partial unsequenced state. Inspect each event result, including accepted events marked truncated. Reported policy drift is recorded; it does not block work.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "client:ingest", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "posture_governed", "invalid_batch", "batch_too_large", "invalid_event", "event_id_conflict", "run_id_mismatch", "run_not_writable", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." } ], "security": [ { "serviceToken": [ "client:ingest" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "./schemas/ingest-batch.schema.json" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "./schemas/ingest-response.schema.json" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/client/v1/otlp/v1/logs": { "post": { "summary": "Ingest an OTLP/HTTP logs export", "description": "Ingest OTLP/HTTP logs as JSON or protobuf. At Watch, use a watch/client:ingest Service Token. At Client Edge, use a dedicated telemetry-purpose Client Ingest Credential; inference credentials and direct Service Tokens are refused there. Discover edge_otlp_logs for the Edge URL. Identity comes from verified claims. Raw log bodies and unsafe attributes are omitted. Inspect partialSuccess.rejectedLogRecords and honor Retry-After on 429. Edge bounds identity/gzip input and expanded data to 8 MiB; Watch retains its own record limits. No gRPC or traces endpoint is served.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "client:ingest", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "posture_governed", "invalid_batch", "unsupported_media_type", "batch_too_large", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." }, { "url": "{base}", "variables": { "base": { "default": "https://api.orkestera.test" } }, "description": "Client Edge: telemetry-purpose credential only." } ], "security": [ { "serviceToken": [ "client:ingest" ] }, { "clientIngestCredential": [] } ], "requestBody": { "required": true, "description": "An OTLP ExportLogsServiceRequest (opentelemetry-proto v1), protobuf-encoded as application/x-protobuf or JSON-encoded as application/json. Any other Content-Type is unsupported_media_type.", "content": { "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Accepted. The body is OTLP's own export response in the encoding the request used: empty on full success, and otherwise a partial success naming how many records were not accepted and why.", "content": { "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "properties": { "partialSuccess": { "type": "object", "required": [ "rejectedLogRecords", "errorMessage" ], "properties": { "rejectedLogRecords": { "type": "integer", "minimum": 1 }, "errorMessage": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-orkestera-edge-credential-purpose": "telemetry" } }, "/client/v1/otlp/v1/metrics": { "post": { "summary": "Ingest an OTLP/HTTP metrics export", "description": "Ingest OTLP/HTTP metrics as JSON or protobuf. Watch accepts a watch/client:ingest Service Token; Client Edge accepts only a telemetry-purpose Client Ingest Credential at the discovered edge_otlp_metrics URL. Cumulative sums and gauges report running totals per series; delta sums are not accumulated across exports. The resulting run is unsequenced and does not claim complete history. Inspect partial-success responses. Codex\u2019s generated profile disables metrics and uses logs only.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "client:ingest", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "posture_governed", "invalid_batch", "unsupported_media_type", "batch_too_large", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." }, { "url": "{base}", "variables": { "base": { "default": "https://api.orkestera.test" } }, "description": "Client Edge: telemetry-purpose credential only." } ], "security": [ { "serviceToken": [ "client:ingest" ] }, { "clientIngestCredential": [] } ], "requestBody": { "required": true, "description": "An OTLP ExportMetricsServiceRequest (opentelemetry-proto v1), protobuf-encoded as application/x-protobuf or JSON-encoded as application/json. Any other Content-Type is unsupported_media_type.", "content": { "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Accepted. The body is OTLP's own export response in the encoding the request used: empty on full success, and otherwise a partial success naming how many records were not accepted and why.", "content": { "application/x-protobuf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "properties": { "partialSuccess": { "type": "object", "required": [ "rejectedDataPoints", "errorMessage" ], "properties": { "rejectedDataPoints": { "type": "integer", "minimum": 1 }, "errorMessage": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "x-orkestera-edge-credential-purpose": "telemetry" } }, "/client/v1/runs": { "get": { "summary": "List the org's external runs", "description": "Page through the organization's external runs, newest first by creation. Updates do not move runs between pages. Use the returned cursor; invalid cursors are rejected. Optional filters narrow the current organization only.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "watch:read", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "temporarily_unavailable", "invalid_cursor" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." } ], "security": [ { "serviceToken": [ "watch:read" ] } ], "parameters": [ { "name": "session_id", "in": "query", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "schema": { "type": "string" }, "description": "Only runs this client registration reported." }, { "name": "client_kind", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/client/v1/runs/{run_id}": { "get": { "summary": "One external run's summary", "description": "Read reduced run state, attribution and reporting status. Client-chosen run IDs may collide; narrow the lookup with client_id and session_id. Ambiguous matches return run_ambiguous. Runs outside the organization return run_not_found.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "watch:read", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "run_not_found", "run_ambiguous", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." } ], "security": [ { "serviceToken": [ "watch:read" ] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client's run id." }, { "name": "client_id", "in": "query", "schema": { "type": "string" }, "description": "The client registration that reported the run." }, { "name": "session_id", "in": "query", "schema": { "type": "string" }, "description": "The session the run was reported in." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSummary" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/client/v1/analysis": { "get": { "summary": "Cross-client analysis for the org", "description": "Analyze external and governed runs by client kind, harness, model, posture or user within retained history. Figures are available, partial or unavailable. A partial value is a lower bound; absent data is never reported as zero. Inspect the sources and window metadata before comparing totals.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "watch:read", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "org_required", "invalid_request", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." } ], "security": [ { "serviceToken": [ "watch:read" ] } ], "parameters": [ { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "client_kind", "harness", "model", "posture", "user" ] }, "description": "The one breakdown to answer. Absent: all five." }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "RFC 3339 with an offset; runs that started at or after it. Earlier than Watch's retention window is clamped to the window's start. In the future is invalid_request." }, { "name": "user_id", "in": "query", "schema": { "type": "string", "minLength": 1 }, "description": "Only runs this user of the token's org started. A user of another org matches nothing." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisReport" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/inference": { "get": { "summary": "Inference statistics: fleet aggregates and organization-owned slices", "description": "Read an operational inference snapshot with mixed coverage. by_task and by_agent use the token\u2019s organization-owned slices; by_model, totals and latency are fleet aggregates with no tenant key. Older snapshots without owned splits return empty tenant maps. Distinguish lifetime counters from rolling-window metrics and inspect availability. Fleet totals are not your organization\u2019s billed spend; use its entitled Spend views for organization usage estimates.", "x-orkestera-surface": { "service": "watch", "status": "live", "issue": null, "gate": "watch:read", "audience": "watch" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://watch.orkestera.test" } }, "description": "Watch: client.* ingest and read-back." } ], "security": [ { "serviceToken": [ "watch:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/api/tasks": { "get": { "summary": "List the org's tasks (governed work), a page at a time", "description": "List organization-owned tasks, newest first. Filter by comma-separated status and page with limit and cursor. The X-Next-Cursor response header identifies the next page. Keep the same filters when reusing a cursor. Storage failure returns 503 rather than an empty list.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:read", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "invalid_request", "invalid_cursor", "org_required", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:read" ] } ], "responses": { "200": { "description": "OK", "headers": { "X-Next-Cursor": { "schema": { "type": "string" }, "description": "Present when another page follows; pass it back as `cursor`." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "503": { "description": "A stable code; the response carries Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Rows per page." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated task statuses (contracts/task_statuses.golden.json); only tasks in one of them are listed." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The previous page's `X-Next-Cursor`. Opaque." } ] }, "post": { "summary": "Submit a goal as a Task", "description": "Submit a goal for governed execution. The response identifies the task and its initial status. The organization comes from the token; policy escape flags are refused.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:write", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "escape_flag_refused", "invalid_request", "task_not_created", "org_required", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "goal" ], "properties": { "goal": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status" ], "properties": { "task_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "503": { "description": "A stable code; the response carries Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } } } } }, "/api/tasks/{task_id}": { "get": { "summary": "One task's detail", "description": "Read task status, issues and available results. Artifact URLs are temporary signed links; re-read the task when they expire. Missing tasks and tasks outside the caller's organization both return task_not_found.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:read", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "org_required", "task_not_found", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:read" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDetail" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "description": "A stable code; the response carries Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } } } }, "delete": { "summary": "Delete a task that is not running", "description": "Delete an organization-owned task that is not running. A running task returns task_status_conflict. Deleting a task is distinct from halting its execution.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:write", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "task_not_found", "task_status_conflict", "internal_error" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status" ], "properties": { "task_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/api/tasks/{task_id}/start": { "post": { "summary": "Start a planned task", "description": "Start a planned task. The response reports planning; policy escape flags are refused. Check status after any ambiguous transport failure before repeating the request.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:write", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "escape_flag_refused", "task_not_found", "task_status_conflict", "platform_halted", "task_already_dispatched", "runner_unavailable", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status" ], "properties": { "task_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "description": "A stable code; the response carries Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } } } } }, "/api/tasks/{task_id}/halt": { "post": { "summary": "Halt one unfinished task", "description": "Stop one unfinished task and mark it halted. A finished task returns task_status_conflict. A failed state write returns 503 without announcing a successful halt.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:write", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "org_required", "task_not_found", "task_status_conflict", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status" ], "properties": { "task_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "description": "A stable code; the response carries Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } } } } }, "/api/tasks/{task_id}/resume": { "post": { "summary": "Resume a halted, failed or pending task", "description": "Re-dispatch a halted, failed or pending task. The response reports planning. Organization ownership and policy escape-flag checks still apply.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": "tasks:write", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected", "escape_flag_refused", "org_required", "task_not_found", "task_status_conflict", "platform_halted", "task_already_dispatched", "runner_unavailable", "temporarily_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:write" ] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status" ], "properties": { "task_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "description": "A stable code; the response carries Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } } } } }, "/api/events": { "get": { "summary": "Server-sent task progress events", "description": "Subscribe to your organization's task progress with tasks:read or tasks:write. Save event IDs and reconnect with Last-Event-ID. When replay is unavailable the stream emits stream_reset; re-read the tasks you follow. IDs represent stream positions, not a count of your own events.", "x-orkestera-surface": { "service": "platform", "status": "live", "issue": null, "gate": ":any_authenticated", "audience": "platform" }, "x-orkestera-errors": [ "unauthorized", "malformed", "untrusted_issuer", "unknown_key", "bad_signature", "expired", "not_yet_valid", "key_source_unavailable", "wrong_audience", "insufficient_scope", "policy_rejected" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://platform.orkestera.test" } }, "description": "Platform: the Task API (governed work)." } ], "security": [ { "serviceToken": [ "tasks:read" ] }, { "serviceToken": [ "tasks:write" ] } ], "responses": { "200": { "description": "text/event-stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The `id:` of the last event received, sent on reconnect." } ] } }, "/v1/models": { "get": { "summary": "Models this org may call (OpenAI dialect)", "description": "List model IDs from your organization\u2019s route table. Accepts a Service Token or an eligible inference-purpose Client Ingest Credential. A seeded model can appear before its provider credential is configured; the list does not prove that a completion will succeed.", "x-orkestera-surface": { "service": "client_edge", "status": "live", "issue": null, "gate": "inference:write", "audience": "client_edge" }, "x-orkestera-errors": [ "invalid_token", "insufficient_scope", "client_identity_required", "posture_not_permitted", "rate_limited", "upstream_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://edge.orkestera.test" } }, "description": "The Client Edge; location and host decided by." } ], "security": [ { "serviceToken": [ "inference:write" ] }, { "clientIngestCredential": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/EdgeError" }, "403": { "$ref": "#/components/responses/EdgeError" }, "429": { "$ref": "#/components/responses/EdgeError" }, "502": { "$ref": "#/components/responses/EdgeError" }, "503": { "$ref": "#/components/responses/EdgeError" } } } }, "/v1/chat/completions": { "post": { "summary": "Chat completions through Orkestera (OpenAI dialect)", "description": "Send an OpenAI Chat Completions request, streaming or JSON, using an available model route. Organization, user and client attribution come from the token. Inference is charged against the organization's budget in every external-execution posture.", "x-orkestera-surface": { "service": "client_edge", "status": "live", "issue": null, "gate": "inference:write", "audience": "client_edge" }, "x-orkestera-errors": [ "dialect_mismatch", "invalid_token", "insufficient_scope", "client_identity_required", "posture_not_permitted", "rate_limited", "upstream_unavailable", "budget_exceeded", "route_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://edge.orkestera.test" } }, "description": "The Client Edge; location and host decided by." } ], "security": [ { "serviceToken": [ "inference:write" ] }, { "clientIngestCredential": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages" ], "description": "OpenAI Chat Completions request, unchanged." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "401": { "$ref": "#/components/responses/EdgeError" }, "402": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "403": { "$ref": "#/components/responses/EdgeError" }, "404": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "429": { "$ref": "#/components/responses/EdgeError" }, "502": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "503": { "$ref": "#/components/responses/EdgeOrUpstreamError" } } } }, "/v1/messages": { "post": { "summary": "Messages through Orkestera (Anthropic dialect)", "description": "Send an Anthropic Messages request, streaming or JSON. Use a bearer credential or X-Api-Key, and the Anthropic-Version header required by your provider. Native Messages routes preserve the protocol; other routes may translate it or reject an unsupported dialect. Inference is charged against the organization's budget.", "x-orkestera-surface": { "service": "client_edge", "status": "live", "issue": null, "gate": "inference:write", "audience": "client_edge" }, "x-orkestera-errors": [ "dialect_mismatch", "invalid_token", "insufficient_scope", "client_identity_required", "posture_not_permitted", "rate_limited", "upstream_unavailable", "budget_exceeded", "model_not_available", "route_unavailable", "invalid_request", "upstream_rejected", "upstream_rate_limited" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://edge.orkestera.test" } }, "description": "The Client Edge; location and host decided by." } ], "security": [ { "serviceToken": [ "inference:write" ] }, { "clientIngestCredential": [] }, { "clientApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "messages", "max_tokens" ], "description": "Anthropic Messages request, unchanged." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/MessagesOrUpstreamError" }, "401": { "$ref": "#/components/responses/MessagesError" }, "402": { "$ref": "#/components/responses/MessagesOrUpstreamError" }, "403": { "$ref": "#/components/responses/MessagesError" }, "404": { "$ref": "#/components/responses/MessagesOrUpstreamError" }, "413": { "$ref": "#/components/responses/MessagesOrUpstreamError" }, "429": { "description": "The Edge's rate_limited (a Client Ingest Credential exchanged too often), or llmproxy's upstream_rate_limited, which carries the provider's Retry-After. Two writers answer here: the Client Edge, and llmproxy, whose refusals the Edge relays byte for byte (it intercepts only an upstream 401). Since both write this one dialect at `application/json`, with a stable code from errors.json. Branch on the code.", "x-orkestera-error-dialect": "anthropic", "headers": { "Retry-After": { "description": "Present on llmproxy's upstream_rate_limited; the Edge's own rate_limited sets none.", "required": false, "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "./schemas/edge-error.schema.json#/$defs/anthropic" } } } }, "502": { "$ref": "#/components/responses/MessagesOrUpstreamError" }, "503": { "$ref": "#/components/responses/MessagesOrUpstreamError" } } } }, "/v1/usage": { "post": { "summary": "Report usage bought beside Orkestera", "description": "Report inference purchased directly from another provider. Usage is attributed to the authenticated principal, recorded as reported and not debited against Orkestera's inference budget. The body limit is 64 KiB; oversized reports currently return 502 upstream_unavailable.", "x-orkestera-surface": { "service": "client_edge", "status": "live", "issue": null, "gate": "inference:write", "audience": "client_edge" }, "x-orkestera-errors": [ "invalid_usage_report", "invalid_token", "insufficient_scope", "client_identity_required", "posture_not_permitted", "rate_limited", "upstream_unavailable", "storage_unavailable" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://edge.orkestera.test" } }, "description": "The Client Edge; location and host decided by." } ], "security": [ { "serviceToken": [ "inference:write" ] }, { "clientIngestCredential": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "./schemas/usage-report.schema.json" } } } }, "responses": { "202": { "description": "Recorded, not debited.", "content": { "application/json": { "schema": { "$ref": "./schemas/usage-response.schema.json" } } } }, "400": { "$ref": "#/components/responses/EdgeError" }, "401": { "$ref": "#/components/responses/EdgeError" }, "403": { "$ref": "#/components/responses/EdgeError" }, "429": { "$ref": "#/components/responses/EdgeError" }, "500": { "description": "llmproxy could not store the report; nothing was recorded. Its `storage_unavailable`, in the Edge dialect.", "x-orkestera-error-dialect": "edge", "content": { "application/json": { "schema": { "$ref": "./schemas/edge-error.schema.json#/$defs/edge" } } } }, "502": { "$ref": "#/components/responses/EdgeError" }, "503": { "$ref": "#/components/responses/EdgeError" } } } }, "/v1/responses": { "post": { "summary": "Native Responses with full tool payloads (JSON or SSE)", "description": "Send a native Responses request on an explicitly pinned Responses route. Tool definitions, calls, results and reasoning items pass through without translation or client-specific filtering. Use stateless input replay with store:false; stored conversation references and background jobs are refused. JSON and SSE are supported. Inference uses the organization\u2019s budget, and the route does not switch providers or models during a continuation.", "x-orkestera-surface": { "service": "client_edge", "status": "live", "issue": null, "gate": "inference:write", "audience": "client_edge" }, "x-orkestera-errors": [ "dialect_mismatch", "invalid_token", "insufficient_scope", "client_identity_required", "posture_not_permitted", "rate_limited", "upstream_unavailable", "budget_exceeded", "model_not_available", "route_unavailable", "invalid_request", "upstream_rejected", "upstream_rate_limited", "request_too_large" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://edge.orkestera.test" } }, "description": "The Client Edge; location and host decided by." } ], "security": [ { "serviceToken": [ "inference:write" ] }, { "clientIngestCredential": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": {}, "stream": { "type": "boolean" }, "store": { "type": "boolean", "enum": [ false ] }, "background": { "type": "boolean", "enum": [ false ] } }, "additionalProperties": true, "description": "Native tool/content fields are preserved. Select a responses-dialect model route." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string", "description": "Native Responses SSE events, including tool/continuation payloads and terminal usage." } } } }, "400": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "401": { "$ref": "#/components/responses/EdgeError" }, "402": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "403": { "$ref": "#/components/responses/EdgeError" }, "404": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "429": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "502": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "503": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "413": { "$ref": "#/components/responses/EdgeOrUpstreamError" } } } }, "/v1/responses/compact": { "post": { "summary": "Compact native Responses history", "description": "Compact native Responses history on the same pinned provider/model route. The result is a response.compaction JSON object for later input replay. Streaming, stored histories and background work are not supported on this endpoint. Full native content and tool payloads are preserved.", "x-orkestera-surface": { "service": "client_edge", "status": "live", "issue": null, "gate": "inference:write", "audience": "client_edge" }, "x-orkestera-errors": [ "dialect_mismatch", "invalid_token", "insufficient_scope", "client_identity_required", "posture_not_permitted", "rate_limited", "upstream_unavailable", "budget_exceeded", "model_not_available", "route_unavailable", "invalid_request", "upstream_rejected", "upstream_rate_limited", "request_too_large" ], "servers": [ { "url": "{base}", "variables": { "base": { "default": "https://edge.orkestera.test" } }, "description": "The Client Edge; location and host decided by." } ], "security": [ { "serviceToken": [ "inference:write" ] }, { "clientIngestCredential": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "input" ], "properties": { "model": { "type": "string" }, "input": {}, "stream": { "type": "boolean", "enum": [ false ] }, "store": { "type": "boolean", "enum": [ false ] }, "background": { "type": "boolean", "enum": [ false ] } }, "additionalProperties": true, "description": "Native tool/content fields are preserved. Select a responses-dialect model route." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "401": { "$ref": "#/components/responses/EdgeError" }, "402": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "403": { "$ref": "#/components/responses/EdgeError" }, "404": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "429": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "502": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "503": { "$ref": "#/components/responses/EdgeOrUpstreamError" }, "413": { "$ref": "#/components/responses/EdgeOrUpstreamError" } } } } }, "components": { "schemas": { "AuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "token_endpoint", "jwks_uri", "grant_types_supported", "scopes_supported" ], "properties": { "issuer": { "type": "string" }, "token_endpoint": { "type": "string" }, "jwks_uri": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "introspection_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "device_authorization_endpoint": { "type": "string", "description": "Live since." }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } } } }, "JWKS": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "required": [ "kty", "kid" ], "properties": { "kty": { "type": "string" }, "kid": { "type": "string" }, "alg": { "type": "string" }, "use": { "type": "string" }, "n": { "type": "string" }, "e": { "type": "string" } } } } } }, "TokenRequest": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string", "description": "Space-separated." }, "resource": { "type": "string", "description": "The audience: auth, core, watch, platform, llmproxy, runner (and the Client Edge's, )." }, "refresh_token": { "type": "string" }, "device_code": { "type": "string", "description": "Live since." }, "posture": { "$ref": "./schemas/common.schema.json#/$defs/posture", "description": "Caps the resolved posture and never raises it. Absent or unknown caps at governed." }, "client_version": { "type": "string", "description": "Pending. Required for client_enforced." } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" }, "aud": { "type": "string" }, "refresh_token": { "type": "string" } } }, "DeviceAuthorizationResponse": { "type": "object", "required": [ "device_code", "user_code", "verification_uri", "expires_in" ], "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" } } }, "RunList": { "type": "object", "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "RunSummary": { "$ref": "./schemas/run-summary.schema.json" }, "AnalysisReport": { "type": "object", "required": [ "group_by", "window", "filters", "sources", "overall", "breakdowns" ], "properties": { "group_by": { "type": [ "string", "null" ], "description": "The breakdown asked for; null when all five are answered." }, "window": { "type": "object", "required": [ "since", "until", "requested_since", "clamped", "retention_seconds" ], "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "requested_since": { "type": [ "string", "null" ], "format": "date-time" }, "clamped": { "type": "boolean" }, "retention_seconds": { "type": "integer", "minimum": 1 } } }, "filters": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": [ "string", "null" ] } } }, "sources": { "type": "object", "required": [ "external", "governed" ], "properties": { "external": { "type": "object", "required": [ "status", "runs", "complete", "cost_basis", "usage_window_minutes", "reason" ], "properties": { "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "runs": { "type": [ "integer", "null" ], "minimum": 0, "description": "How many runs of this kind the answer is built from, after any user_id filter." }, "complete": { "type": "boolean", "description": "false when Watch read only the newest runs of this kind and older ones in the window are not counted, or when an input it needed could not be read in full; `reason` then says which." }, "cost_basis": { "type": "string", "enum": [ "client_reported", "observed_tokens_at_list_price", "unavailable" ] }, "usage_window_minutes": { "type": [ "number", "null" ], "description": "Governed only: the rolling window llmproxy's per-task usage covers. A run that started before it has a partial token count." }, "reason": { "type": [ "string", "null" ] } } }, "governed": { "type": "object", "required": [ "status", "runs", "complete", "cost_basis", "usage_window_minutes", "reason" ], "properties": { "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "runs": { "type": [ "integer", "null" ], "minimum": 0, "description": "How many runs of this kind the answer is built from, after any user_id filter." }, "complete": { "type": "boolean", "description": "false when Watch read only the newest runs of this kind and older ones in the window are not counted, or when an input it needed could not be read in full; `reason` then says which." }, "cost_basis": { "type": "string", "enum": [ "client_reported", "observed_tokens_at_list_price", "unavailable" ] }, "usage_window_minutes": { "type": [ "number", "null" ], "description": "Governed only: the rolling window llmproxy's per-task usage covers. A run that started before it has a partial token count." }, "reason": { "type": [ "string", "null" ] } } } } }, "overall": { "type": "array", "items": { "$ref": "#/components/schemas/AnalysisGroup" }, "description": "One group per execution, key null." }, "breakdowns": { "type": "object", "description": "For each breakdown asked for, its groups: one per (execution, key).", "propertyNames": { "enum": [ "client_kind", "harness", "model", "posture", "user" ] }, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/AnalysisGroup" } } } } }, "AnalysisGroup": { "type": "object", "required": [ "execution", "key", "runs", "outcomes", "failure_rate", "metrics" ], "properties": { "execution": { "type": "string", "enum": [ "external", "governed" ], "description": "`external`: a client executed the run and reported it through client.* events. `governed`: Orkestera's Runner executed it." }, "key": { "type": [ "string", "null" ], "description": "The group's value of the breakdown: a client kind, a harness, a model, a posture or a user id. A run's several harnesses or models are joined with \", \". null: not reported, or no breakdown (`overall`). A governed run's client kind and harness are `orkestera` and its posture is `governed`. `client_enforced` is always qualified as `client_enforced (unattested)`, `(attested)` or `(stale)`." }, "runs": { "type": "integer", "minimum": 1 }, "outcomes": { "type": "object", "required": [ "succeeded", "failed", "cancelled", "in_progress" ], "properties": { "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "in_progress": { "type": "integer", "minimum": 0 } } }, "failure_rate": { "type": "object", "required": [ "status", "value", "reason" ], "description": "failed / (succeeded + failed); cancelled and unfinished runs are left out. Unavailable while no run in the group has succeeded or failed.", "properties": { "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "value": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "reason": { "type": [ "string", "null" ] } } }, "metrics": { "type": "object", "required": [ "cost_usd", "tokens", "input_tokens", "output_tokens", "duration_seconds" ], "properties": { "cost_usd": { "$ref": "#/components/schemas/AnalysisFigure" }, "tokens": { "$ref": "#/components/schemas/AnalysisFigure" }, "input_tokens": { "$ref": "#/components/schemas/AnalysisFigure" }, "output_tokens": { "$ref": "#/components/schemas/AnalysisFigure" }, "duration_seconds": { "$ref": "#/components/schemas/AnalysisFigure" } } } } }, "AnalysisFigure": { "type": "object", "description": "One figure over a group's runs. `available`: every run reported it in full and had finished, and `value` is the total. `partial`: some did; `value` is a lower bound over what was reported, and `reported_runs` of `runs` reported it in full. `unavailable`: none did, and `value` is null. `mean` is over the `reported_runs` runs, null when there are none. A run still going, a token count from a stale or out-of-window llmproxy snapshot, and a total only some of a run's tasks reported are each a lower bound, never a total.", "required": [ "status", "value", "mean", "reported_runs", "runs", "reason" ], "properties": { "status": { "type": "string", "enum": [ "available", "partial", "unavailable" ] }, "value": { "type": [ "number", "null" ] }, "mean": { "type": [ "number", "null" ] }, "reported_runs": { "type": "integer", "minimum": 0 }, "runs": { "type": "integer", "minimum": 1 }, "reason": { "type": [ "string", "null" ], "description": "Why the figure is not available in full; null when it is." } }, "allOf": [ { "if": { "properties": { "status": { "const": "unavailable" } } }, "then": { "properties": { "value": { "type": "null" }, "reason": { "type": "string" } } } }, { "if": { "properties": { "status": { "const": "available" } } }, "then": { "properties": { "value": { "type": "number" }, "reason": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "partial" } } }, "then": { "properties": { "value": { "type": "number" }, "reason": { "type": "string" } } } } ] }, "Task": { "type": "object", "required": [ "task_id", "status" ], "description": "Shape pinned by contracts/tasks.golden.json.", "properties": { "task_id": { "type": "string" }, "org_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "TaskDetail": { "type": "object", "required": [ "task_id", "org_id", "status", "issue_count", "issues", "result", "result_unavailable" ], "properties": { "task_id": { "type": "string" }, "org_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "requirements": { "type": "string" }, "pass_threshold": { "type": "integer" }, "delivery_mode": { "type": "string" }, "run_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "issue_count": { "type": "integer" }, "issues": { "type": "array", "items": { "type": "object", "required": [ "issue_id", "status" ], "properties": { "issue_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "spec": { "type": "string" }, "criteria": { "type": "array" }, "iteration_count": { "type": "integer" }, "current_score": { "type": "number" } } } }, "degradation": { "type": [ "object", "null" ], "properties": { "severity": { "type": "string" }, "message": { "type": "string" } } }, "failure_stage": { "type": "string", "description": "Present only on a failed task." }, "failure_headline": { "type": "string", "description": "Present only on a failed task." }, "result_unavailable": { "type": "boolean", "description": "The run's deliverable could not be read from the Runner; `result` is null." }, "result": { "type": [ "object", "null" ], "properties": { "changed_files": { "type": "array" }, "diff": { "type": "string" }, "diff_truncated": { "type": "boolean" }, "evaluations": { "type": "array" }, "pr_url": { "type": [ "string", "null" ] }, "delivered_branch": { "type": [ "string", "null" ] }, "pr_failed": { "type": "boolean" }, "artifacts_incomplete": { "type": "boolean" }, "artifacts": { "type": "array", "items": { "type": "object", "required": [ "name", "url", "url_expires_at" ], "properties": { "name": { "type": [ "string", "null" ] }, "size": { "type": [ "integer", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Presigned GET, or null when it may not or cannot be signed." }, "url_expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } }, "securitySchemes": { "clientSecretBasic": { "type": "http", "scheme": "basic", "description": "client_secret_basic (RFC 6749 \u00a72.3.1). Auth also accepts client_secret_post: client_id and client_secret as form fields of the request body, which OpenAPI has no security scheme for." }, "serviceToken": { "type": "oauth2", "description": "A five-minute RS256 Service Token minted by Auth for one audience (`resource`). Org, client, user, Client Kind and posture are claims; a token with no posture claim is governed. Public clients obtain one through the device grant and refresh; confidential clients through client_credentials.", "flows": { "clientCredentials": { "tokenUrl": "https://auth.orkestera.test/oauth/token", "scopes": { "client:session": "Open a client session (handshake, audience core). Added to Auth's scope registry by.", "client:ingest": "Post client.* events. Org-grantable to an external client since; requires posture client_enforced or observed.", "watch:read": "Read back the org's runs and analysis.", "tasks:read": "Read the org's tasks and their progress stream.", "tasks:write": "Submit, start, halt, resume and delete the org's tasks.", "inference:write": "Call the Client Edge (audience client_edge): chat completions, Anthropic Messages, models. Added to Auth's scope registry by." } } } }, "clientIngestCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "orkic_", "description": "Client Ingest Credential : `orkic_` and 43 characters of unpadded base64url (./schemas/ingest-credential.schema.json#/$defs/secret), issued to one user for one client registration in one org through Auth's admin API. Valid only at the Client Edge, as a bearer or, on /v1/messages, as X-Api-Key. The Edge exchanges it at Auth (`POST /oauth/ingest_credential/exchange`) on the client's behalf for a five-minute `observed` Service Token, caches that token until shortly before it expires, and admits the request exactly as it would the client's own token. The client never exchanges it itself." }, "clientApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "On /v1/messages only: the same Service Token or Client Ingest Credential an Anthropic SDK sends as its API key. Verified exactly as the bearer is." } }, "responses": { "TokenError": { "description": "RFC 6749 \u00a75.2 error with a stable code.", "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } }, "Error": { "description": "Error with a stable code.", "content": { "application/json": { "schema": { "$ref": "./schemas/error.schema.json" } } } }, "EdgeError": { "description": "Client Edge error: the stable code is `error.code`.", "x-orkestera-error-dialect": "edge", "content": { "application/json": { "schema": { "$ref": "./schemas/edge-error.schema.json#/$defs/edge" } } } }, "EdgeOrUpstreamError": { "description": "Two writers answer here: the Client Edge, and llmproxy, whose refusals the Edge relays byte for byte (it intercepts only an upstream 401). Since both write this one dialect at `application/json`, with a stable code from errors.json. Branch on the code.", "x-orkestera-error-dialect": "edge", "content": { "application/json": { "schema": { "$ref": "./schemas/edge-error.schema.json#/$defs/edge" } } } }, "MessagesOrUpstreamError": { "description": "Two writers answer here: the Client Edge, and llmproxy, whose refusals the Edge relays byte for byte (it intercepts only an upstream 401). Since both write this one dialect at `application/json`, with a stable code from errors.json. Branch on the code. llmproxy writes the Anthropic shape on this path too, with its own wider `type` vocabulary.", "x-orkestera-error-dialect": "anthropic", "content": { "application/json": { "schema": { "$ref": "./schemas/edge-error.schema.json#/$defs/anthropic" } } } }, "MessagesError": { "description": "Client Edge error on /v1/messages, Anthropic-shaped: the stable code is `error.code`.", "x-orkestera-error-dialect": "anthropic", "content": { "application/json": { "schema": { "$ref": "./schemas/edge-error.schema.json#/$defs/anthropic" } } } } } } }