{"openapi":"3.1.0","info":{"title":"Atlan Agent Gateway — registry","description":"The platform core: identity, tenancy, the artifact plane, discovery and the policy plane.","license":{"name":"Apache-2.0","identifier":"Apache-2.0"},"version":"3.19.0"},"paths":{"/registry/v1/aggregate":{"post":{"tags":["discovery"],"summary":"Aggregate artifacts","description":"Grouped metrics over artifacts in workspaces the caller can read. `group_by` dimensions (L1 columns, with `bucket=minute|hour|day|week|month` on a timestamp) and `metrics` (`count`, `count_distinct`, `min`, `max`, `sum`, `avg`), filtered by the same `filters` grammar `POST /search` uses and sorted over a dimension or a metric alias.\n\n**L1 only** — a kind-column dimension or measure is rejected (400).\n\n`project_id` scopes to the project's owned **and linked** artifacts.\n\nThe container join keys `workspace_id` / `project_id` / `repo_id` / `owner_id` are groupable and filterable, so one call replaces a per-container fan-out. Only containers with at least one matching artifact appear: an empty one is **absent**, not zero.\n\n`page.total` is the **distinct-group** count, computed in the same statement as the page.\n\nThe scope defaults (heads only, no system artifacts, no archived) conjoin with `filters`, so filtering *for* an excluded value returns an empty page rather than a widened one.","operationId":"registry.aggregate","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateRequest"}}},"required":true,"description":"Input for Aggregate artifacts."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregationResponse"}}}},"400":{"description":"An unknown or un-aggregatable field, an unknown bucket or op, a bucket on a non-timestamp, a numeric measure over a non-numeric column, a duplicate alias, an unresolvable sort key, or a cap exceeded.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A `project_id` linking more than 1000 artifacts (`project_link_limit_exceeded`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["project_link_limit_exceeded","validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["project_link_limit_exceeded","validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/aggregate/{artifact_kind}":{"post":{"tags":["discovery"],"summary":"Aggregate artifacts of a kind","description":"As `POST /aggregate`, narrowed to one registered kind — and the kind is **validated**, so an unregistered or retired kind is a 404 rather than an empty result.\n\nA kind's own properties are **not** dimensions or measures here, and that is the contract rather than a gap: a kind declares its properties at registration without declaring which of them are queryable, so the grammar has no name to validate against. Only the shared artifact fields group here, exactly as on `POST /aggregate`.","operationId":"registry.aggregateKind","parameters":[{"name":"artifact_kind","in":"path","description":"Registered kind (`file`, `skill`, …)","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateRequest"}}},"required":true,"description":"Input for Aggregate artifacts of a kind."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregationResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such registered kind.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A `project_id` linking more than 1000 artifacts (`project_link_limit_exceeded`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["project_link_limit_exceeded","validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["project_link_limit_exceeded","validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps":{"get":{"tags":["apps"],"summary":"List apps","description":"Every app this account holds, installed or not. An app is an extension as this account holds it: what it is, who publishes it, where its browser UI lives, and whether the account has turned it on.\n\n**Browsing and the install list are the same read.** Filter `?filter[install_status][eq]=available` for what can be installed and `?filter[install_status][eq]=active` for what is. They were separate routes while the catalogue was deployment-global and the installs were account-scoped; an app is neither.\n\nSupports the shared query grammar over the artifact envelope (`name`, `display_name`, `updated_at`, …) and over this kind's own columns: `install_status`, `author`, `license`.","operationId":"registry.listApps","responses":{"200":{"description":"The account's apps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppsPage"}}}},"400":{"description":"The query grammar refused a field or an operator.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps/{app}":{"get":{"tags":["apps"],"summary":"Get an app","description":"Includes the install-time `install_metadata`. A `failed` status is kept rather than cleared: a retry with nothing to explain it is worse than a record saying what happened.","operationId":"registry.getApp","parameters":[{"name":"app","in":"path","description":"The app's name, which is the extension's name.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"This account holds no app by that name.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps/{app}/actions":{"get":{"tags":["apps"],"summary":"List an app's actions","description":"The jobs this app declares it can run, each a Temporal queue and workflow named `<app>/<job>`.\n\n**Not the same as `/actions`.** An app action is a *capability*; an `actions` row is a rule about when to invoke one. A client wiring up an action DAG reads both.","operationId":"registry.listAppActions","parameters":[{"name":"app","in":"path","description":"The app's name, which is the extension's name.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppActionsPage"}}}},"400":{"description":"The query grammar refused a field or an operator.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps/{app}/install":{"post":{"tags":["apps"],"summary":"Install an app","description":"Turns the app on for this account and fires its install lifecycle: the `pre_install` gate, then the app's own artifact moving to `active`, then the seeding `post_install` hook under **your** bearer — which is how an app's per-account seeds (a bootstrap skill, a default provider) are attributed to the caller rather than to the platform.\n\n**Idempotent, and a re-install is the retry.** Installing an already-installed app re-fires both hooks and re-merges their metadata, keeping the original `created_by` and `created_at`. Every documented seed is idempotent, so this is how an install whose seeds failed is recovered.\n\n**Only `pre_install` can refuse.** Once the app is `active` the install stands: a failing seed hook leaves it installed with no per-account state rather than rolling back, because a rolled-back install leaves nothing to retry from. An app that cannot be reached at all installs with empty metadata for the same reason — a deployment window must not become an onboarding outage.\n\nRequires the account to have been onboarded: an app is an artifact, and an artifact needs the org root workspace that onboarding creates.","operationId":"registry.installApp","parameters":[{"name":"app","in":"path","description":"The app's name, which is the extension's name.","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallAppBody"}}},"required":true,"description":"Input for Install an app."},"responses":{"200":{"description":"Installed, or already was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppDto"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The deployment offers no such app.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The account has not onboarded.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"The app's own install gate refused this account.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps/{app}/reconcile":{"post":{"tags":["apps"],"summary":"Trigger an app's reconcile sweep","description":"Hands the app every live artifact of its own kinds in this account, as `{id, metadata}`, so it can release backing resources for anything it is still holding that the registry no longer has a row for.\n\n**The set is the contract, so it is never truncated.** A partial set reads to the app as \"everything else is an orphan\", which for a sweeping handler means deleting live data. If the account holds more artifacts of these kinds than one sweep can carry, this refuses rather than sending a prefix — which is why the size check is part of the `202`, not of the sweep.\n\n**`202`, and the sweep runs after the response.** A reconcile walks an app's whole backing store for the account, so holding the request open for it would tie an operator's timeout to an object-store scan. What is decided before the `202` is everything a caller can act on: that the app is installed, and that its live set fits. The registry logs a reported outcome after acceptance; legacy handlers remain unreported.\n\n`live_count` is what distinguishes a sweep of four hundred artifacts from a sweep of an app the account owns nothing of — which is usually a mistake in which app was named.\n\n**Requires the same install permission the other lifecycle verbs do.** A sweep tells an app what the registry no longer holds, which a sweeping handler acts on by deleting its own backing data — so this is a write verb, and it used to be gated as a read.","operationId":"registry.reconcileApp","parameters":[{"name":"app","in":"path","description":"The app's name, which is the extension's name.","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"The live set was assembled and the sweep dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileAcceptedDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller may read this account but may not install or reconcile its apps.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"This account has not installed that app.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The account has not onboarded.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"422":{"description":"The live set exceeds what one sweep can carry whole.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps/{app}/uninstall":{"post":{"tags":["apps"],"summary":"Uninstall an app","description":"Marks the install `uninstalling`, tells the app so it can release what it provisioned for this account, then archives the account's artifact for it.\n\n**The account's artifacts are not touched.** Uninstalling `skill` does not archive the account's skills — the kind stays registered deployment-wide and the rows stay readable, so a re-install finds them. What the hook releases is the app's *own* per-account state (a bucket prefix, an external provider registration).\n\nA failing hook does not fail the uninstall: an account that asked to remove an app must not stay installed because the app's cleanup failed. `204`, with nothing to say.","operationId":"registry.uninstallApp","parameters":[{"name":"app","in":"path","description":"The app's name, which is the extension's name.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Uninstalled."},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"This account has not installed that app.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The account has not onboarded.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/apps/{app}/upgrade":{"post":{"tags":["apps"],"summary":"Move an install to the registration head","description":"Records the account against the deployment's current `release` and contract version. `{\"is_pinned\": true}` freezes it there, so a later release does not move this account; `{\"is_pinned\": false}` releases the freeze.\n\n**No hooks fire.** An upgrade changes which contract version the account is recorded against, and nothing else — re-running the seeding hook on every upgrade would re-seed an account that already has its rows. An app with per-version work to do has `reconcile`, which is triggered deliberately.","operationId":"registry.upgradeApp","parameters":[{"name":"app","in":"path","description":"The app's name, which is the extension's name.","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeAppBody"}}},"required":true,"description":"Input for Move an install to the registration head."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppDto"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"This account has not installed that app.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The account has not onboarded.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/artifacts/{artifact_kind}/{artifact_id}/channels":{"get":{"tags":["releases"],"summary":"List the channels this artifact currently ships on","description":"One entry per channel with a current release — the \"what betas exist\" read, so an agent can discover `@beta` without guessing the slug.","operationId":"registry.listArtifactChannels","parameters":[{"name":"artifact_kind","in":"path","description":"Kind handle","required":true,"schema":{"type":"string"}},{"name":"artifact_id","in":"path","description":"Artifact handle","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The current release on each channel.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseDto"}}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/artifacts/{artifact_kind}/{artifact_id}/releases":{"get":{"tags":["releases"],"summary":"List one artifact's release history","description":"Newest first, every status included — `withdrawn` among them, because a shipping record that hid its own retractions would be the wrong record.\n\nThe shared list grammar, as on `GET /releases`: `filter`, `sort`, `limit` (default 50, clamped to 500), `offset` and `count=false`. A line seeded by the release migration has one row per version it ever had.\n\nOne artifact under one `read` receipt, so the page is exact at any membership size and `is_truncated` is always `false`.","operationId":"registry.listArtifactReleases","parameters":[{"name":"artifact_kind","in":"path","description":"Kind handle","required":true,"schema":{"type":"string"}},{"name":"artifact_id","in":"path","description":"Artifact handle","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"e.g. filter[channel][eq]=latest, or filter[release_status][ne]=withdrawn.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Release fields, `-` for descending. Default -created_at.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size. Defaults to 50; larger than 500 is clamped to 500.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"offset","in":"query","description":"Rows to skip. At most 10 000.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"count","in":"query","description":"`false` skips `page.total`.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasePage"}}}},"400":{"description":"A malformed or wrong-kind handle, an unknown or un-filterable field, an illegal operator, a zero limit or an over-cap offset.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["releases"],"summary":"Release a version onto a channel","description":"Ships one version of one artifact line on one channel. Absent `version_id` takes the line's head; absent `channel` takes the account's default channel (`latest`).\n\n        The published **number** and the **semver** are allocated here, not at write time — a version that has never been released has neither, which is the whole reason they live on the release. An absent `version_label` auto-bumps the line's minor.\n\nRequires `manage` on the artifact's workspace, or `update` plus being the artifact's owner. A machine-created artifact has no owner, so only the admin arm applies to it.","operationId":"registry.cutRelease","parameters":[{"name":"artifact_kind","in":"path","description":"Kind handle","required":true,"schema":{"type":"string"}},{"name":"artifact_id","in":"path","description":"Artifact handle","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CutReleaseBody"}}},"required":true,"description":"Input for Release a version onto a channel."},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDto"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Unregistered kind, or an artifact the caller cannot see.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"`release_checks_pending` (retry once the check settles), `release_blocked` (a check refused the version), `version_not_distributable` (the version is archived), `version_already_released` (it has already shipped on this channel), `release_label_not_increasing` or `release_label_taken` (name another label); `conflict` when the artifact moved to another workspace while the release was in flight. A refused release writes nothing.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","release_blocked","release_checks_pending","release_label_not_increasing","release_label_taken","version_already_released","version_not_distributable"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"`kind_not_releasable`, `unknown_release_channel`, or `public_release_forbidden`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["kind_not_releasable","public_release_forbidden","unknown_release_channel","validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict","release_blocked","release_checks_pending","release_label_not_increasing","release_label_taken","version_already_released","version_not_distributable"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["kind_not_releasable","public_release_forbidden","unknown_release_channel","validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/artifacts/{artifact_kind}/{artifact_id}/releases/{channel}":{"get":{"tags":["releases"],"summary":"Resolve a channel's current release","description":"What `<artifact>@<channel>` means — the version every distribution surface serves for this line on this channel. `404` when the channel has never shipped, which is distinct from the channel not existing.","operationId":"registry.getCurrentRelease","parameters":[{"name":"artifact_kind","in":"path","description":"Kind handle","required":true,"schema":{"type":"string"}},{"name":"artifact_id","in":"path","description":"Artifact handle","required":true,"schema":{"type":"string"}},{"name":"channel","in":"path","description":"Channel slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/auth/whoami":{"get":{"tags":["auth"],"summary":"Introspect the caller's identity","description":"Echo back the verified identity resolved from the bearer token: subject, account, workspace hint, scopes, the caller's account `role` and its advisory `permissions`, any delegated actor, the token's expiry, and whether this caller has been onboarded.\n\nStandalone extensions call this to reconstruct the caller's identity **without verifying the token themselves**. The identity fields come from the verified token; `role` and `permissions` come from one authorization check against the caller's account: `permissions` lists the account capabilities the caller holds, and `role` is `admin` or `member` — absent for a human the account roster does not name, and for a machine or delegated caller, which also carries no `permissions`. `permissions` is **advisory**: every route decides its own capability fresh. On a deployment with no billing configured, `billing_view` and `billing_manage` are omitted for every role, so a client hides its billing surface when `billing_view` is absent. The raw token is never returned.\n\n`is_onboarded` is a database read, not a claim: a caller can hold a valid token and have no personal workspace, and a client needs to tell those apart to know whether to send them through provisioning.","operationId":"registry.whoami","responses":{"200":{"description":"The verified caller's resolved identity and onboarding state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoamiResponse"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"Account or workspace authorization is temporarily unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/invitations":{"get":{"tags":["invitations"],"summary":"List invitations","description":"A page of the account's invitations, newest first. Supports the shared query grammar over `email`, `role`, `workspace_id`, `status`, `invited_by`, `created_at`, `sent_at` and `expires_at`, plus `q=` over the address. A still-pending invitation past its TTL reports `status: expired`, derived. `members_view`.","operationId":"registry.listInvitations","responses":{"200":{"description":"A page of invitation summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationsPage"}}}},"400":{"description":"The query string is not valid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not a member of the account.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["invitations"],"summary":"Invite people by email","description":"Create or merge up to 50 invitations in one call. Each invitee targets one workspace (defaulting to the account's org_default) at one role. Structural violations — a personal-workspace target, or `viewer` into org_default — are a `422`; a rank over-reach or an email-policy failure is per-email `results[].outcome` data, never an HTTP error, as is an organization with no free seat (`outcome: rejected`, `reason: seat_capacity_exhausted`; the invite is not kept). An archived target workspace refuses the whole batch with `409` `workspace_archived`, since its roster is closed and the invite could never seat anyone. `members_invite`.","operationId":"registry.createInvitations","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvitationsRequest"}}},"required":true,"description":"Input for Invite people by email."},"responses":{"200":{"description":"The per-email outcome breakdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationsResponse"}}}},"400":{"description":"The body is not valid JSON.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller may not invite on this account.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"A target workspace is archived.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["workspace_archived"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"The batch is empty or over 50, or a target/role is not allowed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["workspace_archived"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/invitations/{invitation_id}":{"get":{"tags":["invitations"],"summary":"Get an invitation","description":"One invitation: its target workspace, role, and lifecycle. A still-pending invitation past its TTL reports `status: expired`, derived. `members_view`.","operationId":"registry.getInvitation","parameters":[{"name":"invitation_id","in":"path","description":"Invitation handle (invitation_…)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The invitation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such invitation, or the caller is not a member.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"patch":{"tags":["invitations"],"summary":"Edit a pending invite's role or target","description":"Rewrite a pending invitation's role and/or target workspace in place. The body is `{ role?, workspace_id? }` with at least one present; the email is never editable. The change re-runs all three gates against the (possibly new) target and respects the one-live-invite-per-(workspace, email) uniqueness. `members_invite`.","operationId":"registry.updateInvitation","parameters":[{"name":"invitation_id","in":"path","description":"Invitation handle (invitation_…)","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInvitationRequest"}}},"required":true,"description":"Input for Edit a pending invite's role or target."},"responses":{"200":{"description":"The updated invitation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such invitation, or the caller may not invite.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The invitation is not pending, or the new target already has a pending invite (`conflict`), or the new target is archived (`workspace_archived`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","workspace_archived"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"The body is empty, or the new target/role is not allowed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict","workspace_archived"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/invitations/{invitation_id}/resend":{"post":{"tags":["invitations"],"summary":"Re-email a pending invite","description":"Re-run the control-plane send (up to three attempts) for a pending invitation. The only path to re-email an invite. `members_invite`.","operationId":"registry.resendInvitation","parameters":[{"name":"invitation_id","in":"path","description":"Invitation handle (invitation_…)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The email result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationSendResult"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such invitation, or the caller may not invite.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The invitation is not pending (`conflict`), or the organization has no free seat for it (`seat_capacity_exhausted`); the invite stays pending so it can be resent once a seat frees up.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","seat_capacity_exhausted"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict","seat_capacity_exhausted"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/invitations/{invitation_id}/revoke":{"post":{"tags":["invitations"],"summary":"Revoke a pending invite","description":"Cancel a pending invitation and free its email for a fresh invite. No rank check — revoke is always de-escalation. `members_invite`.","operationId":"registry.revokeInvitation","parameters":[{"name":"invitation_id","in":"path","description":"Invitation handle (invitation_…)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The revoked invitation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such invitation, or the caller may not invite.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The invitation is not pending.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations":{"get":{"tags":["organisations"],"summary":"List organisations","description":"A collection of one: the caller's own account. It is a collection rather than a singleton read so the shape matches every other list, and because the account a token names is not something the client should have to know to ask.","operationId":"registry.listOrganisations","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationsPage"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["organisations"],"summary":"Create an organisation","description":"Create a brand-new organisation with the caller as its owner, independent of the organisation the caller's token belongs to. The control plane decides who may: only a signed-in person whose email domain the deployment allowlists (Atlan staff today), never an agent, a delegated token or a machine credential. The new organisation goes through the same creation transaction as sign-up, so it starts any configured trial. Omit `slug` to get a unique one derived from `name`. The caller's current token stays scoped to its current organisation: switch organisations to work in the new one.","operationId":"registry.createOrganisation","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganisationDto"}}},"required":true,"description":"Input for Create an organisation."},"responses":{"201":{"description":"The created organisation, proxied from the control plane.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationRecordDto"}}}},"400":{"description":"The body is malformed, `name` is blank or too long, or `slug` is not lowercase letters, digits and single hyphens, or is a reserved name.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller may not create organisations: an agent, delegated or scope-bound token, or an email domain the deployment does not allowlist (`org_create_not_allowed`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","org_create_not_allowed","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"409":{"description":"The `slug` is already in use; retry with another, or omit it.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","org_create_not_allowed","platform_principal_refused"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/stats/query":{"post":{"tags":["organisations"],"summary":"Trace statistics across the whole account","operationId":"registry.queryOrganisationTraceStats","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"A trace-statistics query. `group_by: [\"user\"]` is permitted, which is how per-person activity is read without reading anyone's traces. `workspace_id` (a `workspace_…` handle) narrows every figure to one workspace and requires `read` on it; `group_by: [\"workspace\"]` breaks the answer down across the workspaces the caller may read. Without either, the answer is account-wide, unchanged. Body keys the grammar does not define are ignored and named back in `meta.warnings`.","content":{"application/json":{"schema":{}}},"required":true},"responses":{"200":{"description":"Account-wide aggregates, or workspace-scoped ones when `workspace_id` or a `workspace` breakdown is requested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway.TraceStatsEnvelope"}}}},"400":{"description":"The body is not a JSON object, the query is malformed, `workspace_id` is not a `workspace_…` handle, or a panel filters on `workspace`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The authenticated caller is not a current member of this account, or holds no `read` on the requested workspace.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused","workspace_forbidden"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"Trace reads are not configured, the trace backend did not answer in time (`traces_unavailable`; worth retrying, since panels that finished are cached), or live membership authorization is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","not_configured","service_overloaded","traces_unavailable","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"description":"Use this operation to trace statistics across the whole account.","x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused","workspace_forbidden"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","not_configured","service_overloaded","traces_unavailable","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/trace-content-policy":{"get":{"tags":["organisations"],"summary":"Get the account's trace-content policy","description":"A document of facets, one field per facet — `capture` today; retention and redaction configuration are the named next ones, each arriving as an additive field. `capture`: `store` admits the content half of an ingested trace into the content plane, `drop` discards it at the worker, and `null` means the account never chose — which resolves as `drop`, the fail-closed default. Readable by any member: clients strip content at emit when the effective capture is `drop`, so this is the login-time read that makes that possible.","operationId":"registry.getTraceContentPolicy","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceContentPolicyDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"put":{"tags":["organisations"],"summary":"Set the account's trace-content policy","description":"Requires the account's `settings_manage`: account-wide capture posture is an account setting. A patch of facets: only fields present in the body change, so a caller setting `capture` is untouched by facets added later. `capture`: `store` or `drop`; `null` clears the choice back to the fail-closed default — behaviourally identical to `drop`, kept distinct because \"never chose\" and \"chose drop\" are different facts. Audited under the policy's own entity type. Every facet is a ceiling: it can only narrow what a client already decided, never resurrect content a client stripped.","operationId":"registry.setTraceContentPolicy","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetTraceContentPolicyDto"}}},"required":true,"description":"Input for Set the account's trace-content policy."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceContentPolicyDto"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}":{"get":{"tags":["organisations"],"summary":"Get an organisation","description":"The caller's own account, as one merged record: the control plane's account settings joined with the registry-owned `avatar_url` when the account has a picture — the same shape `GET /users/{user_id}` carries, so one read gives the details and a pointer to the picture. `avatar_url` is absent (not `null`) when there is none; fetch it with the caller's bearer (`GET /organisations/{org_id}/avatar`). The `org_id` in the path must be the caller's token org: another account's id is a 404, checked before anything else, so it can never read as a foreign 200. Members and admins may read (`settings_view`). Honors `X-Atlan-Consistency-Token` for read-your-own-writes: the token pins the permission check to a revision at least as fresh as a prior write's. A non-2xx control-plane response is surfaced through the registry's problem catalogue.","operationId":"registry.getOrganisation","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stable identifier of the related org resource."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationDetailDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"patch":{"tags":["organisations"],"summary":"Update an organisation's profile","description":"Update the caller's own account profile — today the display `name`. The control plane is the system of record, so the change is authorized here (`settings_manage`), forwarded on the caller's own bearer, and only once the plane confirms it is this registry's cached copy refreshed from the plane's response. `name` is replace-only on this route: a value replaces the current one, and it cannot be cleared here. Honors `If-Match` for optimistic concurrency. The `org_id` in the path must be the caller's token org: another account's id is a `404`, checked before anything else.","operationId":"registry.updateOrganisation","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stable identifier of the related org resource."},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganisationProfileDto"}}},"required":true,"description":"Input for Update an organisation's profile."},"responses":{"200":{"description":"The updated account record, proxied from the control plane.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationRecordDto"}}}},"400":{"description":"The request body is malformed or empty, or `name` is blank or too long.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, the path org is not the caller's, or a scope-bound token lacks `settings:manage`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"412":{"description":"The `If-Match` precondition failed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["precondition_failed"]}}}],"description":"RFC 7807 problem document for 412 (Precondition Failed)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"412":["precondition_failed"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}/audit-events":{"get":{"tags":["organisations"],"summary":"List account audit events","description":"A page of the account's audit events, proxied from the control plane. Account admins only. The inbound query string is passed through unchanged.","operationId":"registry.listAuditEvents","parameters":[{"name":"org_id","in":"path","description":"The account id (must be the caller's own).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of audit events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventsPage"}}}},"400":{"description":"The request is malformed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, or a scope-bound token lacks `audit:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"422":{"description":"The filter parameters are invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}/avatar":{"get":{"tags":["organisations"],"summary":"Get the account's avatar","description":"The account's picture as raw image bytes, with the media type it was stored as. Gateway-native. Members and admins may read (`settings_view`). `404` when the account has no picture, so a client falls back to whatever it draws for an account without one. The `v` query parameter is a client cache key and is ignored by the server. Fetch with the caller's bearer — this is not an `<img src>` address. The `org_id` in the path must be the caller's token org: another account's id is a `404`.","operationId":"registry.getOrganisationAvatar","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stable identifier of the related org resource."},{"name":"v","in":"query","description":"Content digest, as carried by `avatar_url`. A client-side cache key; ignored by the server.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The image bytes, as `image/png`, `image/jpeg`, `image/webp` or `image/gif`.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The account has no avatar, the caller is not a member of the account, or a scope-bound token lacks `settings:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend or the avatar store is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"put":{"tags":["organisations"],"summary":"Set the account's avatar","description":"Store the picture a console renders for the account, replacing any current one. **Gateway-native**: the registry holds the bytes and serves them; nothing is forwarded to the control plane. Send the **raw image bytes** as the request body: a PNG, JPEG, WebP or GIF, at most 2 MiB. The format is read from the bytes, so `Content-Type` is optional — send `application/octet-stream`, or omit it, and the type is detected; a specific type that disagrees with the bytes is rejected rather than corrected. SVG is not accepted. Account admins only (`settings_manage`). The `org_id` in the path must be the caller's token org: another account's id is a `404`.\n\nRead it back with `GET /organisations/{org_id}/avatar`, whose path this response reports as `avatar_url`; the `?v=` on it is the image's content digest, a client cache key the server ignores.","operationId":"registry.updateOrganisationAvatar","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stable identifier of the related org resource."},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"The raw image bytes.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"200":{"description":"The avatar was set; `avatar_url` is where to read it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarDto"}}}},"400":{"description":"The request body is empty.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, the path org is not the caller's, or a scope-bound token lacks `settings:manage`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The image is larger than 2 MiB.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The bytes are not a PNG, JPEG, WebP or GIF.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"`Content-Type` names a media type the bytes are not.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_field"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend or the avatar store is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["invalid_field"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"delete":{"tags":["organisations"],"summary":"Clear the account's avatar","description":"Remove the account's picture, so `GET /organisations/{org_id}/avatar` answers `404` and a console falls back to whatever it draws for an account without one. Gateway-native. Account admins only (`settings_manage`). Idempotent: an account with no picture answers `204` unchanged. The stored bytes are content-addressed and may be shared, so they are not reclaimed here. The `org_id` in the path must be the caller's token org: another account's id is a `404`.","operationId":"registry.deleteOrganisationAvatar","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stable identifier of the related org resource."}],"responses":{"204":{"description":"The avatar is cleared."},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, the path org is not the caller's, or a scope-bound token lacks `settings:manage`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}/domains":{"get":{"tags":["organisations"],"summary":"List account email domains","description":"The account's attached email domains, proxied from the control plane. Account admins only. The inbound query string is passed through unchanged.","operationId":"registry.listDomains","parameters":[{"name":"org_id","in":"path","description":"The account id (must be the caller's own).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of email domains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainsPage"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, or a scope-bound token lacks `settings:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["organisations"],"summary":"Attach an email domain","description":"Attach an email domain to the account, proxied from the control plane. Account admins only. The request body is forwarded verbatim. Attach is idempotent: a fresh attach is a 201, and resuming an already-attached domain is a 200.","operationId":"registry.attachDomain","parameters":[{"name":"org_id","in":"path","description":"The account id (must be the caller's own).","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"Opaque request body, forwarded to the control plane verbatim.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"200":{"description":"The domain was already attached; the attach resumed with a fresh verification link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachedDomainDto"}}}},"201":{"description":"The domain was attached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachedDomainDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, or a scope-bound token lacks `settings:manage`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The domain conflicts with an existing attachment.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"The domain failed validation.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}/domains/{domain_id}":{"delete":{"tags":["organisations"],"summary":"Detach an email domain","description":"Detach one email domain from the account by id, proxied from the control plane. Account admins only.","operationId":"registry.detachDomain","parameters":[{"name":"org_id","in":"path","description":"The account id (must be the caller's own).","required":true,"schema":{"type":"string"}},{"name":"domain_id","in":"path","description":"The email domain id: letters, digits, `_` and `-` only, at most 128 characters.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The domain was detached."},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such domain, a malformed domain id, the caller is not an account admin, or a scope-bound token lacks `settings:manage`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}/roles":{"get":{"tags":["organisations"],"summary":"List the account's roles","description":"The account's assignable roles, each as an object carrying its per-org `id` and `name` (a role is a per-org identity, not a bare label). Any account member may read; the roster is gateway-native, so there is no control-plane call.","operationId":"registry.listRoles","parameters":[{"name":"org_id","in":"path","description":"The account id (must be the caller's own).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The account's roles as `{id, name}` objects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleListDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not a member of the account, or a scope-bound token lacks `members:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/organisations/{org_id}/settings":{"patch":{"tags":["organisations"],"summary":"Update an organisation's settings","description":"Update the caller's own account settings, an allowlist of the fields a member may change (`join_policy`, `auth_method`, `restrict_invites_to_domains`, `revoke_credentials_on_offboard`). Validated here, then forwarded on the caller's own bearer to the control plane, which is the system of record. Only fields present in the body are forwarded, so an unset field is left untouched. `join_policy` must be one of `open_auto_join`, `request_to_join`, `invite_only`, `closed`; `auth_method` must be one of `magic_otp`, `google`, `enterprise_sso` — both closed vocabularies upstream, so a value outside them is a `400` here rather than a round trip. `auth_method` is **singular**: it adds one method, and the account record reports the resulting set as the read-only `allowed_auth_methods` array; sending that array is a `400`. The account **profile** (`name`) is not part of this surface — send it to `PATCH /organisations/{org_id}`; naming it here is a `400` (an unknown field to this route, rejected by `deny_unknown_fields`). Honors `If-Match`. The `org_id` in the path must be the caller's token org: another account's id is a `404`, checked before anything else.","operationId":"registry.updateOrganisationSettings","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"},"description":"Stable identifier of the related org resource."},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganisationSettingsDto"}}},"required":true,"description":"Input for Update an organisation's settings."},"responses":{"200":{"description":"The updated account record, proxied from the control plane. The plane has one account-update operation, so the body is the whole record, not a settings-only projection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationRecordDto"}}}},"400":{"description":"The request body is malformed or empty, a field failed validation, or an unknown field (such as `name`) was sent.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not an account admin, the path org is not the caller's, or a scope-bound token lacks `settings:manage`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"412":{"description":"The `If-Match` precondition failed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["precondition_failed"]}}}],"description":"RFC 7807 problem document for 412 (Precondition Failed)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"412":["precondition_failed"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/releases":{"get":{"tags":["releases"],"summary":"List releases","description":"Every release the caller can read, newest first. Scoped to the caller's readable workspace set the way `/action-runs` is, so a release in a workspace the caller holds no role on is absent rather than refused. A caller readable on more than 10,000 workspaces sees a floor rather than a refusal, and `is_truncated` is `true`: the items and `page.total` then cover only part of what the caller may read.\n\nEvery status is included, `withdrawn` among them: a shipping record that hid its own retractions would be the wrong record.\n\nThe shared list grammar: `filter[field][op]=` over `release_id`, `artifact_id`, `kind`, `workspace_id`, `version_id`, `channel`, `version_ordinal`, `version_label`, `visibility`, `release_status`, `created_at`, `updated_at` and `released_at`; `sort=` over the same fields — `sort=-released_at` for what shipped most recently, which for an `auto` policy's release is not what was queued most recently; `limit` (default 50, clamped to 500), `offset` (at most 10 000) and `count=false` to skip `page.total`. The migration that created this table seeded a row per version of every artifact, so an account's full history is large — a browse that only wants the recent ones should pass `count=false`.","operationId":"registry.listReleases","parameters":[{"name":"filter","in":"query","description":"e.g. filter[release_status][eq]=released, or filter[channel][eq]=latest.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Release fields, `-` for descending. Default -created_at.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size. Defaults to 50; larger than 500 is clamped to 500.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"offset","in":"query","description":"Rows to skip. At most 10 000.","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"count","in":"query","description":"`false` skips `page.total`.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasePage"}}}},"400":{"description":"An unknown or un-filterable field, an illegal operator, a malformed handle, a zero limit or an over-cap offset.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/releases/{release_id}/withdraw":{"post":{"tags":["releases"],"summary":"Withdraw a release","description":"Unship a release. If it was the channel's current one, the newest `superseded` release on that channel **whose version is still active** is promoted back — a channel with nothing current on it breaks every consumer that resolves it. An archived or blocked version is never restored; if no recent release qualifies, the channel is left with nothing current. That is the opposite of `POST …/archive`, which retires every release of the line and restores nothing.\n\nA **pending** release may be withdrawn too. It never shipped, so nothing is promoted back.\n\nRequires `manage` on the artifact's workspace, or `update` plus being the artifact's owner.","operationId":"registry.withdrawRelease","parameters":[{"name":"release_id","in":"path","description":"Release handle (rel_…)","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawBody"}}},"required":true,"description":"Input for Withdraw a release."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDto"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such release, or it is already withdrawn.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"Somebody else settled this release first, or the artifact moved to another workspace while the withdrawal was in flight; re-read and retry.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/repos":{"get":{"tags":["repos"],"summary":"List repos","description":"Return a page of the non-deleted repos the caller can discover. Supports the shared query grammar: `filter[field][op]=`, `sort=`, `q=`, `limit`/`offset`, and `count=false` to skip the total.\n\n**`source_metadata` is not served here.** This list pages at `discover`, which on this surface means any member of the account, and the provenance bag is caller-supplied and free-form — the repo-onboard flow writes `contributors[].email` into it, the same addresses `GET /detected-users` serves at `read`. Read one repo by id for the bag.\n\nFields: `name`, `display_name`, `description`, `source_type`, `repo_status`, `project_id`, `created_at`, `updated_at`.","operationId":"registry.listRepos","responses":{"200":{"description":"A page of repos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReposPage"}}}},"400":{"description":"The query string is not valid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["repos"],"summary":"Create a repo","description":"Register a remote in a workspace the caller can create in. `source_uri` is **normalised** before storage — scheme forced to `https`, host lowercased, credentials, `.git` and trailing slashes stripped — so the value echoed back may differ from the one sent, and two spellings of one remote are one row. A `project_id`, if given, must live in the same workspace. Registering an existing readable remote returns that repo unchanged with `200`; an existing repo the caller cannot read returns `409 repo_exists` without exposing its fields.","operationId":"registry.createRepo","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRepoBody"}}},"required":true,"description":"Input for Create a repo."},"responses":{"200":{"description":"The remote was already registered; the existing repo is returned unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepoDto"}}}},"201":{"description":"Created","headers":{"Location":{"schema":{"type":"string"},"description":"The new repo's address, `/registry/v1/repos/{repo_id}`. Absent on a `200`, which created nothing."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepoDto"}}}},"400":{"description":"A handle is malformed, or `source_uri` is not a remote.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"No `create` on the named workspace.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"409":{"description":"The remote is already registered but unreadable, or a concurrent registration could not be resolved.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","repo_exists"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"`name` is not kebab-case, or the project is unknown or in another workspace.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"409":["conflict","repo_exists"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/repos/bulk":{"post":{"tags":["repos"],"summary":"Bulk create repos","description":"Register up to 100 remotes in one request. Per-item semantics are exactly `POST /repos`, and each item names its own `workspace_id` — so one batch can span workspaces and the receipt is checked per parent.\n\n**Partial success**: the response is always `207 Multi-Status` with one slot per index, even when every item succeeded, because a client that branches on the envelope status before reading the slots will get that branch wrong the first time one item fails. An item's failure carries the same problem body a single-item request would have returned, including `403` for a workspace the caller cannot write.","operationId":"registry.bulkCreateRepos","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepoBulkCreateRequest"}}},"required":true,"description":"Input for Bulk create repos."},"responses":{"207":{"description":"Multi-Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReposBulkResponse"}}}},"400":{"description":"`items` is empty or over the 100-item cap.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/repos/{repo_id}":{"get":{"tags":["repos"],"summary":"Get a repo","operationId":"registry.getRepo","parameters":[{"name":"repo_id","in":"path","description":"Repo handle (repo_…)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepoDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"description":"Use this operation to get a repo.","x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"delete":{"tags":["repos"],"summary":"Delete a repo","description":"Tombstone the repo. The `source_uri` is **released** in the same statement — a deleted repo that kept it would hold the unique slot forever behind a read filter that hides it, so re-registering the same remote would collide with a row nothing can return.","operationId":"registry.deleteRepo","parameters":[{"name":"repo_id","in":"path","description":"Repo handle (repo_…)","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"patch":{"tags":["repos"],"summary":"Update a repo","description":"Patch the label or the description. `name` is immutable — it is the machine handle — and `source_uri` is fixed at create, because it is the row's identity and the unique key.","operationId":"registry.updateRepo","parameters":[{"name":"repo_id","in":"path","description":"Repo handle (repo_…)","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchRepoBody"}}},"required":true,"description":"Input for Update a repo."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepoDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"An immutable field was supplied.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/repos/{repo_id}/archive":{"post":{"tags":["repos"],"summary":"Archive a repo","description":"Archive the repo: it stays readable and is excluded from a client's own default discovery by convention rather than by predicate — every read here still returns it, so a caller who wants archived rows gone filters `repo_status`.\n\nArchiving keeps the repo readable **and keeps its remote taken**: re-registering the same `source_uri` while an archive holds it is a `409`. That is deliberate — only a `DELETE` releases the remote — and it works because the archived row is readable, so the conflict names something the caller can inspect.\n\n**Idempotent**: archiving an archived repo is `200` with `changed: false`, because that is what a retrying client does and \"it is archived\" is the honest answer to both calls.\n\nAuthorized by `delete` on the repo's workspace — an archive is a removal from a client's point of view, so it takes the removal receipt and runs the same guard a `DELETE` does.","operationId":"registry.archiveRepo","parameters":[{"name":"repo_id","in":"path","description":"Repo handle (repo_…)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepoArchiveAck"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/search":{"post":{"tags":["discovery"],"summary":"Search artifacts","description":"Ranked discovery over artifacts in workspaces the caller can read, across kinds. `query` matches name, display name, description and the extension's indexed text; `filters` and the scope fields narrow; `fields` projects.\n\n**The ranking is the order.** A `sorts` body is rejected (400) — use `GET /artifacts?sort=` for an explicitly ordered browse.\n\n**L1 only.** This never joins a kind's own storage, so a detail-column filter is rejected and no `metadata` is returned. `GET /artifacts/{artifact_kind}?include_metadata=true` is the surface that has both.\n\n`strategy` selects the ranking: `fts` (default), `vector`, `hybrid`, or `group` — the graph filter, which returns an anchor plus its typed neighbourhood, anchor first, each item labelled with `role`/`rel_type`/`direction`/`weight`/`confidence`.\n\n**`vector` and `hybrid` take `query` as text** — the registry embeds it with the same model the stored vectors were written with, so a caller needs no embedder of its own and cannot drift out of the index's space. Supply `query_vector` instead to rank against a probe you embedded yourself; it wins when both are sent. A deployment with no model configured answers `503 not_configured` for these strategies rather than silently falling back to a recency browse; a probe the model refuses answers with the reason — `429 budget_exceeded`, `422 embedding_input_too_long`, `503 embedding_model_unavailable`.\n\n**Query grammar.** Bare words match any; `\"a phrase\"` is required; `-word` excludes; the last word (3+ characters) also matches as a prefix. At most 8000 characters.\n\n**`project_id` includes linked artifacts** — those the project owns and those linked into it.\n\n`page.total` is exact on `fts` and **absent** on the distance-ranked strategies: those rank a fixed 1000-deep candidate pool, a pool's size is not a match count, and `offset + limit` past it is refused.","operationId":"registry.search","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true,"description":"Input for Search artifacts."},"responses":{"200":{"description":"A ranked page in the `{items, limit, offset}` envelope, `total` present on `fts` only. Each item is an artifact L1 view; on `strategy:group` it also carries the graph labels, anchor first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPage"}}}},"400":{"description":"An unknown or un-filterable field, a bad handle, a zero limit or an over-cap offset, a `sorts` body, `group` with no anchor, a query with only excluded terms, a `query` over 8000 characters (`query_too_long`), or a distance-ranked window past the 1000-deep pool (`search_window_exceeded`). An over-cap `limit` is clamped to 500, not refused.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request","query_too_long","search_window_exceeded"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"`vector`/`hybrid` with neither `query` nor `query_vector`, `strategy:agent`, a non-finite or all-zero `query_vector` (`invalid_field`), a query the embedding model refused (`embedding_input_too_long`), or a project linking more than 1000 artifacts (`project_link_limit_exceeded`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["embedding_input_too_long","invalid_field","project_link_limit_exceeded","unprocessable","validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"429":{"description":"Embedding the query was refused: the caller's budget is exhausted (`budget_exceeded`) or the model is throttled (`rate_limited`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["budget_exceeded","rate_limited"]}}}],"description":"RFC 7807 problem document for 429 (Too Many Requests)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A distance-ranked strategy on a deployment with no embedding model (`not_configured`), a model unavailable to this caller (`embedding_model_unavailable`) or failing (`service_unavailable`), or — only on `include=permissions` — the workspace authorization backend being unavailable to resolve the advisory matrix.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","embedding_model_unavailable","not_configured","service_overloaded","service_unavailable","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request","query_too_long","search_window_exceeded"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["embedding_input_too_long","invalid_field","project_link_limit_exceeded","unprocessable","validation_failed"],"429":["budget_exceeded","rate_limited"],"500":["internal_error"],"503":["auth_unavailable","embedding_model_unavailable","not_configured","service_overloaded","service_unavailable","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/service-accounts":{"get":{"tags":["service-accounts"],"summary":"List service accounts","description":"The account's service accounts — `principal_type` is always `service_account`. An agent's identity is listed on its agent, and the platform's own identities are not listed at all.\n\n**Active only by default.** A `revoked` row is kept (the audit trail names it as an actor) and is listed when asked for with `filter[principal_status][eq]=revoked`.\n\nNarrowed through the shared query grammar rather than bespoke parameters: `filter[principal_status][eq]`, `filter[client_id][eq]`, `filter[principal_id][eq]`, `filter[created_by][eq]` (a member's own: the identities they provisioned), `filter[display_name][contains]`, and `q=` for a case-insensitive substring over `display_name`. `sort`, `limit`/`offset` and `count=false` behave as they do on every other collection. **Credential material is never returned** — each row's `credentials` array carries only the kind, expiry and last use of the credentials the identity holds, never a secret or a handle.\n\n**Last use.** Each `credentials` entry carries `last_used_at`, when the identity provider last saw that credential authenticate, whether through the gateway or presented to the provider directly, and `is_last_use_known`. The page reads the provider once per 100 rows that hold a credential, best-effort: when the provider cannot be read in time, the affected entries carry `is_last_use_known: false` and no `last_used_at`, and the list still succeeds. `is_last_use_known: true` with no `last_used_at` means the credential's current secret has not been used since it was issued or last rotated. A secret issued before the provider began recording use, or a credential the provider does not hold, is `false`: its disuse cannot be told from unrecorded use.\n\nFields: `principal_id`, `principal_type`, `principal_status`, `client_id`, `created_by`, `created_at`.","operationId":"registry.listServiceAccounts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccountsPage"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["service-accounts"],"summary":"Provision a machine identity","description":"Provisions a principal the account's automation can authenticate as: the gateway creates the OIDC client at the identity provider, mints the requested credential(s), returns them **once**, and stores the durable identity. The registry keeps no secret value — the response is the only copy, so record it now.\n\n**Reveal-once.** `credentials` names which kinds to mint — `secret` (a client secret), `api_key`, or both, at most one of each. Each is returned in the `credentials` array of the response and nowhere else; a caller that drops the response rotates to recover.\n\n**The id is minted, not supplied.** A durable `sa_…` handle the gateway assigns — the same value a token carries and a workspace roster names.\n\n**`service_account` only.** Every other type is refused with `400`. An `agent` identity is provisioned with its agent artifact through the agent extension, never here. The platform flavours (`action`, `registry`) are seated on every workspace in the account, so one created here would be an account-wide grant; the registry provisions those itself.\n\nAny member may call this — provisioning is gated on `organization#clients_create`, which is `member_access`, so a machine identity for your own automation is an ordinary member operation. It is `created_by` you, which is what the credential sub-resource checks on every later mint/rotate/revoke: you may manage the identities you provisioned, and an account admin (`organization#clients_manage`) may manage anyone's.\n\n**Runs as the calling operator.** The identity provider grants no machine-usable client-admin scope, so the caller's own bearer is forwarded; a synthetic principal with no token is refused `503`.\n\n**Seated `viewer` on the org root.** The new identity can read, and call, what the account shares in `org_default` — the built-in models among it — and nothing more; its spend is reported as yours. Any other workspace is a separate grant, because placing an identity there is that workspace's authority, not the account's: `PUT /workspaces/{workspace_id}/members/{principal_id}`.\n\n**Redirect URIs.** `redirect_uris` (at most 10; absolute `https`, or `http` on `localhost`, `127.0.0.1` or `[::1]` only; no fragment, wildcard or userinfo; trimmed and de-duplicated) makes the client an authorization-code client: it is granted `authorization_code` and `refresh_token` beside `client_credentials`, `openid` and `profile` beside its `contextplane:*` scopes, a `web` application type, and PKCE. Your own runner drives the browser flow and redeems the code with the client secret, so a client with redirect URIs needs a `secret`: `credentials` then defaults to `[\"secret\", \"api_key\"]`, and an explicit list without `secret` is `400`. The gateway's OBO broker does not serve service accounts, and adds no callback of its own.\n\n**Scopes are a ceiling, not a grant.** What the identity may do is what its workspace seats allow, cut down to what its `scopes` cover: `contextplane:read` reads, `contextplane:write` also creates and edits, `contextplane:manage` also deletes and governs workspaces and their members, and `oauth-clients:manage` provisions and administers machine identities. A scope never adds what the seats do not hold. The registry's own routes currently record what a credential's scopes would refuse rather than refusing it; the identity provider's OAuth-client routes already require `oauth-clients:manage`. `oauth-clients:manage` is for machine-only identities: with `redirect_uris` it is `400`.\n\n**Defaults.** Every field is optional: `principal_type` is `service_account`, `credentials` is `[\"api_key\"]` (`[\"secret\", \"api_key\"]` with `redirect_uris`), `scopes` is `[\"contextplane:read\", \"contextplane:write\", \"contextplane:manage\"]`, and an `api_key` lives `credential_ttl_seconds = 7776000` (90 days). `expires_in_seconds`, the Control Plane's name for the same lifetime, is accepted as an alias; sending both is `400`. An unknown field is `400`, so a caller still sending the retired register-only `client_id`/`secret_ref` is told rather than ignored.\n\n`display_name`, `redirect_uris` and `scopes` can change afterwards (`PATCH`); a machine identity's `client_id` and `principal_type` are what it *is*.","operationId":"registry.createServiceAccount","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServiceAccountBody"}}},"required":true,"description":"Input for Provision a machine identity."},"responses":{"201":{"description":"The provisioned identity, its scopes, and its credentials, revealed once.","headers":{"Location":{"schema":{"type":"string"},"description":"The new service account's address, `/registry/v1/service-accounts/{principal_id}`."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccountCreatedDto"}}}},"400":{"description":"An unknown field; a `principal_type` other than `service_account`; an unknown, repeated or empty `credentials`; a `scopes` entry outside `contextplane:read`, `contextplane:write`, `contextplane:manage` and `oauth-clients:manage`, an empty `scopes`, or `oauth-clients:manage` with `redirect_uris`; a `credential_ttl_seconds` outside 3600..=31536000 or sent with no `api_key` to mint; or a `display_name` that is blank, longer than 128 characters, or holds a control character; more than 10 `redirect_uris`, or one that is not an absolute `https` URL (or `http` on loopback), carries a fragment, wildcard or userinfo, or is blank; or `redirect_uris` with a `credentials` list that has no `secret`. A refused redirect URI is named by its position, never echoed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller is not an account member (holds no `clients_create`), or the identity provider refused the caller's own credentials.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"409":{"description":"The identity provider refused because of state it already holds.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No identity provider is configured on this deployment, or the caller carries no forwardable credential.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/service-accounts/{principal_id}":{"get":{"tags":["service-accounts"],"summary":"Get a service account","description":"One service account, revoked or not. Any other identity in the account — an agent's, or a platform identity — is `404` here.\n\n**Last use.** As on the list, each entry in `credentials` carries `last_used_at` and `is_last_use_known`, read from the identity provider on every call. The read is best-effort: when the provider cannot be read in time, or the caller carries no forwardable credential, `is_last_use_known` is `false`, `last_used_at` is absent, and the read still succeeds.","operationId":"registry.getServiceAccount","parameters":[{"name":"principal_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccountDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"delete":{"tags":["service-accounts"],"summary":"Revoke a machine identity","description":"**Soft-deletes** the whole identity: every live credential is revoked at the provider, then the row here is retired, its credential records are marked revoked, and every workspace seat it holds is dropped. Nothing is erased, and the identity provider's OIDC client is **not** archived — it is left holding no live credential.\n\n**The provider first**, deliberately. Each credential is revoked before anything local changes; if the provider refuses, the row stays active and the caller sees why. The reverse would leave a retired row beside a working credential — the state nobody can discover. A credential the provider no longer has (expired and purged, or revoked out of band) is already in the end state and does not block the delete.\n\n**The row stays readable.** `status` becomes `revoked` and `revoked_at` is stamped; the row is not removed, because every audit event this principal produced names it as the actor. Once `revoked`, the bind check rejects every token on next verify. Seats are dropped whatever their role (`admin`, `builder`, `viewer`). Returns the retired row (its `credentials` now empty) rather than 204.\n\n**Audited.** The retire is a `deleted` `service_principal` event, each revoked credential a `deleted` `service_principal_credential` event, and each dropped seat a `deleted` workspace member event — all attributed to the caller.\n\n**Idempotent, and a retry finishes the job.** If a step fails part-way (`503`), repeating the call revokes what is still live and drops the seats still held; a fully revoked identity answers its recorded state without calling the provider.\n\n**Who may revoke.** The member who provisioned the identity, or an account admin (`organization#clients_manage`) over anyone's. **Runs as the calling operator** — the caller's bearer is forwarded to the provider.","operationId":"registry.revokeServiceAccount","parameters":[{"name":"principal_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The retired identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccountDto"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller is not an account member (holds no `clients_create`), or the identity provider refused the caller's own credentials.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such identity in this account, or not one you may manage: a platform identity (`action`, `registry`) and an artifact's identity are provisioned rather than registered here (both unreachable by anyone), and an identity **another member provisioned** is reachable only by an account admin. A non-admin caller sees 404 for all four.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The identity provider refused because of state it already holds, or a credential changed in flight — retry.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No identity provider is configured, the caller carries no forwardable credential, or a local step failed part-way (the identity may already be revoked) — retry to finish.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"patch":{"tags":["service-accounts"],"summary":"Update a service account","description":"Changes the three editable fields, `display_name`, `redirect_uris` and `scopes`. An absent field is left as it is.\n\n**`display_name`.** `null` clears it. Every change is made under the identity's row lock, so a rename while another change runs is `409`. On an identity without redirect URIs a rename is the gateway's own record: nothing is sent to the identity provider, whose client name is a fixed operator label. On one with redirect URIs the name is also the label its consent screen shows, so a rename is sent to the provider under the same rules as a redirect change (runs as the calling operator). A cleared name labels the consent screen with the service account's opaque id.\n\n**`redirect_uris`** replaces the list whole, validated as on create. `null` or `[]` clears it, and the client loses `authorization_code`, `refresh_token`, `openid` and `profile` with it; a first URI earns them. A list equal to the stored one is not sent to the provider. A change is converged at the identity provider first — the URIs, the grants and scopes they imply, and the client's registration metadata — and recorded here only once the provider accepts it, so a refusal changes nothing. The scopes sent never widen the client: they are the service account's scopes that the client still holds at the provider, unless the same request sets `scopes`. A non-empty list needs a live `secret` credential (`409` otherwise: mint one first). One change to an identity runs at a time; a second while one is in flight, or while its `secret` is being revoked, is `409` — retry. **Runs as the calling operator** when the list changes — the caller's bearer is forwarded.\n\n**`scopes`** replaces the set whole, validated as on create; `null` is `400`. It may narrow or widen: the scopes are a ceiling over the identity's seats, so widening never grants beyond them. A changed set is converged at the identity provider first, as a redirect change is, and recorded here once the provider accepts it; an unchanged set makes no provider call. It takes effect on the next token a credential is exchanged for: a token already issued keeps its scopes until it expires. `oauth-clients:manage` cannot sit beside `redirect_uris`: `400` when the body sets both, `409` when the stored list is non-empty. **Runs as the calling operator** when the set changes.\n\n`client_id`, `principal_type` and credentials are what the identity *is*, and any other field is `400`. A revoked service account is `404`.\n\n**Who may update.** The member who provisioned the identity, or an account admin (`organization#clients_manage`) over anyone's. Audited as `updated`.","operationId":"registry.updateServiceAccount","parameters":[{"name":"principal_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServiceAccountBody"}}},"required":true,"description":"Input for Update a service account."},"responses":{"200":{"description":"The updated identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccountDto"}}}},"400":{"description":"An unknown field; a `display_name` that is blank, longer than 128 characters, or holds a control character; `redirect_uris` refused as on create (named by position, never echoed); `scopes` that is `null`, empty, or names a scope outside the create allowlist; or `oauth-clients:manage` with a non-empty `redirect_uris` in the same body.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller is not an account member (holds no `clients_create`), or the identity provider refused the caller's own credentials.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such live service account here, or one you may not manage (another member's, and you are not an account admin).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"Another change to this identity is in progress (retry), a non-empty `redirect_uris` with no live `secret` credential, an identity-provider client holding none of the service account's scopes, `oauth-clients:manage` alongside stored redirect URIs (or redirect URIs added to an identity that holds it), or the identity provider refused the change because of state it holds.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The list or the scopes changed and no identity provider is configured, the caller carries no forwardable credential, or the provider or a local write is unavailable — retry.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/service-accounts/{principal_id}/credentials":{"post":{"tags":["service-accounts"],"summary":"Mint a credential on this identity","description":"Mints one more credential — a `secret` or an `api_key` — on an existing identity's OIDC client and returns it **once**. An identity holds at most one **live** credential of each kind, so minting a kind it already holds live at the provider is `409`; revoke it first, or rotate it.\n\nThe credential is created at the provider first, then recorded here with a `created` audit event. An `api_key` records the `credential_ttl_seconds` it was minted with (also accepted as `expires_in_seconds`), and every later rotation re-applies it. If this identity's record still shows a live credential of the kind that the provider no longer has (it expired, or was revoked out of band), the provider accepts the mint and the stale record is retired beside the new one — the kind never wedges.\n\n**Manageable by the identity's owner or an account admin.** The member who provisioned the identity may mint on it; an account admin (`organization#clients_manage`) may mint on anyone's. A platform identity (`action`, `registry`) and an artifact's identity are unreachable by anyone and answer `404`. **Runs as the calling operator** — the caller's bearer is forwarded to the provider.","operationId":"registry.mintServiceAccountCredential","parameters":[{"name":"principal_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintCredentialBody"}}},"required":true,"description":"Input for Mint a credential on this identity."},"responses":{"201":{"description":"The new credential, returned once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotatedCredentialDto"}}}},"400":{"description":"An unknown field, an unknown credential `kind`, or a `credential_ttl_seconds` outside 3600..=31536000 or sent with `kind: secret`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller is not an account member (holds no `clients_create`), or the provider refused the caller's own credentials.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such identity here, or one you may not manage (another member's, and you are not an account admin).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The provider already holds a live credential of that kind, or refused because of other state it holds.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No identity provider is configured, or the caller carries no forwardable credential.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/service-accounts/{principal_id}/credentials/{kind}":{"delete":{"tags":["service-accounts"],"summary":"Revoke one of this identity's credentials","description":"Revokes the named credential at the identity provider and marks its record here revoked — a **soft delete**: the record stays, audited `deleted`, and the identity and any other credential survive. The kind is then free to be minted again.\n\nThe provider first, deliberately: a refusal leaves the credential live and the caller told why. A credential the provider no longer has (expired and purged, or revoked out of band) is already in the end state, so the record is retired rather than stuck. Distinct from `DELETE /service-accounts/{principal_id}`, which revokes the whole identity.\n\n**A `secret` backs `redirect_uris`.** While the identity has redirect URIs, revoking its `secret` is `409`: the code exchange authenticates with it. Clear `redirect_uris` first (`PATCH`).\n\n**Manageable by the identity's owner or an account admin** (`organization#clients_manage`). A platform identity and an artifact's identity are unreachable by anyone and answer `404`. **Runs as the calling operator** — the caller's bearer is forwarded.","operationId":"registry.revokeServiceAccountCredential","parameters":[{"name":"principal_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}},{"name":"kind","in":"path","description":"The credential kind: `secret` or `api_key`.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The identity, with its remaining credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceAccountDto"}}}},"400":{"description":"An unknown credential `kind`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller is not an account member (holds no `clients_create`), or the provider refused the caller's own credentials.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such identity here, no such credential of that kind, or an identity you may not revoke (another member's, and you are not an account admin).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"A `secret` while the identity still has `redirect_uris`, another change to the identity is in progress (retry), or the provider refused because of state it already holds.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No identity provider is configured, or the caller carries no forwardable credential.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/service-accounts/{principal_id}/credentials/{kind}/rotate":{"post":{"tags":["service-accounts"],"summary":"Rotate one of this identity's credentials","description":"Rotates the named credential and returns the new secret **once**. Nothing is stored: the response is the only copy, so a caller that loses it rotates again — the honest failure mode for reveal-once. The old material stops working when this returns.\n\n**An `api_key` keeps its lifetime.** Its expiry restarts from the rotation with the `credential_ttl_seconds` it was created with — a 90-day key rotates into a 90-day key, and an expired key into a live one (a key recorded before lifetimes were kept gets the 90-day default). Both kinds rotate in place at the provider, so a failed rotation leaves the old credential working.\n\nThe kind must be one the identity holds; rotating a kind it does not have — or one the provider has no record of — is `404`, not a mint. Audited as `updated` on the credential.\n\n**Manageable by the identity's owner or an account admin** (`organization#clients_manage`). A platform identity and an artifact's identity are unreachable by anyone and answer `404`; an artifact's credential is managed on its own kind's route. **Runs as the calling operator** — the caller's bearer is forwarded.","operationId":"registry.rotateServiceAccountCredential","parameters":[{"name":"principal_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}},{"name":"kind","in":"path","description":"The credential kind: `secret` or `api_key`.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The new secret, returned once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotatedCredentialDto"}}}},"400":{"description":"An unknown credential `kind`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller is not an account member (holds no `clients_create`), or the provider refused the caller's own credentials.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such identity here, no such live credential of that kind (here or at the provider), or an identity you may not rotate (another member's, and you are not an account admin).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The credential changed in flight — retry — or the provider refused because of state it already holds.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No identity provider is configured, or the caller carries no forwardable credential.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users":{"get":{"tags":["users"],"summary":"List users","description":"A page of the account's users, read natively from the registry. Any account member may read (`members_view`). Each row carries its account `role` (`admin` or `member`); an unassigned user reads as `member`. Supports the shared query grammar over `user_id`, `name`, `email`, `created_at` and `updated_at`.","operationId":"registry.listUsers","responses":{"200":{"description":"A page of the account's users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersPage"}}}},"400":{"description":"The query string is invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not a member of the account, or a scope-bound token lacks `members:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/me":{"get":{"tags":["users"],"summary":"Get the caller's own user record","description":"The caller's own profile, proxied to the control plane verbatim. The registry's own account `role` and its advisory `permissions` are **not** merged here — read them from `GET /auth/whoami`. Authenticated only — no role check, because the control plane resolves \"me\" from the asserted bearer.","operationId":"registry.getOwnUser","responses":{"200":{"description":"The caller's control-plane profile.","headers":{"ETag":{"schema":{"type":"string"},"description":"The profile's version tag, forwarded from the control plane. Send it back as `If-Match` on `PATCH /users/me` to make that write conditional."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnUserDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The token is scope-bound: a consented third-party or agent client may not read the user's own record.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"patch":{"tags":["users"],"summary":"Update the caller's own user record","description":"Update the caller's own user record, proxied to the control plane. Authenticated only; the control plane resolves \"me\" from the asserted bearer. The body is forwarded verbatim, and the control plane validates it. Send `If-Match: <etag>` - the `ETag` from `GET /users/me` or a prior `PATCH` - to make the write conditional; a stale tag is `412`. Without `If-Match` the write is last-writer-wins.","operationId":"registry.updateOwnUser","parameters":[{"name":"If-Match","in":"header","description":"The profile's `ETag` from a prior read; makes the write conditional.","required":false,"schema":{"type":["string","null"]}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"The profile fields to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOwnUserDto"}}},"required":true},"responses":{"200":{"description":"The updated user record.","headers":{"ETag":{"schema":{"type":"string"},"description":"The updated profile's version tag, for the next conditional write."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnUserDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The token is scope-bound: a consented third-party or agent client may not change the user's own record.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"412":{"description":"The `If-Match` tag is not the profile's current `ETag`: the record changed since it was read. Re-read it and retry.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["precondition_failed"]}}}],"description":"RFC 7807 problem document for 412 (Precondition Failed)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"412":["precondition_failed"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/me/avatar":{"put":{"tags":["users"],"summary":"Set the caller's own avatar","description":"Store the picture a console renders for the caller, replacing any current one. **Gateway-native**: the registry holds the bytes and serves them; nothing is forwarded to the control plane, whose identity-provider default picture is unaffected. Send the **raw image bytes** as the request body: a PNG, JPEG, WebP or GIF, at most 2 MiB. The format is read from the bytes, so `Content-Type` is optional — send `application/octet-stream`, or omit it, and the type is detected; a specific type that disagrees with the bytes is rejected rather than corrected. SVG is not accepted. Self only: the owner is the verified caller, and a machine principal has no avatar.\n\nRead it back with `GET /users/{user_id}/avatar`, whose path this response reports as `avatar_url` and which `GET /users` and `GET /users/{user_id}` carry for every user with a picture; the `?v=` on it is the image's content digest, a client cache key the server ignores.","operationId":"registry.updateOwnAvatar","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"The raw image bytes.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"200":{"description":"The avatar was set; `avatar_url` is where to read it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvatarDto"}}}},"400":{"description":"The request body is empty.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not a human member of the account, or the token is scope-bound.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The image is larger than 2 MiB.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The bytes are not a PNG, JPEG, WebP or GIF.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"`Content-Type` names a media type the bytes are not.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_field"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend or the avatar store is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["invalid_field"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"delete":{"tags":["users"],"summary":"Clear the caller's own avatar","description":"Remove the caller's picture, so `GET /users/{user_id}/avatar` answers `404` and `avatar_url` disappears from their directory row. Gateway-native; the control plane's identity-provider default is unaffected. Self only. Idempotent: a caller with no picture answers `204` unchanged. The stored bytes are content-addressed and may be shared, so they are not reclaimed here.","operationId":"registry.deleteOwnAvatar","responses":{"204":{"description":"The avatar is cleared."},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is not a human member of the account, or the token is scope-bound.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/me/oauth-grants":{"get":{"tags":["oauth-grants"],"summary":"List the caller's own delegated-access grants","description":"The caller's own OAuth grants - the consents that let an agent act on the caller's behalf - proxied from the control plane. Authenticated only: no role check, and no gateway ownership pre-fetch, because the control plane resolves \"me\" from the asserted bearer. A delegated caller (an agent acting for the user) is refused with a 404, because a borrowed authority must not read who else may act for the person. The control plane's `{ \"data\": [GrantRepr...] }` is forwarded verbatim, where a `GrantRepr` is `{ id, client_id, actor_sub, status, created_at, expires_at, revoked_at }`: `id` is the grant id (`oauthgrant_<21>`), `client_id` is the OAuth client the consent was granted to, `actor_sub` is the agent's service account acting on the user's behalf (the token's `act.sub`), `status` is one of `active`, `revoked`, or `expired`, and the three timestamps are RFC 3339 (`revoked_at` is omitted until revoked).","operationId":"registry.listOwnOauthGrants","responses":{"200":{"description":"The caller's OAuth grants.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OauthGrantsPage"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is a delegated agent or a scope-bound token and may not read this surface.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/me/oauth-grants/{grant_id}/revoke":{"post":{"tags":["oauth-grants"],"summary":"Revoke one of the caller's own delegated-access grants by id","description":"Revoke one of the caller's own OAuth grants, by id, withdrawing an agent's consent to act on the caller's behalf. Authenticated only: no role check, and no gateway ownership pre-fetch, because the control plane resolves \"me\" from the asserted bearer. A delegated caller (an agent acting for the user) is refused with a 404, because a borrowed authority must not revoke a peer's consent. A malformed `grant_id` (not `oauthgrant_<21 alphanumerics>`) is the same non-disclosing 404, never a 400 - the format check is also what keeps a caller-supplied id from being interpolated into an upstream path. The request body is forwarded verbatim.","operationId":"registry.revokeOwnOauthGrant","parameters":[{"name":"grant_id","in":"path","description":"The control-plane OAuth-grant id (oauthgrant_<21>).","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"Opaque request body, forwarded to the control plane verbatim.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"200":{"description":"The grant was revoked; the body is the revoked grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OauthGrantDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such grant belongs to the caller, or the caller is a delegated agent or a scope-bound token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/me/sessions":{"get":{"tags":["sessions"],"summary":"List the caller's own sessions","description":"The caller's own sessions, proxied from the control plane. Authenticated only - no role check, because the control plane resolves \"me\" from the asserted bearer. A scope-bound token (a consented third-party or agent client) is refused with a 404. Accepts a `status` query (`active`, `revoked`, or `all`); the default is the control plane's.","operationId":"registry.listOwnSessions","parameters":[{"name":"status","in":"query","description":"Filter by session status: active, revoked, or all","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the caller's sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSessionsPage"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The token is scope-bound: a consented third-party or agent client may not read the user's own sessions.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/me/sessions/revoke":{"post":{"tags":["sessions"],"summary":"Revoke the caller's own sessions","description":"Revoke all of the caller's own sessions, including the one making the call, proxied from the control plane. Authenticated only - no role check. The control plane has no \"me\" revoke-all, so the gateway names the caller's own user id in the plane's by-user revoke; only a direct user caller is \"me\", so a delegated agent or a service account is refused with a 404. The request body is forwarded verbatim.","operationId":"registry.revokeOwnSessions","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"Opaque request body, forwarded to the control plane verbatim.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"200":{"description":"The caller's sessions were revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedSessionsDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The caller is a delegated agent, a service account or a scope-bound token, not a user acting for themselves.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/onboard":{"post":{"tags":["users"],"summary":"Onboard the caller","description":"Scaffold the calling account and the caller's personal workspace: the account's shared root, the caller's own private root, their directory row, their groups, and the account membership every other read is gated on.\n\n**This is the first call a new caller makes.** Before it, the caller holds no account membership, so every account-scoped read answers `403` and the caller has no workspace to create anything in.\n\n**It also installs the deployment's extensions**, in dependency order, for any of them this account does not have yet — firing each one's `pre_install` gate and seeding `post_install` hook under **your** bearer, exactly as `POST /apps/{app}/install` does. On a brand-new account that is the whole set; on an existing one it is usually none, so a repeat onboard fires no install hooks at all. An account whose installs were interrupted completes on its next onboard.\n\n**Idempotent.** A repeat call re-reads what exists and answers `200` with the same assets and `is_created: false`. It also re-asserts the caller's access relationships, so a relationship lost to a partial earlier run heals on the next call rather than needing repair.\n\nThe caller's role on the **shared** root is `admin` for whoever created the account and `member` for everyone after them, and a re-onboard preserves whatever the roster says — a caller whose role was changed is not restored to `admin` by signing in again.\n\n**A machine identity may not call this**, and gets `403`. Account membership is held by people; a service account, an agent's own identity and an action identity each already hold whatever seats they were granted where they were provisioned. A token carrying no `user_id` claim, such as one an OAuth client minted with `client_credentials`, is a machine identity here too, whether or not the registry knows the client.","operationId":"registry.onboard","responses":{"200":{"description":"OK","headers":{"X-Atlan-Consistency-Token":{"schema":{"type":"string"},"description":"A read-your-own-writes token for the account membership and workspaces this onboard just wrote. Store it and send it back as `X-Atlan-Consistency-Token` on your first `GET /workspaces` so that list sees them instead of a stale replica."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardResponse"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"**The caller is a machine identity.** A service account, an agent's own identity, an action identity, or any token without a `user_id` claim (an OAuth `client_credentials` token) does not onboard: account membership is held by people, so there is no personal workspace or account seat for one to be given. Terminal — a retry answers the same. Use a user token.\n\nOr: the identity provider refused this caller, because provisioning machine identities requires permission to manage OIDC clients.\n\nOr: this is a platform organisation that none of its designated administrators has signed in to yet. It opens to its other members once one has.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"409":{"description":"An extension this account needs is disabled and cannot be installed; or the identity provider refused to provision this account's machine identities — the body carries its reason. Distinct from `503` deliberately: a refusal does not become true on a retry.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"422":{"description":"An extension's own install gate refused this account. The body carries the extension's reason. Nothing is rolled back — whatever installed before it stays installed, and a retry resumes from there.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"Machine-identity provisioning is unavailable, the app catalogue could not be prepared, or a concurrent change (a deployment rolling out) kept the account locked through the server's own retries. Onboarding is refused rather than half-applied, and the call is idempotent, so a retry is safe.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"409":["conflict"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/sessions/{session_id}":{"get":{"tags":["sessions"],"summary":"Read one of the caller's own sessions by id","description":"One of the caller's own sessions, by id. Self-scoped by a gateway ownership check: the gateway fetches the session from the control plane and confirms the caller owns it before rendering it. A session that is not the caller's, absent, or a malformed id all answer 404.","operationId":"registry.getOwnSession","parameters":[{"name":"session_id","in":"path","description":"The control-plane session id (session_<21>).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The caller's session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSessionDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such session belongs to the caller, or the token is scope-bound.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/sessions/{session_id}/revoke":{"post":{"tags":["sessions"],"summary":"Revoke one of the caller's own sessions by id","description":"Revoke one of the caller's own sessions, by id, ending a single session without touching the caller's others. Self-scoped by a gateway ownership check: the gateway fetches the session and confirms the caller owns it before forwarding the revoke to the control plane. A session that is not the caller's, absent, or a malformed id all answer 404. The control plane answers with the session as it read it before revoking, so a session that was active still shows `status: \"active\"` and no `revoked_at`; re-read the session for its revoked state.","operationId":"registry.revokeOwnSession","parameters":[{"name":"session_id","in":"path","description":"The control-plane session id (session_<21>).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The session was revoked; the body is the session as read before the revoke, not its revoked state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSessionDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such session belongs to the caller, or the token is scope-bound.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The control plane is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}":{"get":{"tags":["users"],"summary":"Get a user","description":"One of the account's users by id, read natively from the registry. Any account member may read (`members_view`). Carries the user's account `role`; an unassigned user reads as `member`.","operationId":"registry.getUser","parameters":[{"name":"user_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDirectoryDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such user in the caller's account, the caller is not a member of the account, or a scope-bound token lacks `members:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}/avatar":{"get":{"tags":["users"],"summary":"Get a user's avatar","description":"One user's picture as raw image bytes, with the media type it was stored as. Gateway-native. Any account member may read (`members_view`). `404` when the user has no picture or is not in the caller's account, so a client falls back to whatever it draws for a user without one. The `v` query parameter is a client cache key and is ignored by the server. Fetch with the caller's bearer — this is not an `<img src>` address.","operationId":"registry.getUserAvatar","parameters":[{"name":"user_id","in":"path","description":"The durable principal id","required":true,"schema":{"type":"string"}},{"name":"v","in":"query","description":"Content digest, as carried by `avatar_url`. A client-side cache key; ignored by the server.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The image bytes, as `image/png`, `image/jpeg`, `image/webp` or `image/gif`.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such user in the caller's account, the user has no avatar, the caller is not a member of the account, or a scope-bound token lacks `members:read`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend or the avatar store is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}/traces":{"get":{"tags":["users"],"summary":"List the traces this person created","operationId":"registry.listUserTraces","parameters":[{"name":"user_id","in":"path","description":"The stable directory user id — the same id `GET /users/{user_id}` takes, and the one trace ownership is keyed on.","required":true,"schema":{"type":"string"}},{"name":"start_time_unix_seconds","in":"query","description":"Window start, inclusive (unix epoch seconds, UTC).","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"end_time_unix_seconds","in":"query","description":"Window end, exclusive (unix epoch seconds, UTC).","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Page size.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","description":"Opaque resume token from a prior page's `page.next_cursor`. Bound to the caller, the access\npolicy and the scope that produced it, so it cannot be replayed across a policy change.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Trace ordering. Defaults to `started_at_desc` — newest first.\n\n**This param takes the trace store's own enum spelling, not the registry's `-field`\ngrammar.** `started_at_desc` / `started_at_asc`, and a leading `-` means nothing here.\nStated because the two dialects sit side by side on one surface, and a `sort` param that\ndocuments neither its accepted values nor its default leaves a client no way to discover\neither but by trying.","required":false,"schema":{"type":"string"}},{"name":"trace_ids","in":"query","description":"Narrow the list to these traces: how a caller checks which traces in a batch exist.\nComma-separated, 1–100 distinct trace ids, each 32 lowercase hex characters and not all\nzeros. Requires both `start_time_unix_seconds` and `end_time_unix_seconds`, within the usual\n365-day limit, and `limit` then defaults to 100. A trace recorded in several workspaces is one\nitem per workspace, so keep following `page.next_cursor` until it is absent, sending the same\n`trace_ids` each time. An id absent from every page is not visible to you in that window; an\nerror response never means an id is absent.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Newest first, cursor-paged. The `access` block states which tier answered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListEnvelope"}}}},"400":{"description":"An unparseable or expired cursor, an inverted or over-long window, or a `trace_ids` batch that is malformed, repeats an id, names more than 100, or comes without both window bounds.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["cursor_expired","invalid_cursor","invalid_query","invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller may see statistics for this person but not their raw traces. An empty page is deliberately **not** the answer: it would tell a caller who may not know that this person has no traces.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","aggregate_only","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such person in this account's directory. The same answer for an id that exists elsewhere, so the surface cannot probe.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"This deployment has no trace backend configured, trace data is temporarily unavailable, or the `audit_read` authorization check a cross-user read needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","not_configured","service_overloaded","traces_unavailable","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"description":"Use this operation to list the traces this person created.","x-gateway-error-codes":{"400":["cursor_expired","invalid_cursor","invalid_query","invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","aggregate_only","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","not_configured","service_overloaded","traces_unavailable","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}/traces/stats/query":{"post":{"tags":["users"],"summary":"Trace statistics for this person","operationId":"registry.queryUserTraceStats","parameters":[{"name":"user_id","in":"path","description":"The stable directory user id.","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"description":"A trace-statistics query: the window, the metrics, and `group_by`. The creator scope is set by this surface from the path id and any `creator_user_ids` in the body is ignored — a client-supplied one would widen the aggregation past the person named in the path.","content":{"application/json":{"schema":{}}},"required":true},"responses":{"200":{"description":"The requested aggregates. Answered for every org member, including one who may not read this person's raw traces.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/gateway.TraceStatsEnvelope"}}}},"400":{"description":"The body is not a JSON object, or the query is malformed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such person in this account's directory.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No trace backend is configured, or the trace backend did not answer in time (`traces_unavailable`); the latter is worth retrying, since panels that finished are cached.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"description":"Use this operation to trace statistics for this person.","x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}/traces/{trace_id}":{"get":{"tags":["users"],"summary":"Read one of this person's traces","operationId":"registry.getUserTrace","parameters":[{"name":"user_id","in":"path","description":"The stable directory user id.","required":true,"schema":{"type":"string"}},{"name":"trace_id","in":"path","description":"The trace id, as returned by the list.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The trace, sliced to what this caller may see.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceDetailView"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Statistics-only access.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such person, or no such trace **owned by them** — the two are one answer on purpose, so a trace id cannot be tested against an arbitrary subject.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No trace backend configured, or the `audit_read` authorization check a cross-user read needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","not_configured","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"description":"Use this operation to read one of this person's traces.","x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","not_configured","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}/traces/{trace_id}/content":{"delete":{"tags":["users"],"summary":"Delete one trace's stored content","description":"The content plane's deletion: one transaction tombstones the control row, nulls the manifest and the content-derived title, writes the `trace_content_delete` audit row, and enqueues the physical object deletions — so the commit IS the deletion, every read is structure-only from that moment, and the bytes follow within the executor's retry budget. Permanent: a late-arriving part for a deleted trace is refused, and re-approval does not resurrect it. The trace's STRUCTURE — the timeline, counts, costs — is untouched, deliberately. Allowed to the trace's creator and to a holder of the account's `settings_manage`; the `user_id` in the path must be the creator, so an admin deleting on someone's behalf addresses the trace under that person.","operationId":"registry.deleteUserTraceContent","parameters":[{"name":"user_id","in":"path","description":"The trace creator's stable directory id.","required":true,"schema":{"type":"string"}},{"name":"trace_id","in":"path","description":"The trace whose content goes.","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"query","description":"The workspace the trace lives in.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceContentDeletionDto"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Not the creator and no `settings_manage` on the account — or no receipt on the named workspace.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No content was ever stored for this trace in this workspace, or the path's user is not its creator.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/users/{user_id}/traces/{trace_id}/spans":{"get":{"tags":["users"],"summary":"List the spans of one of this person's traces","operationId":"registry.listUserTraceSpans","parameters":[{"name":"user_id","in":"path","description":"The stable directory user id.","required":true,"schema":{"type":"string"}},{"name":"trace_id","in":"path","description":"The trace id.","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","description":"Opaque resume token from a prior page's `page.next_cursor`.","required":false,"schema":{"type":"string"}},{"name":"fields","in":"query","description":"Comma-separated field groups: `core`, `io`, `metadata`, `attributes`,\n`events`, `usage`, `cost`, `error`. Omitted returns `core` only (identity,\ntiming, status); request `io` for input and output. An unknown group is\nrefused with `400`.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paged spans, sliced to what this caller may see.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpanListEnvelope"}}}},"400":{"description":"An unparseable or expired cursor.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Statistics-only access.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such person, or no such trace owned by them.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"No trace backend configured, or the `audit_read` authorization check a cross-user read needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","not_configured","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"description":"Use this operation to list the spans of one of this person's traces.","x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","not_configured","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces":{"get":{"tags":["workspaces"],"summary":"List workspaces","description":"A page of the **active** workspaces the caller can discover. Archived rows are excluded **by default**, and `filter[workspace_status][eq]=archived` (or `[in]=active,archived`) is the only way to see them — there is no separate flag, so a status filter governs the page outright instead of fighting a default. `deleted` rows are never listed, however you filter.\n\nSupports the shared grammar: `filter[field][op]=`, `sort=`, `q=`, `limit`/`offset`, `count=false`. Fields: `name`, `display_name`, `description`, `kind`, `workspace_status`, `parent_id`, `created_at`, `updated_at`. The bare spellings `workspace_status`, `status`, `kind`, `parent_id` and `name` are refused with a `400` naming the `filter[...][eq]=` form, rather than silently widening the page as they used to; any other unrecognised parameter is still ignored.\n\n`include=member_count` attaches each row's roster size from one grouped read. It is **absent rather than zero** on a workspace the caller can discover but not read into: this list runs under `discover`, which reaches through `discoverable_by`, while the count is taken under `read` on the membership rows — so a headcount is not something discovery alone reveals.\n\n`include=artifact_counts` attaches each row's `artifact_count` and its per-kind `artifact_count_by_kind` breakdown, from one grouped read — the pair the pre-Postgres stack served here and the cutover dropped. Unlike `member_count` it is present on **every** row of the page, including a workspace the caller can discover but has not joined, and a `0` therefore means zero: it is taken under the page's own `discover` receipt, because a count of artifacts identifies nobody. It counts what `POST /aggregate` counts — live heads, no system artifacts, no archived ones, discoverable kinds only — so the number does not change when the caller joins.\n\n`include=permissions` attaches each row's advisory `can_*` capability matrix. Advisory only — a UI gates controls on it; it never authorizes a request.","operationId":"registry.listWorkspaces","parameters":[{"name":"include","in":"query","description":"Opt-in embeds, comma-separated. `member_count` attaches each row's roster size; `artifact_counts` attaches its artifact volume by kind and in total; `permissions` attaches the caller's advisory `can_*` capability matrix.","required":false,"schema":{"type":"string"}},{"name":"X-Atlan-Consistency-Token","in":"header","description":"Optional read-your-own-writes token. Echo the `X-Atlan-Consistency-Token` a recent write returned, and this read is pinned to at least that revision so it sees your own change instead of a stale replica. Omit it for the fastest read. An unrecognised token is ignored and the read still succeeds.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacesPage"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The advisory capability matrix could not be resolved because the workspace authorization backend is unavailable. Only reachable on `include=permissions`; retry without it to proceed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"post":{"tags":["workspaces"],"summary":"Create a workspace","description":"Mint a child workspace under a parent the caller may write in. `parent_id` defaults to the account's `org_default` root. `name` is the kebab-case machine handle and is also the marketplace plugin slug. A later rename changes that slug and orphans existing installs. Reach follows the tree the workspace lands in: the shared tree is org-discoverable, a personal tree is not.","operationId":"registry.createWorkspace","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceBody"}}},"required":true,"description":"Input for Create a workspace."},"responses":{"201":{"description":"Created","headers":{"Location":{"schema":{"type":"string"},"description":"The new workspace's address, `/registry/v1/workspaces/{workspace_id}`."},"X-Atlan-Consistency-Token":{"schema":{"type":"string"},"description":"A read-your-own-writes token, present when this request changed workspace authorization. Store it and echo it as `X-Atlan-Consistency-Token` on your next read so that read sees this write; absent when the request touched no authorization relationships, in which case keep the token you already held."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/registry.WorkspaceView"}}}},"400":{"description":"`name` is not kebab-case, or `parent_id` is malformed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller may not create in that parent.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The parent does not exist or is not visible.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"The result would breach the nesting cap.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/bulk":{"post":{"tags":["workspaces"],"summary":"Bulk create workspaces","description":"Create up to 100 workspaces in one request. Each item runs the full single-item flow independently — parent resolution, the depth cap, the access relationships and the member projection — so a failed item that grants nothing also creates nothing.\n\n**Partial success**: always `207 Multi-Status`, one slot per index. Items may name different parents, and the `create` receipt is checked per distinct parent.\n\nA batch may not name a workspace created earlier *in the same batch* as a parent: parents are resolved from a read set taken once, before the first item, so a just-created sibling is not in it. That is deliberate rather than incidental — the alternative is a batch whose meaning depends on item order.","operationId":"registry.bulkCreateWorkspaces","parameters":[{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceBulkCreateRequest"}}},"required":true,"description":"Input for Bulk create workspaces."},"responses":{"207":{"description":"Multi-Status","headers":{"X-Atlan-Consistency-Token":{"schema":{"type":"string"},"description":"A read-your-own-writes token, present when this request changed workspace authorization. Store it and echo it as `X-Atlan-Consistency-Token` on your next read so that read sees this write; absent when the request touched no authorization relationships, in which case keep the token you already held."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacesBulkResponse"}}}},"400":{"description":"`items` is empty or over the 100-item cap.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/recommendations":{"get":{"tags":["workspaces"],"summary":"Recommend workspaces to join","description":"The workspaces the caller should consider joining, best first. **Suggest-only**: this reads, and joining remains the separate explicit act `PUT /workspaces/{workspace_id}/members/me`.\n\nThree signals are fused by reciprocal rank. **`detected_contributor`** — the caller's verified address appears in an onboarded repo's contributor history there. **`nearby`** — it is the parent, a child, or a sibling of a workspace the caller is already seated in and recently active in. **`text_match`** — with `q`, its `name`, `display_name` or `description` matched, using the same substring grammar as `GET /workspaces?q=`.\n\nOnly workspaces the caller can **actually join right now** are listed: active, in the account's shared tree, not the org root, not already joined, and with every ancestor already joined — so no suggestion answers `409 join X first`.\n\nThe list is capped and has no window. `page.total` is absent because a fused ranking is not a count, and `limit`/`offset`/`sort`/`filter[…]` are refused rather than ignored. `score` is comparable **within one response and meaningless across two**: it is a sum of reciprocal ranks over this request's candidate set, never a probability or a similarity.","operationId":"registry.listWorkspaceRecommendations","parameters":[{"name":"q","in":"query","description":"Optional substring needle over `name`, `display_name` and `description`, matched exactly as `GET /workspaces?q=` matches it. Contributes a third ranked signal rather than filtering the result.","required":false,"schema":{"type":"string"}},{"name":"X-Atlan-Consistency-Token","in":"header","description":"Optional read-your-own-writes token. Echo the `X-Atlan-Consistency-Token` a recent write returned, and this read is pinned to at least that revision so it sees your own change instead of a stale replica. Omit it for the fastest read. An unrecognised token is ignored and the read still succeeds.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceRecommendationsPage"}}}},"400":{"description":"`q` is longer than the shared grammar's search cap, or a parameter this route does not accept was sent. This surface takes `q` only: it has no page window and no sort.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/{workspace_id}":{"get":{"tags":["workspaces"],"summary":"Get a workspace","description":"One workspace by handle. Workspace metadata uses `discover`, the same permission as the list. Reading artifacts, exports, or roster identities inside the workspace still requires `read`. **404 and 403 are distinguishable here**: an absent or deleted workspace is 404, while an existing but undiscoverable workspace is 403.\n\n`include=artifact_counts` attaches this workspace's `artifact_count` and its per-kind `artifact_count_by_kind` breakdown, taken under the same `discover` the row itself was read at, so it is served even to a caller who has not joined. It counts what `POST /aggregate` counts, so the number does not change on joining.\n\n`include=permissions` attaches the caller's advisory `can_*` capability matrix. Advisory only — a UI gates controls on it; it never authorizes a request.","operationId":"registry.getWorkspace","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (`workspace_…`) or the workspace's kebab-case `name`. The two grammars are disjoint, so no disambiguation is needed. A `name` is **mutable** — a `display_name` edit re-derives it — so a client that stores an address should store the handle, which every response echoes.","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Opt-in embeds, comma-separated. `artifact_counts` embeds the workspace's artifact volume by kind and in total; `permissions` embeds the caller's advisory `can_*` capability matrix.","required":false,"schema":{"type":"string"}},{"name":"X-Atlan-Consistency-Token","in":"header","description":"Optional read-your-own-writes token. Echo the `X-Atlan-Consistency-Token` a recent write returned, and this read is pinned to at least that revision so it sees your own change instead of a stale replica. Omit it for the fastest read. An unrecognised token is ignored and the read still succeeds.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/registry.WorkspaceView"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_query"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The advisory capability matrix could not be resolved because the workspace authorization backend is unavailable. Only reachable on `include=permissions`; retry without it to proceed.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_query"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded","workspace_authorization_unavailable"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"delete":{"tags":["workspaces"],"summary":"Delete a workspace and its subtree","description":"A soft delete: the workspace and every descendant are tombstoned atomically, and the access it granted is released with them. Refused for a singleton (`user_default`, `org_default`).","operationId":"registry.deleteWorkspace","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (`workspace_…`) or the workspace's kebab-case `name`. The two grammars are disjoint, so no disambiguation is needed. A `name` is **mutable** — a `display_name` edit re-derives it — so a client that stores an address should store the handle, which every response echoes.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The subtree contains a personal or org-default workspace, or it changed under a concurrent workspace move; a retry collects it again.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"patch":{"tags":["workspaces"],"summary":"Update a workspace's labels","description":"`display_name`, `name` and `description` are the mutable fields. An omitted field is unchanged; `description: null` clears it.\n\n**A `display_name` edit re-derives `name`**, the machine handle, by slugifying the new label — unless the body sets `name` explicitly. A label with nothing sluggable in it leaves the handle alone. The handle must be free among the live workspaces of the same **tree**, not the whole account, so one person's personal workspace name never denies another's; if it is taken the request is a `409` and the fix is to resend with an explicit `name`.\n\nA handle change is a one-way door for clients: `name` is the marketplace plugin slug's source, so a rename orphans every existing install. The `org_default` and `user_default` handles do **not** move — Control Plane provisioning matches those two by value — and asking is a `409`; their `display_name` is still editable.\n\n**`parent_id` moves the workspace** and its subtree under another shared-tree workspace. It takes `update` on the workspace and `create` on the destination, the same receipt a create under that parent takes: a destination the caller cannot see is a `404`, one it can see but not create in is a `403`. Restating the current parent asks nothing.\n\n**An archived workspace does not change**: relabelling it, moving it, or moving another workspace under it is `409` `workspace_archived`. The archive renamed it to free its handle, and a relabel must not take the handle back.","operationId":"registry.updateWorkspace","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (`workspace_…`) or the workspace's kebab-case `name`. The two grammars are disjoint, so no disambiguation is needed. A `name` is **mutable** — a `display_name` edit re-derives it — so a client that stores an address should store the handle, which every response echoes.","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchWorkspaceBody"}}},"required":true,"description":"Input for Update a workspace's labels."},"responses":{"200":{"description":"OK","headers":{"X-Atlan-Consistency-Token":{"schema":{"type":"string"},"description":"A read-your-own-writes token, present when this request changed workspace authorization. Store it and echo it as `X-Atlan-Consistency-Token` on your next read so that read sees this write; absent when the request touched no authorization relationships, in which case keep the token you already held."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/registry.WorkspaceView"}}}},"400":{"description":"`name` is not kebab-case or is over 40 characters.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller lacks `update` on the workspace, or `create` on the `parent_id` destination.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"The workspace, or the `parent_id` destination, does not exist or is not visible.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The derived or supplied handle is already held by a live workspace in this tree, or it is a frozen provisioning handle (`conflict`); or the workspace or the `parent_id` destination is archived (`workspace_archived`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","workspace_archived"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict","workspace_archived"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/{workspace_id}/archive":{"post":{"tags":["workspaces"],"summary":"Archive a workspace","description":"Archive the workspace **and its whole subtree**: a tree with an archived root and live children is not what a caller asking to archive a workspace meant.\n\nEvery node stays readable, and each one is **renamed** to `<name>-<id tail>` — so the bare handle is free for reuse the moment the archive commits, and the archived row is still addressable under the name it now displays.\n\nThat **moves the workspace's marketplace plugin path**, which is the cost of releasing the handle: an archived workspace should not keep holding a name a live one wants.\n\nTwo things an archive does that a delete does not, both because `archived` is a live status here:\n\n- the access the workspace granted is **kept**. Releasing it would leave a readable workspace nobody can read, which is a delete wearing an archive's name.\n- `deleted_by`/`deleted_at` are **not** stamped. They belong to a tombstone, and an archived workspace is not one.\n\nA personal or `org_default` workspace cannot be archived, for the same reason it cannot be deleted: it is provisioning identity, and an account with no tree root has nothing to create in.\n\n**Idempotent**, per node: `archived_count` is what this call changed, so a re-archive is `200` with `0`.\n\n**A re-archive re-runs the cascade.** If a cascade is still `pending` or `running`, the call answers with that run as `cascade_run_id` and starts nothing. Otherwise it records the next attempt — which is how a cascade that `failed` on a refused hook is finished once the refusal is resolved — and that run acts as **the caller**, who becomes the workspace's recorded archiver if they were not already.\n\nThe subtree is collected from a receipted read. A live descendant the caller cannot see is neither archived around (it would stay live under an archived parent, its contents never cascaded) nor archived through (that touches rows the caller was never shown): the archive is refused with `409` `workspace_subtree_unseen`, naming only how many, and succeeds once those workspaces' own admins have archived them.","operationId":"registry.archiveWorkspace","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (`workspace_…`) or the workspace's kebab-case `name`. The two grammars are disjoint, so no disambiguation is needed. A `name` is **mutable** — a `display_name` edit re-derives it — so a client that stores an address should store the handle, which every response echoes.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceArchiveAck"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The subtree contains a personal or org-default workspace, or it changed under a concurrent workspace move; a retry collects it again (`conflict`). Or it contains live workspaces the caller cannot see (`workspace_subtree_unseen`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","workspace_subtree_unseen"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict","workspace_subtree_unseen"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/{workspace_id}/export":{"get":{"tags":["workspaces"],"summary":"Export a workspace","description":"A one-shot L1 snapshot: every artifact that belongs to this workspace, plus its **first-level** children grouped by kind (`projects`, `workspaces`).\n\n**L1 only.** Artifacts carry no per-kind `metadata` and no relationships, and children carry no artifact counts — an export is a manifest, not a substitute for reading each row. A caller that needs a kind's own properties reads `GET /artifacts/{artifact_kind}/{artifact_id}`.\n\n**Uncapped, and deliberately so**: a snapshot with a page boundary in it is not a snapshot. The cost is real — a large workspace is a large response — which is why this is one request rather than a browse surface.\n\nThe requested workspace is not echoed back, and its own artifacts are **direct members only**: a project's linked library artifacts belong to the project, and `GET /projects/{project_id}/export` is where they resolve.","operationId":"registry.exportWorkspace","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (`workspace_…`) or the workspace's kebab-case `name`. The two grammars are disjoint, so no disambiguation is needed. A `name` is **mutable** — a `display_name` edit re-derives it — so a client that stores an address should store the handle, which every response echoes.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceExport"}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"The caller can discover the workspace but cannot read its contents.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such workspace in this account, or it is deleted.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/{workspace_id}/invitations":{"get":{"tags":["invitations"],"summary":"List pending invites into a workspace","description":"Pending invitations targeting one workspace, so a workspace admin without org-admin can see who is on the way in. Gated on workspace `read`.","operationId":"registry.listWorkspaceInvitations","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (workspace_…)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The pending invites into the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceInvitationListDto"}}}},"401":{"description":"The bearer token is missing or invalid.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"No such workspace, or the caller may not read it.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"The authorization backend is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/{workspace_id}/release-policy/{channel}":{"get":{"tags":["releases"],"summary":"Read a workspace's resolved release policy for a channel","description":"The **resolved** policy, not the stored row: exact `(workspace, channel)` row, else the channel's own definition, else the fail-safe default. `resolved_from` says which level answered for the policy as a whole — `workspace` whenever the workspace has a row, even one that sets nothing — and `sources` says which level decided each facet.\n\nThere is deliberately no inheritance from a parent workspace — a caller holding `read` on a child may hold nothing on its parent, so an inheriting resolver would either spend receipts it cannot get or read ancestor rows ungoverned.","operationId":"registry.getReleasePolicy","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (workspace_…)","required":true,"schema":{"type":"string"}},{"name":"channel","in":"path","description":"Channel slug, e.g. `latest` or `beta`","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasePolicyDto"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_request"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_request"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"},"put":{"tags":["releases"],"summary":"Set a workspace's release policy for a channel","description":"Requires **`manage`** on the workspace — workspace admins only. Not `update`: a member who may edit an artifact is not thereby a member who may decide whether artifacts ship.\n\nEvery facet is a double option — absent leaves it alone, a value sets it, and `null` clears it back to the level below: the channel's definition for `require_checks`, the fail-safe default (`auto`, `private`, `true`) for `mode`, `default_visibility` and `allow_version_override`, which the channel does not carry. Clearing every facet leaves the row in place, so `resolved_from` still reads `workspace`; `sources` reads the level below for each. A workspace cannot raise the channel's `allow_public` ceiling; asking for `public` where the org has not opened it resolves back to `private`.","operationId":"registry.setReleasePolicy","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (workspace_…)","required":true,"schema":{"type":"string"}},{"name":"channel","in":"path","description":"Channel slug","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetReleasePolicyBody"}}},"required":true,"description":"Input for Set a workspace's release policy for a channel."},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleasePolicyDto"}}}},"400":{"description":"An empty patch, or an unknown `mode`/`visibility`.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"No `manage` on the workspace.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"`unknown_release_channel`: the channel is not declared in this account.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unknown_release_channel","validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["unknown_release_channel","validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}},"/registry/v1/workspaces/{workspace_id}/visibility":{"patch":{"tags":["workspaces"],"summary":"Change a workspace's visibility","description":"Set a shared-tree workspace to `public` (the account can list and self-join it) or `private` (invisible to non-members, invite-only). The receipt is `manage` — an admin's — because visibility is a property of the workspace, like its roster, not of the content in it.\n\n**The funnel holds both ways.** Widening to `public` is refused if the parent is less open (a `422`): a child is never more open than its parent. Restricting to `private` is refused while any immediate child is still `public` (a `422` naming the child); make the children private first, bottom-up.\n\nRefused for a singleton (`org_default` is always public, `user_default` always private) and for a personal-tree workspace, which is private by tree and has no shared-tree visibility to set — both a `409`. An archived workspace's visibility is fixed too (`409` `workspace_archived`), so an archive cannot be reopened to discovery. Setting the visibility a workspace already has is a no-op `200`.","operationId":"registry.setWorkspaceVisibility","parameters":[{"name":"workspace_id","in":"path","description":"Workspace handle (`workspace_…`) or the workspace's kebab-case `name`. The two grammars are disjoint, so no disambiguation is needed. A `name` is **mutable** — a `display_name` edit re-derives it — so a client that stores an address should store the handle, which every response echoes.","required":true,"schema":{"type":"string"}},{"name":"Content-Encoding","in":"header","description":"Codings applied to the request body, outermost last. Send `base64`, or `gzip, base64` to compress first; the body is decoded before it is read and `Content-Type` still names the inner media type. Omit for an unencoded body.","required":false,"schema":{"type":"string","enum":["base64","gzip, base64"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetVisibilityBody"}}},"required":true,"description":"Input for Change a workspace's visibility."},"responses":{"200":{"description":"OK","headers":{"X-Atlan-Consistency-Token":{"schema":{"type":"string"},"description":"A read-your-own-writes token, present when this request changed workspace authorization. Store it and echo it as `X-Atlan-Consistency-Token` on your next read so that read sees this write."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/registry.WorkspaceView"}}}},"400":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["invalid_base64","invalid_gzip","invalid_json"]}}}],"description":"RFC 7807 problem document for 400 (Bad Request)."}}}},"401":{"description":"Missing or unverifiable bearer token.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"]}}}],"description":"RFC 7807 problem document for 401 (Unauthorized)."}}}},"403":{"description":"Caller is authenticated but not permitted on this resource.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["access_denied","account_suspended","forbidden","platform_principal_refused"]}}}],"description":"RFC 7807 problem document for 403 (Forbidden)."}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["not_found"]}}}],"description":"RFC 7807 problem document for 404 (Not Found)."}}}},"409":{"description":"The workspace is a provisioning singleton or a personal-tree workspace, whose visibility is fixed (`conflict`), or it is archived (`workspace_archived`).","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["conflict","workspace_archived"]}}}],"description":"RFC 7807 problem document for 409 (Conflict)."}}}},"413":{"description":"The request body, encoded or decoded, exceeds its size limit.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"]}}}],"description":"RFC 7807 problem document for 413 (Payload Too Large)."}}}},"415":{"description":"The request body's content type or content encoding is not accepted here.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["unsupported_content_encoding","unsupported_content_type"]}}}],"description":"RFC 7807 problem document for 415 (Unsupported Media Type)."}}}},"422":{"description":"An unknown visibility value, or a change that would break the funnel — widening past a less-open parent, or restricting while a child is still public.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["validation_failed"]}}}],"description":"RFC 7807 problem document for 422 (Unprocessable Entity)."}}}},"500":{"description":"Unexpected internal failure.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["internal_error"]}}}],"description":"RFC 7807 problem document for 500 (Internal Server Error)."}}}},"503":{"description":"A dependency this operation needs is unavailable.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["auth_unavailable","service_overloaded"]}}}],"description":"RFC 7807 problem document for 503 (Service Unavailable)."}}}},"504":{"description":"The request exceeded its processing deadline.","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable reason for this failure.","enum":["request_timeout"]}}}],"description":"RFC 7807 problem document for 504 (Gateway Timeout)."}}}}},"x-gateway-error-codes":{"400":["invalid_base64","invalid_gzip","invalid_json"],"401":["alg_mismatch","alg_not_allowed","audience_mismatch","invalid_api_key","missing_identity","missing_org","missing_user","signature_invalid","token_expired","token_malformed","token_missing","token_not_yet_valid","token_rejected","token_service_account_unbound","unauthorized","unknown_account","unknown_key","untrusted_issuer"],"403":["access_denied","account_suspended","forbidden","platform_principal_refused"],"404":["not_found"],"409":["conflict","workspace_archived"],"413":["compressed_payload_too_large","decompressed_payload_too_large","payload_too_large"],"415":["unsupported_content_encoding","unsupported_content_type"],"422":["validation_failed"],"500":["internal_error"],"503":["auth_unavailable","service_overloaded"],"504":["request_timeout"]},"x-gateway-error-contract":"native"}}},"components":{"schemas":{"AccessView":{"type":"object","description":"Advisory access block for UI banners — never an enforcement signal (the\ngateway already enforced access before the results were shaped).","required":["audience","slice","basis","allow_user_filter"],"properties":{"allow_user_filter":{"type":"boolean","description":"Whether the caller may filter by an explicit `user_id`."},"audience":{"type":"string","description":"`own` or `all` — whose traces are in scope."},"basis":{"type":"string","description":"`member` / `creator` / `admin` — why the caller has access."},"detail":{"type":"string","description":"`raw` or `aggregate_only` — whether raw trace rows are readable at all."},"slice":{"type":"string","description":"`full` or `skill_turn` — how much of a cross-user trace is visible."}}},"AggregateRequest":{"type":"object","description":"The `POST /aggregate` body.","properties":{"filters":{"type":"array","items":{"$ref":"#/components/schemas/FilterClause"},"description":"Per-field filters over L1 columns, ANDed into the `WHERE` before grouping."},"group_by":{"type":"array","items":{"$ref":"#/components/schemas/DimensionSpec"},"description":"Grouping dimensions, at most 4 — the group count is the product of their cardinalities.\n\nEmpty ⇒ one grand-total group. A group is emitted only for a value with at least one matching\nartifact, so an empty container is **absent** rather than present with `count: 0`; read a\nmissing key as zero."},"is_all_versions_included":{"type":["boolean","null"],"description":"Aggregate every live version rather than only the heads. Defaults to false."},"is_archived_included":{"type":["boolean","null"],"description":"Include archived artifacts. Defaults to false, matching the collection reads — an aggregate\nthat counted archived rows would disagree with the list it summarises."},"is_system_included":{"type":["boolean","null"],"description":"Include artifacts the deployment wrote. Defaults to false."},"limit":{"type":["integer","null"],"format":"int64","description":"Max groups. Defaults to 50; a larger value than 500 is clamped to 500, and `0` is refused.","minimum":1},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricSpec"},"description":"Measures, at most 8. Empty ⇒ a single `count`."},"offset":{"type":["integer","null"],"format":"int64","description":"Groups to skip. Defaults to 0, rejected above 10000.","minimum":0},"project_id":{"type":["string","null"],"description":"Narrow to one project: the artifacts it owns (`project_id`) **and** the ones linked into it,\nthe same scope `POST /search` applies. A project linking more than 1000 artifacts is refused\n(`422 project_link_limit_exceeded`). Grouping by `project_id` still groups by the artifact's\nown column."},"sort":{"type":"array","items":{"type":"string"},"description":"Sort keys over a `group_by` field name or a metric alias, `-key` for descending. Omitted ⇒\nthe first metric descending, tiebroken by the dimensions so offset pages stay stable."},"workspace_id":{"type":["string","null"],"description":"Narrow to one workspace. Omitted ⇒ every workspace the caller can read."}},"additionalProperties":false},"AggregationGroup":{"type":"object","description":"One group.","required":["key","metrics"],"properties":{"key":{"type":"object","description":"The dimension values, keyed by the field name as it was requested.\n\nA `null` value is a **real** group — the artifacts in no project — not an absence, so it is\nserialized rather than omitted. A handle-shaped key comes back as the `<prefix>_<body>`\nhandle the rest of the API speaks; `owner_id` is a bare Control-Plane user id in both\ndirections, because that is already its public form."},"metrics":{"type":"object","description":"The measures, keyed by alias."}}},"AggregationResponse":{"type":"object","description":"A page of groups.","required":["groups","page"],"properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/AggregationGroup"},"description":"Value of the `groups` field."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page of groups was served under. `page.total` is the number of **distinct\ngroups** matching the filter — not a row count."}}},"AppActionDto":{"type":"object","description":"One job an app declares it can run.","required":["job_id","app","name","execution_kind","is_user_authorable","updated_at"],"properties":{"app":{"type":"string","description":"Value of the `app` field."},"config_schema":{"type":["object","null"],"description":"Value of the `config_schema` field."},"description":{"type":["string","null"],"description":"Human-readable description."},"execution_kind":{"type":"string","description":"`activity` | `workflow`."},"is_user_authorable":{"type":"boolean","description":"Whether a user-authored action may name this job."},"job_id":{"type":"string","description":"`<app>/<job>` — what an action's DAG node references."},"name":{"type":"string","description":"Stable machine-readable name."},"output_schema":{"type":["object","null"],"description":"Value of the `output_schema` field."},"release":{"type":["string","null"],"description":"Value of the `release` field."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."}}},"AppActionsPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AppActionDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of AppActions resources."},"AppDto":{"type":"object","description":"An app: an extension as this account holds it.","required":["can_install","can_use","app","display_name","install_status","is_installed","is_pinned","categories","tags","install_metadata","installed_by","installed_at","updated_at"],"properties":{"access_expires_at":{"type":["string","null"],"description":"Clock deadline for these commercial rights, when bounded."},"access_reason":{"type":["string","null"],"description":"Why `can_install` and `can_use` are false, when they are: `subscription_required` when the\nplan does not grant the app, or `commercial_access_unavailable` when billing could not be\nread and both are refused until it can. Installation and stored data remain intact."},"app":{"type":"string","description":"The app's name, which is the extension's name."},"author":{"type":["string","null"],"description":"Who publishes this app, as display text."},"author_url":{"type":["string","null"],"description":"Value of the `author_url` field."},"can_install":{"type":"boolean","description":"Whether the active subscription permits new installation. User permissions also apply."},"can_use":{"type":"boolean","description":"Whether the active subscription permits using an existing installation."},"categories":{"type":"array","items":{"type":"string"},"description":"Always arrays on the wire, never `null` — a client iterating them should not have to\ndistinguish \"none\" from \"unset\"."},"contract_version":{"type":["integer","null"],"format":"int64","description":"Value of the `contract_version` field."},"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":"string","description":"Human-readable name."},"homepage_url":{"type":["string","null"],"description":"Value of the `homepage_url` field."},"icon_uri":{"type":["string","null"],"description":"The app's logo."},"install_metadata":{"type":"object","description":"Whatever the app's install hooks wrote back about this account."},"install_status":{"type":"string","description":"`available` | `installing` | `active` | `uninstalling` | `failed`."},"installed_at":{"type":"string","description":"Value of the `installed_at` field."},"installed_by":{"type":"string","description":"Value of the `installed_by` field."},"is_installed":{"type":"boolean","description":"Whether this account has the app turned on — `install_status == \"active\"`, and nothing\nelse. The transitional states are not installed: `installing` has not finished its seed and\n`failed` did not."},"is_pinned":{"type":"boolean","description":"Whether pinned."},"license":{"type":["string","null"],"description":"Value of the `license` field."},"readme_uri":{"type":["string","null"],"description":"Value of the `readme_uri` field."},"release":{"type":["string","null"],"description":"Value of the `release` field."},"repo_url":{"type":["string","null"],"description":"Value of the `repo_url` field."},"running":{"oneOf":[{"$ref":"#/components/schemas/RunningDto","description":"What this deployment is serving for the app right now, read from the live probe snapshot\n(`/readyz`) — distinct from `release`, which is what this account holds and may be pinned.\nAbsent when the app is not running on this deployment or its process did not answer."},{"type":"null"}],"description":"Value of the `running` field."},"summary":{"type":["string","null"],"description":"Value of the `summary` field."},"support_url":{"type":["string","null"],"description":"Value of the `support_url` field."},"tags":{"type":"array","items":{"type":"string"},"description":"Value of the `tags` field."},"ui_path":{"type":["string","null"],"description":"Where the app's browser UI is mounted, relative to the gateway root (`/skill/v1/ui/`), or\nabsent when it serves none."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."}}},"AppsPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AppDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Apps resources."},"ArtifactConflictProblem":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"existing_artifact_id":{"type":["string","null"],"description":"Present only when `code == \"duplicate_content\"`; absent when the existing\nartifact could not be resolved."}}}],"description":"The one problem body with an extra member: a content-dedup `409` names the\nartifact that already holds the content, so a client recovers it without a\nfollow-up search.\n\nA separate type rather than an `Option` on [`ProblemDetails`] because a single\nshared schema meant all 816 error responses in the published specs advertised\n`existing_artifact_id`, and only this one can return it."},"ArtifactView":{"type":"object","description":"The L1 envelope plus the kind's own properties, nested.\n\n**`metadata` is nested rather than flattened**, and that is the kind-polymorphic surface's own\ndecision: one route serves every kind, so a flattened property would be indistinguishable from an\nenvelope key. Each extension's typed per-kind view flattens it one layer out, which is where the\nkind is known — `file`'s `FileArtifact` is the worked example.","required":["id","kind","name","display_name","artifact_status","commit_ts","etag","workspace_id","version_ordinal","version_id","is_released","is_latest","is_system","source_type","created_by","created_at","updated_by","updated_at"],"properties":{"app":{"type":["string","null"],"description":"The app that registered the kind. Absent on the cross-kind list, which would need one\ncatalogue read per distinct kind on the page to fill it.\n\nNamed `extension` until `apps-2026-09-15-the-extension-tables-are-dropped`; renamed with no\nalias, for the reason `KindDto.extension` was — a name that answers on one spelling and not\nthe other is a second thing to keep in step."},"artifact_status":{"type":"string","description":"`pending_review`, `active`, `blocked` or `archived`. Only `deleted` is a tombstone, and it\nnever appears on a read.\n\nIt says nothing about whether this version is *distributed*: that follows the release, so an\n`active` head with no current release is discoverable and shipped to nobody."},"commit_ts":{"type":"string","description":"The cross-table monotonic cursor. `updated_at` on this stack: there is no separate commit\ntimestamp column, and the two agree for every purpose a cursor has."},"content_hash_hex":{"type":["string","null"],"description":"BLAKE3 of the canonicalised per-kind properties, hex: content provenance, which is what a\nversion pin cites. An envelope-only edit does not move it, so it is **not** the `If-Match`\ncomparand — [`Self::etag`] is. Named `_hex` for the shipped contract's sake."},"created_at":{"type":"string","description":"RFC 3339, millisecond precision."},"created_by":{"type":"string","description":"The principal who created this version."},"description":{"type":["string","null"],"description":"Always serialized, `null` when unset — unlike every other optional here, and matching the\nshipped contract."},"display_name":{"type":"string","description":"The human label. Defaulted to `name` at create, so always present."},"etag":{"type":"string","description":"The entity tag, hex: the value the `ETag` header carries and the one `If-Match` is compared\nagainst. It moves on any edit a `PATCH` can make — properties and envelope alike — so a\nconditional write sent from a stale read is `412`\n([artifacts-2026-09-28-the-etag-covers-the-envelope](../../../docs/architecture/decisions/0003-persistence-artifact-model-and-schema.md#artifacts-2026-09-28-the-etag-covers-the-envelope))."},"id":{"type":"string","description":"`<kind>_<26 chars>`. The only stable handle for this artifact."},"identity":{"oneOf":[{"$ref":"#/components/schemas/gateway.ArtifactIdentityRevealView","description":"Reveal-once machine credential; present **only** on the create response, never on a read."},{"type":"null"}],"description":"Value of the `identity` field."},"is_latest":{"type":"boolean","description":"Whether this row is the line's head. Exactly one live version per line carries it."},"is_released":{"type":"boolean","description":"Whether this version is the current release on at least one channel.\n\nStraight from the artifact row, so every surface carries it at no extra read. It answers\n\"is this live\", not \"where\" — a version can be current on `latest` and `beta` at once, and\n`released_channels` is what names them."},"is_system":{"type":"boolean","description":"Whether the deployment wrote this rather than a user. Set at create from the kind's\ndeclaration and immutable after."},"kind":{"type":"string","description":"The registered kind, and the discriminator for what `metadata` contains."},"managed_by":{"type":["string","null"],"description":"The handle of the artifact managing this line, which therefore refuses edits; absent for\nan ordinary artifact."},"metadata":{"type":["object","null"],"description":"The kind's own properties. Absent on list and search rows unless asked for; a column holding\nNULL is omitted rather than serialized as `null`."},"name":{"type":"string","description":"The stable machine handle (AIP-122): identifier-shaped, unique per `(workspace, kind)` among\nlive artifacts."},"oidc_client_id":{"type":["string","null"],"description":"The OIDC client id an agent authenticates as. Read and list responses derive it from the\nactive `service_principals` row after the artifact read is authorized. Credential material\nis never included; the create response separately carries its reveal-once `identity`."},"owner_id":{"type":["string","null"],"description":"The canonical owner's user id, bare and not handle-prefixed.\n\nDefaulted to the creating principal, so this is normally set. Absent for a machine or seed\nprincipal, which has no directory row to own anything, and for a row created before that\ndefault landed."},"permissions":{"oneOf":[{"$ref":"#/components/schemas/gateway.CapabilityMatrix","description":"Embedded only when `include=permissions` asked for it."},{"type":"null"}],"description":"Value of the `permissions` field."},"project_id":{"type":["string","null"],"description":"The project this artifact is grouped under, when it has one. Provenance, not a second home."},"relationships":{"oneOf":[{"$ref":"#/components/schemas/RelationshipsView","description":"Embedded only when `include=relationships` asked for it."},{"type":"null"}],"description":"Value of the `relationships` field."},"released_channels":{"type":"array","items":{"type":"string"},"description":"The channels on which **this version** is the current release. Absent when it is on none.\n\nAbout this version, deliberately, not about the line: the row is a version, and reporting\nthe line's channels here would say \"released on latest\" on a head that is not the released\none — which under a `manual` policy is the normal case. For the line's view use\n`GET /artifacts/{kind}/{id}/channels`.\n\nFilled only by the surfaces that opt into the fan-out ([`with_released_channels`]); it is\none extra query per page, not per row, and a surface that does not need it does not pay."},"repo_id":{"type":["string","null"],"description":"The source repository it was onboarded from, when it was."},"source_created_at":{"type":["string","null"],"description":"Value of the `source_created_at` field."},"source_created_by":{"type":["string","null"],"description":"Value of the `source_created_by` field."},"source_digest":{"type":["string","null"],"description":"Value of the `source_digest` field."},"source_id":{"type":["string","null"],"description":"The artifact's identifier in its source system."},"source_last_modified_at":{"type":["string","null"],"description":"Value of the `source_last_modified_at` field."},"source_last_modified_by":{"type":["string","null"],"description":"Value of the `source_last_modified_by` field."},"source_metadata":{"type":["object","null"],"description":"Value of the `source_metadata` field."},"source_synced_at":{"type":["string","null"],"description":"Value of the `source_synced_at` field."},"source_type":{"type":"string","description":"`git`, `atlan`, `local`, or `external`."},"source_uri":{"type":["string","null"],"description":"Value of the `source_uri` field."},"source_version":{"type":["string","null"],"description":"Value of the `source_version` field."},"updated_at":{"type":"string","description":"RFC 3339, millisecond precision."},"updated_by":{"type":"string","description":"The principal who last changed it."},"version_id":{"type":"string","description":"This version's identity: a 26-character handle body, unique per account.\n\nWhat a release names, what `blake3:` addressing resolves to, and the stable id for a\nversion across the line's history — where `version_ordinal` is only its position. Always\npresent: the column is `NOT NULL` (`m000069_artifact_version_id_not_null`)."},"version_label":{"type":["string","null"],"description":"The free-form label the write set, verbatim. Absent when none was sent.\n\n**Not the name this version shipped under** — that is the release's own `version_label`,\non `GET …/releases`. The two are different facts sharing a field name, because this one\npredates the release plane and keeps its meaning."},"version_ordinal":{"type":"integer","format":"int64","description":"This version's position in its line: the **write index**, 1-based and dense over versions\nwritten.\n\nNot the published number. `ReleaseDto::version_ordinal` counts versions *shipped*, and the\ntwo are the same field name for two different counts — they agree under the default `auto`\nrelease policy, where every version ships, and diverge under `manual`."},"workspace_id":{"type":"string","description":"The owning workspace, and the artifact's authorization object. Immutable after create."}}},"AttachedDomainDto":{"type":"object","description":"An attached email domain, with the link that completes its verification.","required":["id","org_id","domain","kind","state","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time","description":"When the domain was attached."},"domain":{"type":"string","description":"The domain name."},"expires_at":{"type":"string","format":"date-time","description":"When `portal_url` stops working. Absent whenever `portal_url` is."},"failure_reason":{"type":"string","description":"Why verification failed. Present only when `state` is `failed`."},"id":{"type":"string","description":"The domain record's id."},"kind":{"$ref":"#/components/schemas/DomainKind","description":"What the domain entry is for."},"org_id":{"type":"string","description":"The organisation the domain is attached to."},"portal_url":{"type":"string","description":"The admin-portal link that completes verification. Absent once the domain is verified,\nand for `invite_allow` entries, which are never verified."},"state":{"type":"string","description":"The verification state: `unverified`, `pending`, `verified`, or `failed`."},"updated_at":{"type":"string","format":"date-time","description":"When the domain record last changed."},"verified_at":{"type":"string","format":"date-time","description":"When the domain was verified, once it is."},"verified_via":{"$ref":"#/components/schemas/DomainVerifiedVia","description":"How a verified domain was proven, once it is."}}},"AuditActorType":{"type":"string","description":"The kind of principal behind an audit event.","enum":["user","service","platform","system"]},"AuditEventDto":{"type":"object","description":"One event in the control plane's account audit log.","required":["id","occurred_at","event_type","org_id","actor_type","target_type","target_id","outcome","schema_version"],"properties":{"actor_id":{"type":"string","description":"The acting principal's id, when there was one."},"actor_type":{"$ref":"#/components/schemas/AuditActorType","description":"What kind of principal acted."},"changes":{"description":"The changes the action made, as the event recorded them (any JSON value), when it did."},"context":{"description":"Event-specific context (any JSON value), when the event recorded any."},"event_type":{"type":"string","description":"What happened, as a dotted event name."},"id":{"type":"string","description":"The event id."},"occurred_at":{"type":"string","format":"date-time","description":"When the event happened."},"org_id":{"type":"string","description":"The organisation the event belongs to."},"outcome":{"type":"integer","format":"int32","description":"Whether the action succeeded: `1` for success, `2` for a rejected attempt."},"reason":{"type":"string","description":"Why a rejected attempt failed, from a closed set."},"request_id":{"type":"string","description":"The request that made the action, when known."},"schema_version":{"type":"string","description":"The version of this event's schema."},"session_id":{"type":"string","description":"The session the action was made in, when known."},"source_ip":{"type":"string","description":"The client address the action came from, when known."},"target_id":{"type":"string","description":"The id of the resource acted on."},"target_type":{"type":"string","description":"The kind of resource acted on."},"trace_id":{"type":"string","description":"The trace of the request that made the action, when known."}}},"AuditEventsPage":{"type":"object","description":"A page of the control plane's account audit events.","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventDto"},"description":"The events on this page."},"page":{"$ref":"#/components/schemas/ControlPlanePage","description":"The cursor position of this page."}}},"AuthMethod":{"type":"string","description":"A sign-in method an organisation can allow.","enum":["magic_otp","google","enterprise_sso"]},"AvatarDto":{"type":"object","description":"The one response body an avatar write returns: where to read the picture back.","required":["avatar_url"],"properties":{"avatar_url":{"type":"string","description":"The read route's path with the image's content digest as `?v=`, so the address changes\nexactly when the picture does. Fetch it with the caller's bearer; it is not an `<img src>`."}}},"ControlPlanePage":{"type":"object","description":"The cursor position of a page the control plane served.","required":["limit","has_more"],"properties":{"has_more":{"type":"boolean","description":"Whether a further page follows this one."},"limit":{"type":"integer","format":"int64","description":"The page size the request asked for."},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page; `null` on the last page."},"prev_cursor":{"type":["string","null"],"description":"Pass as `cursor` to read the previous page; `null` on the first page."}}},"CostView":{"type":"object","description":"Per-span cost. Mirrors `otel::CostView`.","required":["input_cost_usd","output_cost_usd","total_cost_usd"],"properties":{"input_cost_usd":{"type":"number","format":"double","description":"Input cost in US dollars."},"output_cost_usd":{"type":"number","format":"double","description":"Output cost in US dollars."},"source":{"type":["string","null"],"description":"Origin of this data."},"total_cost_usd":{"type":"number","format":"double","description":"Total cost in US dollars."}}},"CreateInvitationsRequest":{"type":"object","description":"The create/validate request body.","required":["invitees"],"properties":{"invitees":{"type":"array","items":{"$ref":"#/components/schemas/InviteeRequest"},"description":"1..=50 invitees; empty or over 50 is a `422`."}}},"CreateOrganisationDto":{"type":"object","description":"What a `POST /organisations` creates.","required":["name"],"properties":{"name":{"type":"string","description":"The organisation's display name. Trimmed; 1 to 80 characters."},"slug":{"type":["string","null"],"description":"The organisation's handle and the first segment of its dashboard URL: lowercase letters,\ndigits and single hyphens, at most 120 characters, and not a reserved name such as `auth`\nor `settings`. Omit it to derive a unique one from `name`."}},"additionalProperties":false},"CreateRepoBody":{"type":"object","description":"`POST /repos` body.","required":["workspace_id","source_type","source_uri"],"properties":{"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":["string","null"],"description":"Human-readable name."},"name":{"type":["string","null"],"description":"The stable machine handle in `owner/repo` form. Omitted ⇒ derived from the\nnormalised `source_uri`. **Never minted from `display_name`**: prose is refused,\nnot re-slugged."},"project_id":{"type":["string","null"],"description":"Handle of the project this repo belongs to. Validated to sit inside\n`workspace_id` when supplied — the two are a pair, not alternatives."},"source_metadata":{"type":["object","null"],"description":"Opaque provenance the client observed about the remote — `default_branch`, and\n**`contributors[]`**, which is the only input to the detected-contributor writer.\n\nThe gateway makes no outbound call to obtain any of this: a client reads its own git\nhistory and posts what it saw. That is the whole reason the column is an opaque bag\nrather than typed fields — the registry does not interpret it beyond the one key it\nreads.\n\n`contributors[]` accepts a bare email string or an object carrying an `email`. A\nmalformed entry is **dropped, not refused**: a bad provenance entry must not fail a\nrepo registration."},"source_type":{"type":"string","description":"`git` | `atlan` | `local`. Fixed at create."},"source_uri":{"type":"string","description":"The repo remote. Normalised before storage; fixed at create."},"workspace_id":{"type":"string","description":"Handle of the workspace to create the repo in."}}},"CreateServiceAccountBody":{"type":"object","description":"`POST /service-accounts` body. Every field is optional; an unknown one is `400`.","properties":{"credential_ttl_seconds":{"type":["integer","null"],"format":"int64","description":"The `api_key`'s lifetime in seconds, 3600 (1 hour) to 31536000 (365 days). Defaults to\n7776000 (90 days). `400` when `credentials` mints no `api_key`: a client secret carries no\nexpiry.\n\n`expires_in_seconds` is accepted as an alias, because it is the Control Plane's name for the\nsame value and the console shipped it. `credential_ttl_seconds` is canonical; sending both is\n`400`.","minimum":0},"credentials":{"type":["array","null"],"items":{"type":"string"},"description":"Which credentials to mint on the new client: `secret`, `api_key`, or both. Defaults to\n`[\"api_key\"]`; if sent, at least one and at most one of each. Each is returned once in the\nresponse and stored nowhere."},"display_name":{"type":["string","null"],"description":"A human label: trimmed, 1 to 128 characters, no control characters. Optional."},"principal_type":{"type":["string","null"],"description":"`service_account`, the default and the only value accepted. `agent` (provisioned with its\nagent artifact) and the platform flavours (`action`, `registry`) are refused with `400`."},"redirect_uris":{"type":["array","null"],"items":{"type":"string"},"description":"OAuth redirect URIs, for a service account whose own runner drives the authorization-code\nflow: at most 10; absolute `https`, or `http` on `localhost`/`127.0.0.1`/`[::1]` only; no\nfragment, wildcard or userinfo; trimmed and de-duplicated. Non-empty earns the client\n`authorization_code` + `refresh_token` and `openid`/`profile`, defaults `credentials` to\n`[\"secret\", \"api_key\"]`, and requires `credentials` to include `secret` when sent. Absent,\n`null` or `[]` is a machine-only client."},"scopes":{"type":["array","null"],"items":{"type":"string"},"description":"The client's scopes, a ceiling over what its seats allow: a non-empty subset of\n`contextplane:read` (read), `contextplane:write` (also create and edit),\n`contextplane:manage` (also delete, and govern workspaces and their members) and\n`oauth-clients:manage` (provision and administer machine identities). Defaults to the three\n`contextplane:*` levels. A scope never grants what the seats do not. `oauth-clients:manage`\nwith `redirect_uris` is `400`."}},"additionalProperties":false},"CreateWorkspaceBody":{"type":"object","description":"`POST /workspaces` body.","required":["name"],"properties":{"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":["string","null"],"description":"Optional; defaults to `name`."},"name":{"type":"string","description":"The kebab-case machine handle, at most 40 characters. Required — it is the\nmarketplace plugin slug, so the caller chooses its initial value rather than\nreceiving one minted from prose. A later PATCH may rename it."},"parent_id":{"type":["string","null"],"description":"Omitted nests at the account's `org_default` root."},"visibility":{"type":["string","null"],"description":"`public` or `private`. Omitted inherits the parent's visibility — a child of\na public parent defaults public, a child of a private parent defaults\nprivate. An explicit value more open than the parent is a `422`: a child is\nnever more open than its parent."}}},"CredentialSummaryDto":{"type":"object","description":"One credential as a directory read sees it. **No secret and no `secret_ref`** — a read that could\nsurface either would turn a list into a credential oracle.","required":["kind","is_last_use_known"],"properties":{"expires_at":{"type":["string","null"],"description":"RFC 3339, when the credential is time-bounded (an `api_key`; a `client_secret` is not)."},"is_last_use_known":{"type":"boolean","description":"Whether the identity provider's usage record answers for this credential. `true` with no\n`last_used_at` means unused since the current secret was issued or last rotated. `false`\nmeans unknown — the provider could not be read in time, the caller carries no forwardable\ncredential, the provider does not hold this credential, or its secret predates the\nprovider's usage recording — and is always the value on write responses, which do not read\nthe provider. **Do not read `false` as disuse.**"},"kind":{"type":"string","description":"`secret` | `api_key`."},"last_used_at":{"type":["string","null"],"description":"RFC 3339, when the credential last authenticated, as the identity provider recorded it at\nfive-minute granularity — through the gateway or presented to the provider directly. A\nrotation resets it. Absent when the current secret has not been used since it was issued\nor last rotated, or when `is_last_use_known` is `false`."}}},"CursorPage":{"type":"object","description":"Keyset page metadata for a facade list response (cursor, not offset).","required":["limit"],"properties":{"limit":{"type":"integer","format":"int32","minimum":0,"description":"Maximum number of items to return."},"next_cursor":{"type":["string","null"],"description":"Opaque pagination cursor."}}},"CutReleaseBody":{"type":"object","description":"The body of `POST …/releases`.","properties":{"channel":{"type":["string","null"],"description":"The channel. Absent takes the account's default channel."},"notes":{"type":["string","null"],"description":"Value of the `notes` field."},"version_id":{"type":["string","null"],"description":"The version to ship: a `ver_…` handle, or absent for the head."},"version_label":{"type":["string","null"],"description":"The semver to publish under. Absent auto-bumps the line's minor at promotion."},"visibility":{"type":["string","null"],"description":"`private` (default) or `public`."}},"additionalProperties":false},"DimensionSpec":{"type":"object","description":"One `group_by` dimension.","required":["field"],"properties":{"bucket":{"type":["string","null"],"description":"`minute` | `hour` | `day` | `week` | `month`, and only on a timestamp field."},"field":{"type":"string","description":"A declared, filterable L1 field. Grouping reuses the `filter` allowlist rather than a\nseparate one: a field withheld from filtering is withheld because comparing or grouping it is\nunsound or unindexed, and both objections apply at least as hard to a `GROUP BY`."}},"additionalProperties":false},"DomainDto":{"type":"object","description":"One email domain attached to the organisation.","required":["id","org_id","domain","kind","state","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time","description":"When the domain was attached."},"domain":{"type":"string","description":"The domain name."},"failure_reason":{"type":"string","description":"Why verification failed. Present only when `state` is `failed`."},"id":{"type":"string","description":"The domain record's id."},"kind":{"$ref":"#/components/schemas/DomainKind","description":"What the domain entry is for."},"org_id":{"type":"string","description":"The organisation the domain is attached to."},"state":{"type":"string","description":"The verification state: `unverified`, `pending`, `verified`, or `failed`."},"updated_at":{"type":"string","format":"date-time","description":"When the domain record last changed."},"verified_at":{"type":"string","format":"date-time","description":"When the domain was verified, once it is."},"verified_via":{"$ref":"#/components/schemas/DomainVerifiedVia","description":"How a verified domain was proven, once it is."}}},"DomainKind":{"type":"string","description":"What an attached email domain is for.","enum":["claim","invite_allow"]},"DomainVerifiedVia":{"type":"string","description":"How a verified domain was proven.","enum":["dns","signup"]},"DomainsPage":{"type":"object","description":"A page of the organisation's email domains.","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DomainDto"},"description":"The domains on this page."},"page":{"$ref":"#/components/schemas/ControlPlanePage","description":"The cursor position of this page."}}},"EdgeTarget":{"type":"object","description":"One end of an edge.\n\n`{id, kind}` and whether this caller can open it. An `EdgeTarget` reaching a caller names an\nartifact with a live, non-archived head in this account; one that does not resolve is dropped\nupstream in the SQL rather than rendered thin. It may be in a workspace the caller cannot read\n(`artifacts-2026-10-12-relationships-may-cross-workspaces`), and `is_readable` says so before a\nclick does.","required":["id","kind","is_readable"],"properties":{"id":{"type":"string","description":"The artifact handle (`<kind>_…`), so a client can follow the edge without rebuilding it."},"is_readable":{"type":"boolean","description":"Whether this caller can read the artifact. `false` for one in a workspace the caller cannot\nread: the edge is shown, and following it answers `404`."},"kind":{"type":"string","description":"The target's kind, which is also the handle's prefix. Present so a caller can branch on it\nwithout parsing."}}},"FilterClause":{"type":"object","description":"One filter clause: the JSON form of `filter[field][op]=value`.","required":["field"],"properties":{"field":{"type":"string","description":"A declared L1 field. A kind's detail column is refused: this surface never joins a kind's\nown storage, so the column would have to be resolved per row of an unknown page."},"op":{"type":["string","null"],"description":"`eq` (the default) | `ne` | `gt` | `gt_or_null` | `gte` | `lt` | `lte` | `in` | `contains` | `is_null`."},"value":{"type":["string","null"],"description":"The comparison value, for every operator except `in`. For `is_null`, only the literal\nstrings `true` (SQL NULL) and `false` (NOT NULL) are accepted, regardless of field type."},"values":{"type":["array","null"],"items":{"type":"string"},"description":"The values for `in`. At least one; joined with commas on the way into the shared grammar,\nso a comma inside a value is a separator."}},"additionalProperties":false},"GroupDto":{"type":"object","description":"The wire shape for a group.","required":["id","created_at","updated_at"],"properties":{"created_at":{"type":"string","description":"Value of the `created_at` field."},"external_id":{"type":["string","null"],"description":"The identity provider's own id, when there is one. Absent for a locally-minted group."},"id":{"type":"string","description":"Stable identifier of this resource."},"name":{"type":["string","null"],"description":"Stable machine-readable name."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."}}},"InstallAppBody":{"type":"object","description":"`POST /apps/{app}/install` body.","properties":{"config":{"type":["object","null"],"description":"Install-time configuration, handed verbatim to the app's install hooks and stored\nnowhere. **Not a place for credentials** — an app that needs one takes a reference into\nthe secret provider, because this object reaches the hook in cleartext."}}},"IntrospectedActor":{"type":"object","description":"The delegated actor.","required":["subject","org_id","on_behalf_of"],"properties":{"on_behalf_of":{"type":"string","description":"The human the agent is acting for — the token's own `user_id`.\n\nWithout it, a trail could see that delegation happened and not on whose behalf, which is the\nonly interesting part — and, per RFC 8693 §1.1, the only thing separating delegation from\nimpersonation."},"org_id":{"type":"string","description":"Stable identifier of the related org resource."},"subject":{"type":"string","description":"The agent doing the acting — the token's `act.sub`, and the `actor` on every audit and\nusage row this request writes.\n\nDifferent from the outer `subject` — which on a delegated token is the user — so read the\nacting agent here rather than inferring it from the subject."}}},"IntrospectedIdentity":{"type":"object","description":"The verified identity. **Never the raw token.**","required":["subject","org_id","organisation_type","is_platform_user","allow_local_sync","workspace","scopes","permissions","user_id"],"properties":{"act":{"oneOf":[{"$ref":"#/components/schemas/IntrospectedActor","description":"Present only on a delegated token."},{"type":"null"}],"description":"Value of the `act` field."},"allow_local_sync":{"type":"boolean","description":"Whether automatic imports of employee-local skills and traces may sync into this account.\n`false` in a platform organisation, which takes intentional writes only."},"exp":{"type":["integer","null"],"format":"int64","description":"Token expiry, unix seconds. Carried so a caller can bound a cache by the token's own lifetime\nrather than a fixed TTL — a cache hit then cannot outlive the credential."},"is_platform_user":{"type":"boolean","description":"Whether the Control Plane admitted this caller as eligible workforce. Grants no account\nrole and no workspace access."},"org_id":{"type":"string","description":"Stable identifier of the related org resource."},"organisation_type":{"$ref":"#/components/schemas/OrganisationType","description":"The account's operator-managed classification, from the token. A token that predates it\nreads as `customer`."},"permissions":{"type":"array","items":{"type":"string"},"description":"The account capabilities the caller holds (`members_view`, `billing_manage`, …), sorted;\nempty when the caller has no role. **Advisory only** — every route decides the capability\nit needs fresh, never from this list."},"role":{"type":["string","null"],"description":"The caller's account role as the authorization model grants it: `admin` or `member`.\n**Absent** for a human the account roster does not name, and for a machine,\nservice-account or delegated caller — none holds a human role."},"scopes":{"type":"array","items":{"type":"string"},"description":"Value of the `scopes` field."},"subject":{"type":"string","description":"The **authorization** subject — whose authority this request spends, and what every\npermission check and ownership stamp names.\n\nOn a direct call it is the caller. On a delegated one it is the user the agent acts for. It\nis **not** the audit actor — read `act.subject` for who acted."},"user_id":{"type":"string","description":"The authorization subject's durable id, as a bare string. The same value as `subject`."},"workspace":{"type":"string","description":"The token's workspace claim, or empty. A default hint, never a permission."}}},"InvitationDto":{"type":"object","description":"A full invitation, for the single-read, update and revoke responses.","required":["invitation_id","email","workspace_id","role","status","email_status","invited_by","created_at","expires_at"],"properties":{"accepted_at":{"type":["string","null"],"description":"Value of the `accepted_at` field."},"created_at":{"type":"string","description":"Value of the `created_at` field."},"email":{"type":"string","description":"Value of the `email` field."},"email_status":{"type":"string","description":"`sent` | `failed` | `not_sent`."},"expires_at":{"type":"string","description":"Value of the `expires_at` field."},"invitation_id":{"type":"string","description":"Stable identifier of the related invitation resource."},"invited_by":{"type":"string","description":"Value of the `invited_by` field."},"joined_user_id":{"type":["string","null"],"description":"Stable identifier of the related joined user resource."},"role":{"type":"string","description":"Value of the `role` field."},"sent_at":{"type":["string","null"],"description":"Value of the `sent_at` field."},"status":{"type":"string","description":"`pending` | `accepted` | `revoked` | `expired` (the last derived from the TTL)."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"InvitationSendResult":{"type":"object","description":"The resend response: the email fact for one invitation.","required":["invitation_id","email_status"],"properties":{"email_status":{"type":"string","description":"`sent` | `not_sent` | `failed`."},"invitation_id":{"type":"string","description":"Stable identifier of the related invitation resource."}}},"InvitationSummaryDto":{"type":"object","description":"One row of the invitation list.","required":["invitation_id","email","workspace_id","role","status","email_status","invited_by","created_at","expires_at"],"properties":{"created_at":{"type":"string","description":"Value of the `created_at` field."},"email":{"type":"string","description":"Value of the `email` field."},"email_status":{"type":"string","description":"Value of the `email_status` field."},"expires_at":{"type":"string","description":"Value of the `expires_at` field."},"invitation_id":{"type":"string","description":"Stable identifier of the related invitation resource."},"invited_by":{"type":"string","description":"Value of the `invited_by` field."},"role":{"type":"string","description":"Value of the `role` field."},"sent_at":{"type":["string","null"],"description":"Value of the `sent_at` field."},"status":{"type":"string","description":"Current lifecycle state."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"InvitationsPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InvitationSummaryDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Invitations resources."},"InvitationsResponse":{"type":"object","description":"The per-email breakdown create and validate both return.","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/InviteeResult"},"description":"One result per invitee, in request order."}}},"InviteeRequest":{"type":"object","description":"One invitee: an email, an optional target workspace, and a role.","required":["email","role"],"properties":{"email":{"type":"string","description":"The invitee address; normalized server-side to `lower(trim())`."},"role":{"type":"string","description":"The role to grant on the target: `admin`, `builder` or `viewer`. Legacy `member` is\naccepted as an alias for `builder`."},"workspace_id":{"type":["string","null"],"description":"The target workspace handle (`workspace_…`). Omit to target the account's `org_default`."}}},"InviteeResult":{"type":"object","description":"One invitee's outcome. `outcome` is the commit fact and `email_status` the email fact — a client\nbranches on `outcome`, then on `reason`.","required":["email","outcome","email_status"],"properties":{"email":{"type":"string","description":"The normalized address, echoed."},"email_status":{"type":"string","description":"`sent` | `not_sent` | `failed` | `not_applicable`."},"invitation_id":{"type":["string","null"],"description":"The invitation handle when a row exists; `null` for `already_member` and `rejected`."},"outcome":{"type":"string","description":"`invited` | `updated` | `already_invited` | `already_member` | `rejected`."},"reason":{"type":["string","null"],"description":"The rejection code, only when `outcome == \"rejected\"`."},"role":{"type":["string","null"],"description":"The role; `null` when `rejected`, or `already_member` with no seat."},"workspace_id":{"type":["string","null"],"description":"The target workspace handle; `null` when `rejected`, or `already_member` with no seat."}}},"MembershipStatus":{"type":"string","description":"A user's membership status in an organisation.","enum":["active","invited","suspended","deprovisioned","archived"]},"MetricSpec":{"type":"object","description":"One aggregate measure.","required":["op"],"properties":{"alias":{"type":["string","null"],"description":"Overrides the default result key (`<op>` or `<op>_<field>`)."},"field":{"type":["string","null"],"description":"Required by every op except `count`, which counts rows. Supplying one beside `count` is a\n`400`, not an ignore: `COUNT(field)` skips NULLs and is a different number."},"op":{"type":"string","description":"`count` | `count_distinct` | `min` | `max` | `sum` | `avg`."}},"additionalProperties":false},"MintCredentialBody":{"type":"object","description":"`POST /service-accounts/{principal_id}/credentials` body.","required":["kind"],"properties":{"credential_ttl_seconds":{"type":["integer","null"],"format":"int64","description":"The `api_key`'s lifetime in seconds, 3600 (1 hour) to 31536000 (365 days). Defaults to\n7776000 (90 days). `400` with `kind: secret`. `expires_in_seconds` is accepted as an alias,\nas on the create.","minimum":0},"kind":{"type":"string","description":"The credential kind to mint: `secret` or `api_key`. Required, never defaulted. The identity\nmust not already hold one of this kind."}},"additionalProperties":false},"OauthGrantDto":{"type":"object","description":"One delegated-access grant: an agent the caller has allowed to act on their behalf.","required":["id","client_id","actor_sub","status","created_at","expires_at"],"properties":{"actor_sub":{"type":"string","description":"The agent's service account acting on the caller's behalf."},"client_id":{"type":"string","description":"The OAuth client the grant was made to."},"created_at":{"type":"string","format":"date-time","description":"When the grant was made."},"expires_at":{"type":"string","format":"date-time","description":"When the grant expires."},"id":{"type":"string","description":"The grant id."},"revoked_at":{"type":"string","format":"date-time","description":"When the grant was revoked, if it was."},"status":{"$ref":"#/components/schemas/OauthGrantStatus","description":"The grant's lifecycle state."}}},"OauthGrantStatus":{"type":"string","description":"A delegated-access grant's lifecycle state.","enum":["active","revoked","expired"]},"OauthGrantsPage":{"type":"object","description":"The caller's delegated-access grants.","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OauthGrantDto"},"description":"The grants."}}},"OnboardResponse":{"type":"object","description":"The assets the caller owns after onboarding.\n\nEvery field reflects **persisted state**, not just what this call created — which is what makes a\nrepeat onboard useful as a \"what do I have\" read rather than only an idempotent no-op.","required":["is_created","organisation","user","groups","org","user_default","org_seat"],"properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/GroupDto"},"description":"Mirrored from the token's `groups` claim; empty when it carries none."},"is_created":{"type":"boolean","description":"Whether this call minted the caller's personal workspace. `false` is a replay.\n\nKeyed on the *personal* workspace deliberately: a second person joining an existing account\nis a fresh onboard for them, even though the shared root was already there."},"org":{"$ref":"#/components/schemas/registry.WorkspaceView","description":"The account's shared root."},"org_seat":{"type":"string","description":"The caller's role on the shared root: `admin` or `builder`."},"organisation":{"$ref":"#/components/schemas/OrganisationDto"},"user":{"$ref":"#/components/schemas/UserDto"},"user_default":{"$ref":"#/components/schemas/registry.WorkspaceView","description":"The caller's private root."}}},"OrganisationDetailDto":{"type":"object","description":"The single merged organisation read: the control-plane account record joined with the\nregistry-native `avatar_url`.\n\nThe **detail** shape, and deliberately not [`OrganisationDto`]. The list\n(`GET /organisations`) stays on the narrow registry-native row — a page of the caller's own\naccount and nothing it does not own — while the point read folds in what the control plane owns\n(settings) and what the registry owns (the picture). Every control-plane field is\n`skip_serializing_if = \"Option::is_none\"`, so an account the plane has said nothing about reads\nas `{\"id\": ...}` rather than a wall of nulls, and a field the plane adds later arrives without a\nreader change.","required":["id"],"properties":{"allowed_auth_methods":{"type":["array","null"],"items":{"type":"string"},"description":"Value of the `allowed_auth_methods` field."},"avatar_url":{"type":["string","null"],"description":"The registry-native pointer to the account's picture, when it has one. Absent (not `null`)\notherwise, and best-effort: a store that cannot answer drops the key rather than failing the\nread."},"created_at":{"type":["string","null"],"description":"Value of the `created_at` field."},"created_by":{"type":["string","null"],"description":"Value of the `created_by` field."},"id":{"type":"string","description":"The account id. Always the path/token org id, never a value from the control-plane body, so a\nmerged record can never name an account other than the one authorized. `id` on the wire for\nthe reason [`OrganisationDto`]'s is."},"join_policy":{"type":["string","null"],"description":"Value of the `join_policy` field."},"name":{"type":["string","null"],"description":"Control-plane fields, each present only when the plane returned it."},"restrict_invites_to_domains":{"type":["boolean","null"],"description":"Value of the `restrict_invites_to_domains` field."},"revoke_credentials_on_offboard":{"type":["boolean","null"],"description":"Value of the `revoke_credentials_on_offboard` field."},"slug":{"type":["string","null"],"description":"Value of the `slug` field."},"status":{"type":["string","null"],"description":"Current lifecycle state."},"updated_at":{"type":["string","null"],"description":"Value of the `updated_at` field."},"version":{"type":["integer","null"],"format":"int64","description":"The account's `If-Match` ETag, read from the control-plane body.","minimum":0},"workos_organization_id":{"type":["string","null"],"description":"Stable identifier of the related workos organization resource."}}},"OrganisationDto":{"type":"object","description":"The wire shape for an account.","required":["id","created_at","updated_at"],"properties":{"created_at":{"type":"string","description":"Value of the `created_at` field."},"id":{"type":"string","description":"The account id. `id` on the wire for the reason `UserDto`'s is: the column is `org_id`,\nthe resource's own identifier is `id`."},"name":{"type":["string","null"],"description":"Stable machine-readable name."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."}}},"OrganisationRecordDto":{"type":"object","description":"The control plane's account record, as a create or update returns it.\n\nThis is not the merged `GET /organisations/{org_id}` read: it carries no `avatar_url`, so a\nclient that replaces its cached organisation with this body should keep the avatar it had.","required":["id","slug","name","status","organisation_type","allow_local_sync","allowed_auth_methods","join_policy","restrict_invites_to_domains","revoke_credentials_on_offboard","version","created_at","updated_at"],"properties":{"allow_local_sync":{"type":"boolean","description":"Whether automatic employee-local skills and traces may sync to this organisation."},"allowed_auth_methods":{"type":"array","items":{"$ref":"#/components/schemas/AuthMethod"},"description":"The sign-in methods the organisation allows."},"created_at":{"type":"string","format":"date-time","description":"When the organisation was created."},"created_by":{"type":"string","description":"The user who created the organisation, when known."},"id":{"type":"string","description":"The organisation id."},"join_policy":{"type":"string","description":"How people join the organisation: `open_auto_join`, `request_to_join`, `invite_only`, or\n`closed`."},"name":{"type":"string","description":"The organisation's display name."},"organisation_type":{"$ref":"#/components/schemas/OrganisationType","description":"The organisation's operator-managed classification."},"restrict_invites_to_domains":{"type":"boolean","description":"Whether invitations must match the organisation's attached email domains."},"revoke_credentials_on_offboard":{"type":"boolean","description":"Whether a member's OAuth clients are disabled when that member is offboarded."},"slug":{"type":"string","description":"The organisation's URL-safe slug."},"status":{"$ref":"#/components/schemas/OrganisationStatus","description":"The organisation's lifecycle status."},"updated_at":{"type":"string","format":"date-time","description":"When the record last changed."},"version":{"type":"integer","format":"int64","description":"The record's optimistic-concurrency version."},"workos_organization_id":{"type":"string","description":"The identity-provider organisation linked to this account, when one is."}}},"OrganisationStatus":{"type":"string","description":"An organisation's lifecycle status.","enum":["active","suspended","pending_deletion","archived"]},"OrganisationType":{"type":"string","description":"An account's operator-managed classification.","enum":["customer","platform"]},"OrganisationsPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrganisationDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Organisations resources."},"OwnUserDto":{"type":"object","description":"The caller's own control-plane profile.\n\n`avatar_url` is the identity provider's picture. The avatar a user uploads with\n`PUT /users/me/avatar` is stored by the gateway and is not reflected here: read it from the\ncaller's row in `GET /users/{user_id}`. The account `role` and its advisory `permissions` are\nserved by `GET /auth/whoami`.","required":["id","email","provisioning","status","org_id","orgs","version"],"properties":{"avatar_url":{"type":"string","description":"The identity provider's picture for the caller, when it supplied one. Not the avatar\nuploaded through `PUT /users/me/avatar`."},"email":{"type":"string","description":"The caller's email address."},"full_name":{"type":"string","description":"The caller's display name, when they have one."},"id":{"type":"string","description":"The caller's control-plane user id."},"onboarding_completed_at":{"type":"string","format":"date-time","description":"When the caller first completed onboarding in this organisation (RFC 3339). Absent if\nthey never have."},"org_id":{"type":"string","description":"The organisation the caller's token is bound to."},"orgs":{"type":"array","items":{"$ref":"#/components/schemas/OwnUserOrganisationDto"},"description":"Every active organisation the caller can switch to."},"provisioning":{"$ref":"#/components/schemas/UserProvisioning","description":"How the caller's account was created."},"status":{"$ref":"#/components/schemas/MembershipStatus","description":"The caller's membership status in the token's organisation."},"version":{"type":"integer","format":"int64","description":"The profile's optimistic-concurrency version."}}},"OwnUserOrganisationDto":{"type":"object","description":"One organisation the caller can switch to.","required":["id","slug","name","organisation_type","allow_local_sync","member_count"],"properties":{"allow_local_sync":{"type":"boolean","description":"Whether desktop automatic skill and trace jobs are permitted in this organisation."},"id":{"type":"string","description":"The organisation id."},"member_count":{"type":"integer","format":"int64","description":"How many members the organisation has."},"name":{"type":"string","description":"The organisation's display name."},"organisation_type":{"$ref":"#/components/schemas/OrganisationType","description":"The organisation's operator-managed classification."},"plan":{"type":"string","description":"The organisation's billing plan key, when it has one."},"slug":{"type":"string","description":"The organisation's URL-safe slug."}}},"PatchRepoBody":{"type":"object","description":"`PATCH /repos/{id}` body.","properties":{"description":{"type":["string","null"],"description":"Absent leaves it unchanged; `null` clears it."},"display_name":{"type":["string","null"],"description":"Human-readable name."},"name":{"type":["string","null"],"description":"Immutable. Present at all ⇒ 422."}}},"PatchWorkspaceBody":{"type":"object","description":"`PATCH /workspaces/{id}` body.","properties":{"description":{"type":["string","null"],"description":"Absent leaves it unchanged; `null` clears it. `Option<Option<_>>` with\n`deserialize_with` is what keeps those two apart — a plain `Option` collapses\nthem, which is the bug `PATCH`-is-the-primary-verb exists to prevent."},"display_name":{"type":["string","null"],"description":"Human-readable name."},"name":{"type":["string","null"],"description":"The machine handle: kebab-case, at most 40 characters. Prose is a `400`, never silently\nre-slugged.\n\nOmit it and a `display_name` edit **derives** it from the new label\n(`naming-2026-08-21-display-name-rename-reslugs-the-handle`). Set it to keep a hand-picked\nhandle across a relabel, or to resolve the `409` a derived handle collided on.\n\nA handle change is a one-way door for clients: `name` is the marketplace plugin slug's\nsource, so renaming orphans every existing install of this workspace's plugin. The two\nprovisioning handles — `org_default` and `user_default` — refuse it outright."},"parent_id":{"type":["string","null"],"description":"Move the workspace under another one, with its whole subtree.\n\nApplied before the label patch and in its own transaction, alongside the rerooting\nof every project in the moved subtree — which has to be the same commit, because\nproject names are unique per tree root.\n\nRefused for a singleton (a tree root does not move), for a destination inside the\nmoved subtree (a cycle), and for a move that would nest the subtree's leaves past\nthe depth cap."}}},"ProblemDetails":{"type":"object","description":"Rendered RFC 7807 payload. Public so tests can decode it; extensions\nshould construct errors through [`ExtensionError`] and let the\n`IntoResponse` impl do the rendering.\n\n`code` is **mandatory** — every non-2xx body carries one, so a client branches\non a stable token instead of matching prose. The published specs narrow it to a\nper-status enum (see `openapi::with_standard_errors`).\n\nNo member is namespaced. `trace_id` was `gateway.trace_id` and the schema was\n`gateway.ProblemDetails`; both dropped the prefix, since an error body should\nnot name the component that produced it.\n\n**There is no `type` member, deliberately.** RFC 9457 §3.1 makes an absent `type`\nmean `about:blank`, and §4.2.1 defines that as \"no additional semantics beyond\nthat of the HTTP status code\" — which is exactly right here, because the\nsemantics live in the mandatory `code`. The earlier `about:blank#<code>` form\nwas derived from `code` and nothing else, so it duplicated a mandatory member on\nevery error body while naming a fragment of a blank page that identifies nothing;\nit also displaced the one URI a consumer library special-cases. Omitting it is\nwhat makes `title` correct too: §4.2.1 says the title SHOULD be the status's\nrecommended phrase, which is what [`ProblemDetails::body`] sets it to.","required":["title","status","detail","code"],"properties":{"code":{"type":"string","description":"Value of the `code` field."},"detail":{"type":"string","description":"Value of the `detail` field."},"status":{"type":"integer","format":"int32","minimum":0,"description":"Current lifecycle state."},"title":{"type":"string","description":"Value of the `title` field."},"trace_id":{"type":["string","null"],"description":"Stable identifier of the related trace resource."}}},"ProjectSummary":{"type":"object","description":"A project as an export line. The full shape is `GET /projects/{project_id}`.","required":["id","name","display_name","workspace_id","project_status","created_at","updated_at"],"properties":{"created_at":{"type":"string","description":"Value of the `created_at` field."},"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":"string","description":"Human-readable name."},"id":{"type":"string","description":"Stable identifier of this resource."},"name":{"type":"string","description":"Stable machine-readable name."},"project_status":{"type":"string","description":"Value of the `project_status` field."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"ReconcileAcceptedDto":{"type":"object","description":"What a dispatched reconcile handed over.","required":["app","live_count"],"properties":{"app":{"type":"string","description":"Value of the `app` field."},"live_count":{"type":"integer","description":"How many live artifacts of this app's kinds were sent. `0` is legitimate and usually means\nthe account owns nothing of them — which, on a reconcile an operator triggered\ndeliberately, is worth seeing rather than inferring from silence.","minimum":0}}},"RelationshipDto":{"type":"object","description":"One edge. Exactly one of `to` and `from` is present: `to` on an outgoing edge, `from` on an\nincoming one, so a caller reading a neighbourhood never has to work out which end it is looking\nat.","required":["rel_type","direction","provenance","relationship_status"],"properties":{"attributes":{"type":["object","null"],"description":"Whatever the writer recorded about *why*. Nothing reads it structurally."},"confidence":{"type":["number","null"],"format":"double","description":"How sure the writer is, on the same absent-versus-zero footing as `weight`."},"direction":{"type":"string","description":"`directed` or `undirected`. Symmetric edges (`alternative`, `duplicate_of`) are stored once\nand mean the same thing read backwards."},"from":{"oneOf":[{"$ref":"#/components/schemas/EdgeTarget"},{"type":"null"}],"description":"Value of the `from` field."},"label":{"type":["string","null"],"description":"Free prose about this particular edge; `null` when the writer set none."},"provenance":{"type":"string","description":"Who asserted it: `manual`, `agent_inferred`, `trace_derived`, `system_derived` or `imported`.\nThe field to read before trusting a `confidence`."},"rel_type":{"type":"string","description":"The declared edge type (`depends_on`, `duplicate_of`, …)."},"relationship_status":{"type":"string","description":"`active`, `deprecated` or `archived`. An archived edge stays readable."},"role":{"type":["string","null"],"description":"What the target plays in this relation, when the edge type has roles; `null` otherwise."},"to":{"oneOf":[{"$ref":"#/components/schemas/EdgeTarget"},{"type":"null"}],"description":"Value of the `to` field."},"weight":{"type":["number","null"],"format":"double","description":"Edge strength, `null` when the writer asserted none — a `0.0` would be a claim rather than an\nabsence."}}},"RelationshipsView":{"type":"object","description":"An artifact's edges in both directions, with the total.","required":["outgoing","incoming","count"],"properties":{"count":{"type":"integer","description":"`outgoing` + `incoming`, so a caller rendering a badge does not have to add them up. Bounded\nby the per-direction cap, so a very dense artifact reports the cap rather than the truth —\nand bounded by the endpoint filter, so an edge whose other end is archived or deleted is\ncounted by neither array nor this total. An end the caller cannot read is counted, and\nmarked `is_readable: false`. See\n`registry_model::ops::artifact::far_end_resolves`: the alternative was a node that answered\n\"No such artifact in this account\" when a lineage graph drew it.","minimum":0},"incoming":{"type":"array","items":{"$ref":"#/components/schemas/RelationshipDto"},"description":"Edges *to* this artifact. Each carries `from`."},"outgoing":{"type":"array","items":{"$ref":"#/components/schemas/RelationshipDto"},"description":"Edges *from* this artifact. Each carries `to`."}}},"ReleaseDto":{"type":"object","description":"One release, on the wire.","required":["release_id","artifact_id","kind","workspace_id","version_id","channel","visibility","release_status","is_current","created_by","created_at","updated_by","updated_at"],"properties":{"artifact_id":{"type":"string","description":"Stable identifier of the related artifact resource."},"channel":{"type":"string","description":"Value of the `channel` field."},"content_hash":{"type":["string","null"],"description":"Value of the `content_hash` field."},"created_at":{"type":"string","description":"When the row was minted, RFC 3339 like every other timestamp on this API. For an `auto`\npolicy's row this is when it was **queued**; `released_at` is when it shipped."},"created_by":{"type":"string","description":"Who minted the release row. For an explicit cut, who released it; for an `auto` policy's\nrow, whoever made the write that queued it."},"is_current":{"type":"boolean","description":"Whether current."},"kind":{"type":"string","description":"Domain discriminator for this resource."},"notes":{"type":["string","null"],"description":"Value of the `notes` field."},"reason":{"type":["string","null"],"description":"Value of the `reason` field."},"release_id":{"type":"string","description":"`rel_…`."},"release_status":{"type":"string","description":"Value of the `release_status` field."},"released_at":{"type":["string","null"],"description":"When this version first shipped on this channel, RFC 3339. Not moved by a later\nsupersession or by being promoted back after a withdrawal. Absent while pending, on a\nrelease discarded before it shipped, and — until a follow-up backfill — on a release\npromoted while this field was being rolled out."},"released_by":{"type":["string","null"],"description":"Who first shipped this version on this channel. Absent while pending, and on a release\ndiscarded before it ever shipped."},"updated_at":{"type":"string","description":"When that last transition happened, RFC 3339. `release_status` says which it was."},"updated_by":{"type":"string","description":"Who made the last transition — promotion, supersession, withdrawal or a promote-back."},"version_id":{"type":"string","description":"`ver_…` — the version shipped."},"version_label":{"type":["string","null"],"description":"The semver. Absent while pending, for `version_ordinal`'s reason."},"version_ordinal":{"type":["integer","null"],"format":"int64","description":"The published version number. Absent while the release is pending: an unshipped version\nhas no number, which is the whole reason this field is on a release and not an artifact."},"visibility":{"type":"string","description":"Value of the `visibility` field."},"withdrawn_at":{"type":["string","null"],"description":"When it was withdrawn, RFC 3339. Present only when `release_status` is `withdrawn`."},"withdrawn_by":{"type":["string","null"],"description":"Who withdrew it. Present only when `release_status` is `withdrawn`."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"ReleasePage":{"type":"object","required":["items","page","is_truncated"],"properties":{"is_truncated":{"type":"boolean","description":"`true` when the caller's readable workspaces were cut at the lookup cap, so\n`items` and `page.total` are a floor rather than everything the caller may read."},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Release resources."},"ReleasePolicyDto":{"type":"object","description":"A workspace's resolved release policy, with the level that answered.","required":["workspace_id","channel","mode","require_checks","default_visibility","allow_version_override","allow_public","resolved_from","sources"],"properties":{"allow_public":{"type":"boolean","description":"Whether this channel may carry a public release at all — the org's ceiling. A workspace\nchooses within it and cannot raise it."},"allow_version_override":{"type":"boolean","description":"Whether version override."},"channel":{"type":"string","description":"Value of the `channel` field."},"default_visibility":{"type":"string","description":"`private` or `public`."},"mode":{"type":"string","description":"`auto` or `manual`."},"require_checks":{"type":"boolean","description":"Value of the `require_checks` field."},"resolved_from":{"type":"string","description":"`workspace`, `channel` or `default` — which level answered. Advisory; it exists so an\noperator can see why a release behaved as it did.\n\n`workspace` means the workspace **has a policy row** for this channel, not that it set\nanything: a row whose every facet is `null` still reports `workspace`. Whether any facet is\nset here, and which, is `sources`."},"sources":{"$ref":"#/components/schemas/ReleasePolicySourcesDto","description":"Which level decided each facet."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"ReleasePolicySourcesDto":{"type":"object","description":"Which level decided each facet of a resolved release policy: `workspace`, `channel` or\n`default`.\n\nOnly `require_checks` and `allow_public` have a channel level — the channel's definition\ncarries nothing else — so `null` on the other three settable facets falls back to the\nfail-safe default, never to the channel. `allow_public` is never `workspace`: a workspace\ncannot set it.","required":["mode","require_checks","default_visibility","allow_version_override","allow_public"],"properties":{"allow_public":{"type":"string","description":"`channel` or `default`."},"allow_version_override":{"type":"string","description":"`workspace` or `default`."},"default_visibility":{"type":"string","description":"`workspace` or `default`, except that a workspace's `public` clamped to `private` by the\nchannel's `allow_public` ceiling reports the ceiling's level, `channel` or `default`."},"mode":{"type":"string","description":"`workspace` or `default`."},"require_checks":{"type":"string","description":"`workspace`, `channel` or `default`."}}},"RepoArchiveAck":{"type":"object","description":"`POST /repos/{repo_id}/archive` reply.","required":["id","status","changed"],"properties":{"changed":{"type":"boolean","description":"Whether **this** call archived it. `false` on a re-archive — the row was already archived, and\nno second audit event was recorded for a state change that did not happen."},"id":{"type":"string","description":"Stable identifier of this resource."},"status":{"type":"string","description":"Always `archived`, echoed so a client need not assume it."}}},"RepoBulkCreateRequest":{"type":"object","description":"`POST /repos/bulk` body.","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateRepoBody"},"description":"Up to 100 items, each exactly a `POST /repos` body — including its own\n`workspace_id`, so one batch can span workspaces."}}},"RepoDto":{"type":"object","description":"The wire shape.","required":["id","workspace_id","name","display_name","source_type","repo_status","created_by","created_at","updated_by","updated_at"],"properties":{"created_at":{"type":"string","description":"RFC 3339 strings, matching the shipped contract. Changing them to typed\ntimestamps is the `api-contract` skill's call, not a side effect of a store\nswap."},"created_by":{"type":"string","description":"Value of the `created_by` field."},"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":"string","description":"Human-readable name."},"id":{"type":"string","description":"Stable identifier of this resource."},"name":{"type":"string","description":"Stable machine-readable name."},"project_id":{"type":["string","null"],"description":"Stable identifier of the related project resource."},"repo_status":{"type":"string","description":"The lifecycle state. `repo_status`, not `status` — see `ProjectDto::project_status`;\n`registry_model::repo::Entity` likewise declares `(\"status\", \"repo_status\")` retired, so\nthe response served the one name the request refused."},"source_metadata":{"type":["object","null"],"description":"The provenance bag as stored. Served so the write round-trips: the contributor\nwriter reads one key out of it, and a caller that could not read back what it sent\nhas no way to tell a dropped bag from an accepted one."},"source_type":{"type":"string","description":"Value of the `source_type` field."},"source_uri":{"type":["string","null"],"description":"Value of the `source_uri` field."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."},"updated_by":{"type":"string","description":"Value of the `updated_by` field."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"RepoListDto":{"type":"object","description":"Published representation of RepoListDto.","required":["id","workspace_id","name","display_name","source_type","repo_status","created_by","created_at","updated_by","updated_at"],"properties":{"created_at":{"type":"string","description":"RFC 3339 strings, matching [`RepoDto`]."},"created_by":{"type":"string","description":"Value of the `created_by` field."},"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":"string","description":"Human-readable name."},"id":{"type":"string","description":"Stable identifier of this resource."},"name":{"type":"string","description":"Stable machine-readable name."},"project_id":{"type":["string","null"],"description":"Stable identifier of the related project resource."},"repo_status":{"type":"string","description":"The lifecycle state. `repo_status`, not `status` — see [`RepoDto::repo_status`]."},"source_type":{"type":"string","description":"Value of the `source_type` field."},"source_uri":{"type":["string","null"],"description":"Value of the `source_uri` field."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."},"updated_by":{"type":"string","description":"Value of the `updated_by` field."},"workspace_id":{"type":"string","description":"Stable identifier of the related workspace resource."}}},"RepoSlot":{"type":"object","description":"One index's outcome. Exactly one of the payload and `error` is present.","required":["index","status_code"],"properties":{"error":{"oneOf":[{"$ref":"#/components/schemas/SlotError","description":"The problem document, when it failed."},{"type":"null"}],"description":"Error returned when the operation fails."},"index":{"type":"integer","description":"The item's position in the request, so a client can join a failure back to what\nit sent. Sent even on success, because a caller filtering to the failures still\nneeds the index of each.","minimum":0},"repo":{"oneOf":[{"$ref":"#/components/schemas/RepoDto","description":"The resource, when this item succeeded."},{"type":"null"}],"description":"Value of the `repo` field."},"status_code":{"type":"integer","format":"int32","description":"The item's own success or failure status.","minimum":0}}},"ReposBulkResponse":{"type":"object","description":"The batch response. Always `207`, even when every item succeeded.\n\nUniform on purpose: a client that has to branch on the envelope status before it can\nread the slots will get that branch wrong on the day one item fails.\n\n**No `created`/`failed` counters.** They were a convenience over `items`, and they are\nthe kind of derived field that goes stale: the published contract carries the slots\nalone, and `items.iter().filter(...)` is the same loop wherever it is written.","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RepoSlot"},"description":"Results aligned with the submitted item positions."}}},"ReposPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RepoListDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Repos resources."},"RevealedCredentialDto":{"type":"object","description":"One credential revealed once at provision. `Serialize` only, no `Debug` — it holds a plaintext\nsecret.","required":["kind","secret"],"properties":{"expires_at":{"type":["string","null"],"description":"RFC 3339, when the provider set an expiry."},"kind":{"type":"string","description":"`secret` | `api_key`."},"secret":{"type":"string","description":"The secret. Record it now; it is not retrievable."}}},"RevokedSessionsDto":{"type":"object","description":"The result of revoking every one of the caller's sessions.","required":["user_id","revoked_count"],"properties":{"revoked_count":{"type":"integer","format":"int64","description":"How many active sessions this call revoked; `0` when there were none."},"user_id":{"type":"string","description":"The caller's user id."}}},"RoleDto":{"type":"object","description":"One role in the account catalogue: a per-org identity, not a bare label.","required":["id","name"],"properties":{"id":{"type":"string","description":"The role's stable per-org id."},"name":{"type":"string","description":"The role name: `admin` | `member` today, open for per-org custom."}}},"RoleListDto":{"type":"object","description":"The account's role catalogue.","required":["roles"],"properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleDto"},"description":"Each role as an `{id, name}` object."}}},"RotatedCredentialDto":{"type":"object","description":"A freshly rotated credential. **The only place a secret value crosses this surface.**\n\nReveal-once by construction: nothing stores it, so this response is the sole copy. `Serialize`\nonly — there is no `Deserialize` and no `Debug`, deliberately, because a `Debug` on a struct\nholding a plaintext secret is one `tracing::debug!` away from a credential in a log.","required":["principal_id","kind","secret"],"properties":{"expires_at":{"type":["string","null"],"description":"RFC 3339, when the provider set an expiry."},"kind":{"type":"string","description":"The credential kind the provider issued."},"principal_id":{"type":"string","description":"The identity this credential belongs to."},"secret":{"type":"string","description":"The secret. Record it now; it is not retrievable."}}},"RunningDto":{"type":"object","description":"The live build serving an app.","required":["version"],"properties":{"commit":{"type":["string","null"],"description":"The commit the serving binary was built from; `dev` for a local build. Absent when the\nserving process predates reporting one."},"tag":{"type":["string","null"],"description":"The release tag (`vX.Y.Z`) the deployment ships as, when one was cut."},"version":{"type":"string","description":"The app's own version (semver), bumped with every change to the extension."}}},"SearchPage":{"type":"object","description":"Paginated collection of Search resources.","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactView"},"description":"The ranked results, best first. An artifact L1 view, plus `score` on the fused strategies\nand the graph labels on `group`."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under.\n\n`page.total` is present on `fts` and **absent** on `vector`/`hybrid`/`group`: those rank a\nbounded candidate pool, and the pool's size is not the number of matching artifacts."}}},"SearchRequest":{"type":"object","description":"The `POST /search` body.\n\n`deny_unknown_fields`, and it is load-bearing rather than hygiene: `sort` is the name every other\nlist surface uses, so a caller writing `sort` instead of `sorts` should hear about it rather than\nreceive an arbitrarily-ordered page that looks ranked.","properties":{"count":{"type":["boolean","null"],"description":"Return the exact `total`. Defaults to **true**, which is the contract\n([`authorization.md`] D3): a search answers with an exact post-filter count.\n\n`false` declines it, and what it declines is real work rather than a field. The count is a\n`COUNT(*) OVER ()` sharing the query's own `WHERE`, so producing it forces the whole matching\nset to be materialized — a query matching 2,000 artifacts pays for 2,000 to return 20. A\ncaller paging by \"was this page full\", which is what a walker actually needs, can decline it.\n\nOpt-**out**, never opt-in: the default is the promise, and a client that has never heard of\nthis field sees exactly what it saw before.\n\nIt does not remove the ranking, only the count. The `ORDER BY` still sorts the whole matching\nset, so this is a meaningful p95/p99 improvement on a broad query and not a change of\nasymptotics — keyset paging is the fix for that (LIMITATIONS L33).\n\n[`authorization.md`]: ../../../../docs/architecture/02-extension-platform/authorization.md"},"embedding_kind":{"type":["string","null"],"description":"Restrict the vector half to one declared embedding. Omitted ⇒ rank across all of them."},"fields":{"type":["array","null"],"items":{"type":"string"},"description":"Return only these keys of each result. `id` and `kind` are always present, and on `group` so\nare the graph labels — projecting away the thing that distinguishes an anchor from a\ndependent would leave the response unreadable."},"filters":{"type":"array","items":{"$ref":"#/components/schemas/FilterClause"},"description":"Per-field filters over L1 columns, ANDed together."},"include":{"type":"array","items":{"type":"string"},"description":"Opt-in embeds. `permissions` attaches the caller's advisory `can_*` capability matrix per\nitem, resolved from the page's own read receipt; unknown tokens are ignored."},"is_all_versions_included":{"type":["boolean","null"],"description":"Include every live version rather than only the heads. Defaults to false."},"is_archived_included":{"type":["boolean","null"],"description":"Include archived artifacts. Defaults to false — an archived artifact stays readable by id\nbut is hidden from discovery.\n\nLeft false while also filtering `artifact_status` to `archived` is a contradiction, and the\nanswer is an empty page: the two are conjoined, not resolved in the caller's favour."},"is_system_included":{"type":["boolean","null"],"description":"Include artifacts the deployment wrote. Defaults to false."},"kind":{"type":["string","null"],"description":"Narrow to one registered kind."},"limit":{"type":["integer","null"],"format":"int64","description":"Max results. Defaults to 50; a larger value than 500 is clamped to 500, and `0` is refused.","minimum":1},"offset":{"type":["integer","null"],"format":"int64","description":"Results to skip. Defaults to 0, rejected above 10000.\n\nOn `vector`, `hybrid` and `group`, `offset + limit` may not exceed 1000\n(`400 search_window_exceeded`): those rank a fixed 1000-deep candidate pool, so a page past it\nhas nothing to serve. A page shorter than `limit` is the end.","minimum":0},"project_id":{"type":["string","null"],"description":"Narrow to one project: the artifacts it owns (`project_id`) **and** the ones linked into it.\nOrthogonal to `workspace_id` — a project is a grouping *inside* a workspace, so both may be\nset and both narrow.\n\nA project linking more than 1000 artifacts is refused (`422 project_link_limit_exceeded`);\nnarrow by `kind` or `workspace_id` instead. A `filters` clause on `project_id` still matches\nthe artifact's own column only."},"query":{"type":["string","null"],"description":"The free-text query, matched over `name`, `display_name`, `description` and the extension's\n`search_text`. Required by `fts` and `hybrid`; at most 8000 characters (`400 query_too_long`).\n\nBare words match **any** of them. `\"a quoted phrase\"` is required, in order. `-word` or\n`-\"a phrase\"` excludes. The last bare word, if it has three or more characters, also matches\nas a prefix, so a partly typed word finds its completions. A query with only exclusions is a\n`400`."},"query_vector":{"type":["array","null"],"items":{"type":"number","format":"float"},"description":"A probe the caller embedded itself, 1024-dim with finite components.\n\n**Optional.** `vector` and `hybrid` embed `query` server-side, with the same model the stored\nvectors were written with — so a caller needs no embedder and cannot drift out of the index's\nspace. This field remains for a caller that runs its own and wants an exact probe; it takes\nprecedence over `query` when both are sent."},"source_type":{"type":["string","null"],"description":"Narrow to one provenance: `git` | `atlan` | `local` | `external`."},"strategy":{"type":["string","null"],"description":"`fts` (the default) | `vector` | `hybrid` | `group`.\n\n`group` is the graph filter: it resolves the top match into an anchor plus its typed\nneighbourhood (`depends_on` / `next_step` / `alternative`, both directions) and returns them\nanchor-first, each item carrying `role` / `rel_type` / `direction` / `weight` /\n`confidence`."},"workspace_id":{"type":["string","null"],"description":"Narrow to one workspace. Omitted ⇒ every workspace the caller can read. The account\nboundary is the verified token and never the body."}},"additionalProperties":false},"ServiceAccountCreatedDto":{"type":"object","description":"The reveal-once result of provisioning a service account. **The only place secret material\ncrosses this surface at create.**\n\n`Serialize` only — no `Deserialize` and no `Debug`, for the same reason as [`RotatedCredentialDto`]:\na `Debug` on a struct holding plaintext is one `tracing::debug!` from a credential in a log.","required":["id","client_id","principal_type","scopes","redirect_uris","credentials"],"properties":{"client_id":{"type":"string","description":"The OIDC client this identity authenticates as."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/RevealedCredentialDto"},"description":"Every credential minted, revealed once. Record them now; they are not retrievable."},"id":{"type":"string","description":"The durable principal id the gateway minted."},"principal_type":{"type":"string","description":"Always `service_account`."},"redirect_uris":{"type":"array","items":{"type":"string"},"description":"The redirect URIs the client was registered with, trimmed and de-duplicated; empty for a\nmachine-only client. Non-empty means the client also holds `authorization_code`,\n`refresh_token`, `openid` and `profile` at the identity provider."},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes the identity was provisioned with: the subset of `contextplane:read`,\n`contextplane:write`, `contextplane:manage` and `oauth-clients:manage` requested, or the three\n`contextplane:*` levels when none was given."}}},"ServiceAccountDto":{"type":"object","description":"The wire shape for a machine identity.","required":["id","principal_type","client_id","status","scopes","redirect_uris","credentials","created_at"],"properties":{"client_id":{"type":"string","description":"Stable identifier of the related client resource."},"created_at":{"type":"string","description":"Value of the `created_at` field."},"created_by":{"type":["string","null"],"description":"Value of the `created_by` field."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/CredentialSummaryDto"},"description":"The credentials this identity holds — kind and expiry only. **Never a secret or a handle.**"},"display_name":{"type":["string","null"],"description":"Human-readable name."},"id":{"type":"string","description":"Stable identifier of this resource."},"principal_type":{"type":"string","description":"Always `service_account`: this surface lists and serves no other identity."},"redirect_uris":{"type":"array","items":{"type":"string"},"description":"The client's OAuth redirect URIs; empty for a machine-only client. Non-empty means the client\nmay run the authorization-code flow (`authorization_code` and `refresh_token` beside\n`client_credentials`). Changed with `PATCH`."},"revoked_at":{"type":["string","null"],"description":"Value of the `revoked_at` field."},"scopes":{"type":"array","items":{"type":"string"},"description":"The client's scopes: the ceiling over what its seats allow. A subset of\n`contextplane:read`, `contextplane:write`, `contextplane:manage` and `oauth-clients:manage`.\nChanged with `PATCH`. A client with `redirect_uris` additionally holds `openid` and\n`profile` at the identity provider; they are derived, not stored here."},"status":{"type":"string","description":"Current lifecycle state."},"updated_at":{"type":["string","null"],"description":"RFC 3339, when the identity was last renamed or its redirect URIs or scopes changed. Absent\nif none of that has happened."}}},"ServiceAccountsPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceAccountDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of ServiceAccounts resources."},"SessionIssuedVia":{"type":"string","description":"How a session was signed in.","enum":["magic_otp","google_sso","enterprise_sso","oidc_client","service","org_switch"]},"SessionStatus":{"type":"string","description":"Whether a session is still usable.","enum":["active","revoked"]},"SetReleasePolicyBody":{"type":"object","description":"The body of `PUT /workspaces/{workspace_id}/release-policy/{channel}`.\n\nEvery facet is a double option: absent leaves it alone, `null` clears it back to the level\nbelow — the channel for `require_checks`, the fail-safe default for the other three — and a\nvalue sets it. `PUT` rather than `PATCH` because a merge-patch over four nullable\nfacets cannot tell \"leave this\" from \"clear this\" without exactly this vocabulary, and\nspelling it explicitly is better than inventing a sentinel.","properties":{"allow_version_override":{"type":["boolean","null"],"description":"Whether version override."},"default_visibility":{"type":["string","null"],"description":"Value of the `default_visibility` field."},"mode":{"type":["string","null"],"description":"Value of the `mode` field."},"require_checks":{"type":["boolean","null"],"description":"Value of the `require_checks` field."}},"additionalProperties":false},"SetTraceContentPolicyDto":{"type":"object","description":"The settable half: a PATCH of facets — only fields present in the body\nchange, so a caller setting `capture` is untouched by facets added later.\n`\"capture\": null` clears; the field absent leaves it alone.","properties":{"capture":{"type":["string","null"],"description":"`store` | `drop` | `null` (clear)."}}},"SetVisibilityBody":{"type":"object","description":"`PATCH /workspaces/{id}/visibility` body.","required":["visibility"],"properties":{"visibility":{"type":"string","description":"`public` or `private`. Required — this endpoint sets the value outright, so\nthere is no absent-means-unchanged case a `PATCH` body would otherwise carry."}}},"SlotError":{"type":"object","description":"One item's failure, already rendered.\n\nThe **same four members** a whole-request failure carries, so a slot body and a top-level\nproblem body are the same shape and a client parses one thing. `Clone` because\n[`CreateGrants`] caches refusals, which is the point of that cache.\n\nThere is deliberately **no `type`**. RFC 9457 §3.1 makes an absent `type` mean `about:blank`,\nwhich §4.2.1 defines as \"no additional semantics beyond that of the HTTP status code\" — right\nhere, because the semantics live in the mandatory `code`. The member this replaces was derived\nfrom `code` and nothing else, so it duplicated a mandatory field on every failed slot while\nnaming a fragment of a blank page.\n\n`trace_id` is absent for a different reason: a 207 is **one** response with one trace, and the\nenvelope's own problem body would carry it. Repeating it per slot would say the slots had\nseparate traces.","required":["title","status","detail","code"],"properties":{"code":{"type":"string","description":"The stable machine token — the same vocabulary a single-item failure emits."},"detail":{"type":"string","description":"Value of the `detail` field."},"status":{"type":"integer","format":"int32","minimum":0,"description":"Current lifecycle state."},"title":{"type":"string","description":"Short, human-readable summary — the status's canonical reason."}}},"SpanListEnvelope":{"type":"object","description":"The facade span-list response: cursor-paged spans.","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SpanViewDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/CursorPage"}}},"SpanViewDto":{"type":"object","description":"One span. Mirrors `otel::SpanView`.","required":["span_id","trace_id","name","span_type","span_kind","started_at_unix_seconds","span_status"],"properties":{"attributes":{"description":"The span's attributes: `{\"resource\": {...}, \"scope\": {...}, \"span\": {...}}`,\neach bag a flat map keyed by the exact OTLP attribute key\n(`\"gen_ai.tool.call.id\": \"toolu_1\"`), values in their JSON type, a\nmap-valued attribute as one object under its own key. The same shape in\nevery read mode. Keys promoted to their own fields are not repeated here."},"command_name":{"type":["string","null"],"description":"Value of the `command_name` field."},"cost":{"oneOf":[{"$ref":"#/components/schemas/CostView"},{"type":"null"}],"description":"Value of the `cost` field."},"duration_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Duration in milliseconds."},"ended_at_unix_seconds":{"type":["integer","null"],"format":"int64","description":"Ended at as Unix epoch seconds."},"event_seq":{"type":["integer","null"],"format":"int64","description":"Producer emission order within the trace. Absent for historical spans\nand producers that do not emit `atlan.event.seq`."},"events":{"description":"Value of the `events` field."},"input":{"description":"Value of the `input` field."},"mcp_server":{"type":["string","null"],"description":"Value of the `mcp_server` field."},"metadata":{"description":"Domain-specific attributes attached to this resource."},"model":{"type":["string","null"],"description":"Value of the `model` field."},"name":{"type":"string","description":"Stable machine-readable name."},"output":{"description":"Value of the `output` field."},"parent_span_id":{"type":["string","null"],"description":"Stable identifier of the related parent span resource."},"provider":{"type":["string","null"],"description":"Value of the `provider` field."},"score_name":{"type":["string","null"],"description":"Promoted Eval score dimensions. Present together on `score` spans and\nomitted from every other span type."},"score_value":{"type":["number","null"],"format":"double","description":"Value of the `score_value` field."},"scorer_id":{"type":["string","null"],"description":"Stable identifier of the related scorer resource."},"scorer_version":{"type":["integer","null"],"format":"int64","description":"Value of the `scorer_version` field."},"service_name":{"type":["string","null"],"description":"Value of the `service_name` field."},"session_id":{"type":["string","null"],"description":"The producer's own session id, when it stamped one. The only way back\nfrom a trace to its session: the traces rollup aggregates\n`parent_session_id` but not this, so no trace row carries one."},"skill_name":{"type":["string","null"],"description":"Value of the `skill_name` field."},"skill_version":{"type":["string","null"],"description":"Value of the `skill_version` field."},"span_id":{"type":"string","description":"Stable identifier of the related span resource."},"span_kind":{"type":"string","description":"Value of the `span_kind` field."},"span_status":{"$ref":"#/components/schemas/TraceStatus"},"span_type":{"type":"string","description":"Value of the `span_type` field."},"started_at_unix_seconds":{"type":"integer","format":"int64","description":"Started at as Unix epoch seconds."},"tool_name":{"type":["string","null"],"description":"Value of the `tool_name` field."},"tool_type":{"type":["string","null"],"description":"Value of the `tool_type` field."},"trace_id":{"type":"string","description":"Stable identifier of the related trace resource."},"usage":{"oneOf":[{"$ref":"#/components/schemas/UsageView"},{"type":"null"}],"description":"Value of the `usage` field."}}},"TraceContentDeletionDto":{"type":"object","description":"The delete's answer on the wire.","required":["outcome"],"properties":{"outcome":{"type":"string","description":"`deleted` | `already_deleted`."}}},"TraceContentPolicyDto":{"type":"object","description":"The account's trace-content policy on the wire: a document of facets, one\nfield per facet, so the shape grows without breaking a reader. Every facet\nis always present (explicitly `null` when unset), so \"not configured\" can\nnever be confused with \"an old server that lacks the facet\".","properties":{"capture":{"type":["string","null"],"description":"`store` | `drop` | `null` (never chosen; resolves as `drop`)."},"updated_at":{"type":["string","null"],"description":"When any facet was last changed, and by whom — the policy's own\nprovenance. Absent when nothing was ever configured."},"updated_by":{"type":["string","null"],"description":"Value of the `updated_by` field."}}},"TraceDetailView":{"allOf":[{"$ref":"#/components/schemas/TraceSummaryView"},{"type":"object","required":["links"],"properties":{"content_state":{"type":["string","null"],"description":"The content plane's verdict: `none` | `present` | `deleted` (tombstoned —\n\"content removed\", a different fact from \"no content\") | `error` (the\nplane could not answer; the structural detail is still complete).\nAbsent from deployments that predate the plane — additive."},"input":{"description":"Value of the `input` field."},"links":{"$ref":"#/components/schemas/TraceLinks"},"output":{"description":"Value of the `output` field."},"parent":{"oneOf":[{"$ref":"#/components/schemas/TraceParentView"},{"type":"null"}],"description":"Value of the `parent` field."}}}],"description":"A single trace with its summary + optional root IO + links. Mirrors\n`otel::TraceDetail` (`summary` is flattened onto the object)."},"TraceLinks":{"type":"object","description":"Navigation links on a trace detail. Mirrors `otel::TraceLinks`. The facade\nrewrites these to its own routes before returning to a client.","required":["spans","timeline","logs"],"properties":{"logs":{"type":"string","description":"Value of the `logs` field."},"spans":{"type":"string","description":"Value of the `spans` field."},"timeline":{"type":"string","description":"Value of the `timeline` field."}}},"TraceListEnvelope":{"type":"object","description":"The facade trace-list response: cursor-paged items + the advisory access block.","required":["items","page","access"],"properties":{"access":{"$ref":"#/components/schemas/AccessView"},"items":{"type":"array","items":{"$ref":"#/components/schemas/TraceSummaryView"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/CursorPage"}}},"TraceParentView":{"type":"object","description":"Parent trace relationship when the trace continues an earlier session.","required":["trace_id","is_available"],"properties":{"confidence":{"type":["string","null"],"description":"Value of the `confidence` field."},"identity_version":{"type":["string","null"],"description":"Value of the `identity_version` field."},"is_available":{"type":"boolean","description":"Whether available."},"relationship":{"type":["string","null"],"description":"Value of the `relationship` field."},"session_id":{"type":["string","null"],"description":"Stable identifier of the related session resource."},"trace_id":{"type":"string","description":"Stable identifier of the related trace resource."},"workspace_id":{"type":["string","null"],"description":"Stable identifier of the related workspace resource."}}},"TraceStatus":{"type":"string","description":"Trace/span error state derived from span status. Mirrors `otel::TraceStatus`.","enum":["ok","error","unset"]},"TraceSummaryStats":{"type":"object","description":"Aggregate counts for a trace. Mirrors `otel::TraceSummaryStats`.","required":["span_count","error_count"],"properties":{"error_count":{"type":"integer","format":"int64","minimum":0,"description":"Number of error."},"input_tokens":{"type":["integer","null"],"format":"int64","description":"Value of the `input_tokens` field."},"output_tokens":{"type":["integer","null"],"format":"int64","description":"Value of the `output_tokens` field."},"span_count":{"type":"integer","format":"int64","minimum":0,"description":"Number of span."},"total_cost_usd":{"type":["number","null"],"format":"double","description":"Total cost in US dollars."},"total_tokens":{"type":["integer","null"],"format":"int64","description":"Value of the `total_tokens` field."}}},"TraceSummaryView":{"type":"object","description":"One trace row. Mirrors `otel::TraceSummary`.","required":["trace_id","is_complete","started_at_unix_seconds","trace_status","summary"],"properties":{"attributes":{"description":"Value of the `attributes` field."},"duration_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Duration in milliseconds."},"ended_at_unix_seconds":{"type":["integer","null"],"format":"int64","description":"Ended at as Unix epoch seconds."},"is_complete":{"type":"boolean","description":"Whether complete."},"match_confidence":{"type":["string","null"],"description":"Value of the `match_confidence` field."},"metadata":{"description":"Domain-specific attributes attached to this resource."},"models":{"type":["array","null"],"items":{"type":"string"},"description":"Value of the `models` field."},"providers":{"type":["array","null"],"items":{"type":"string"},"description":"Value of the `providers` field."},"root_span_id":{"type":["string","null"],"description":"Stable identifier of the related root span resource."},"root_span_name":{"type":["string","null"],"description":"Value of the `root_span_name` field."},"run_status":{"type":["string","null"],"description":"Value of the `run_status` field."},"service_name":{"type":["string","null"],"description":"Value of the `service_name` field."},"started_at_unix_seconds":{"type":"integer","format":"int64","description":"Started at as Unix epoch seconds."},"summary":{"$ref":"#/components/schemas/TraceSummaryStats"},"title":{"type":["string","null"],"description":"Value of the `title` field."},"trace_id":{"type":"string","description":"Stable identifier of the related trace resource."},"trace_status":{"$ref":"#/components/schemas/TraceStatus"},"user_id":{"type":["string","null"],"description":"Stable identifier of the related user resource."},"workspace_id":{"type":["string","null"],"description":"Optional, mirroring the producer. A span arrives with whatever resource attributes its client\nstamped and nothing obliges one to name a workspace, so `otel::TraceSummary` omits this field\nfor an unattributed trace rather than emitting a bodyless `\"workspace_\"` handle.\n\nIt was a required `String` here while the producer was already omitting it, so **every** list\nor detail read whose page contained one unattributed trace failed to deserialize — and\n`TraceViewError::Decode` was reported as `traces_unavailable`, a 503 \"retry later\" for a\ncondition no retry could clear. `/spans` and `traces/stats/query` kept working, which is what\nmade it look like an outage rather than a shape mismatch."}}},"UpdateInvitationRequest":{"type":"object","description":"The `PATCH /invitations/{id}` request body: at least one of `role` or `workspace_id`.","properties":{"role":{"type":["string","null"],"description":"The new role: `admin`, `builder` or `viewer`. Legacy `member` is accepted as an alias\nfor `builder`."},"workspace_id":{"type":["string","null"],"description":"The new target workspace handle (`workspace_…`)."}}},"UpdateOrganisationProfileDto":{"type":"object","description":"What a `PATCH /organisations/{org_id}` may set.\n\n`deny_unknown_fields` rejects anything but `name`, so the settings surface's fields cannot ride\nthe profile route. `name` is replace-only here — a value replaces the current one, and there is\nno null to clear it with — which is why it is a plain `Option<String>` rather than the\n`Option<Option<_>>` the clearable PATCH fields use.","properties":{"name":{"type":["string","null"],"description":"The account's display name. Trimmed; at most 200 characters, the control plane's own cap."}},"additionalProperties":false},"UpdateOrganisationSettingsDto":{"type":"object","description":"What a `PATCH /organisations/{org_id}/settings` may set.\n\n**This is the control plane's `UpdateOrgBody`, minus `name`.** The plane declares that body\n`additionalProperties: false`, so a field it does not know is not merely ignored upstream — it\nfails the whole write. That makes the allowlist here a mirror of a closed upstream contract\nrather than a convention, and every field below is one the plane names.\n\n`deny_unknown_fields` is the load-bearing guarantee: it makes `name` (and `slug`, `status`,\n`version`, …) a `400` here, so the profile surface's field cannot ride this route. Every field is\n`skip_serializing_if = \"Option::is_none\"`, so the forwarded body carries only the fields the\ncaller set — an unset field structurally cannot appear, which is what keeps `name` off the wire.","properties":{"auth_method":{"type":["string","null"],"description":"An authentication method to allow on the account. One of [`AUTH_METHODS`].\n\n**Singular, and it is not the inverse of the read.** The account record reports\n`allowed_auth_methods` as a read-only *array*; the plane's write contract takes one\n`auth_method` at a time and derives that array itself. Sending the array is a `400` here (an\nunknown field), which is the honest answer — the plane has no field to put it in."},"join_policy":{"type":["string","null"],"description":"How people join the account. One of [`JOIN_POLICIES`]."},"restrict_invites_to_domains":{"type":["boolean","null"],"description":"Whether invitations are restricted to the account's attached email domains."},"revoke_credentials_on_offboard":{"type":["boolean","null"],"description":"Whether a member's credentials are revoked when they are offboarded."}},"additionalProperties":false},"UpdateOwnUserDto":{"type":"object","description":"What a `PATCH /users/me` may set.\n\n**Documentation only.** The handler forwards the raw body to the control plane, which owns the\nprofile and validates it; nothing here deserializes this type. It exists so the published\nrequest body is an object a generated client can send, not the array of integers a `Vec<u8>`\nannotation renders as. It mirrors the control plane's `PatchCurrentUserInputBody`, which\nrejects any other field.","required":["full_name"],"properties":{"full_name":{"type":"string","description":"The caller's new display name.","maxLength":200,"minLength":1}}},"UpdateServiceAccountBody":{"type":"object","description":"`PATCH /service-accounts/{principal_id}` body. `display_name`, `redirect_uris` and `scopes` are\nthe only fields; any other is `400`.","properties":{"display_name":{"type":["string","null"],"description":"Absent leaves it unchanged; `null` clears it; a string is trimmed and must be 1 to 128\ncharacters with no control characters."},"redirect_uris":{"type":["array","null"],"items":{"type":"string"},"description":"Absent leaves the list unchanged; `null` or `[]` clears it (the client loses\n`authorization_code`, `refresh_token`, `openid` and `profile`); a list replaces it whole and is\nvalidated as on create. A non-empty list needs a live `secret` credential."},"scopes":{"type":["array","null"],"items":{"type":"string"},"description":"Absent leaves the scopes unchanged; a list replaces them whole and is validated as on\ncreate. `null` is `400`: a service account always holds at least one scope.\n`oauth-clients:manage` on a service account that has, or is given, `redirect_uris` is `400`\nwhen both are in the body and `409` when the redirect URIs are already stored."}},"additionalProperties":false},"UpgradeAppBody":{"type":"object","description":"`POST /apps/{app}/upgrade` body.","properties":{"is_pinned":{"type":["boolean","null"],"description":"Freeze the account on the release this upgrade moves it to. Absent means `false` — follow\nthe registration head — which is also how a freeze is released.\n\n`pin` is accepted as an alias, because that is the spelling the architecture doc named before\nthe route existed. `is_pinned` is canonical: it matches the column it writes and the boolean\nnaming rule, and a field called `pin` reads as a verb."}}},"UsageView":{"type":"object","description":"Per-span token usage. Mirrors `otel::UsageView`.","required":["input_tokens","output_tokens","total_tokens","cache_read_tokens","cache_write_tokens"],"properties":{"cache_read_tokens":{"type":"integer","format":"int64","description":"Value of the `cache_read_tokens` field."},"cache_write_tokens":{"type":"integer","format":"int64","description":"Value of the `cache_write_tokens` field."},"input_tokens":{"type":"integer","format":"int64","description":"Value of the `input_tokens` field."},"output_tokens":{"type":"integer","format":"int64","description":"Value of the `output_tokens` field."},"total_tokens":{"type":"integer","format":"int64","description":"Value of the `total_tokens` field."}}},"UserDirectoryDto":{"type":"object","description":"The directory wire shape: the four fields the local projection can answer.\n\n`id`, not `user_id`, for the same reason [`UserDto`]'s is — the resource's own identifier is\n`id`, the column stays `user_id`. `role` is the account role name (`admin` or `member`); a user\nwith no assignment reads as `member`. No `enrichment`/`created_at`/`updated_at`: those were the\ncontrol plane's to render, and these reads no longer forward to it.","required":["id","role"],"properties":{"avatar_url":{"type":["string","null"],"description":"Where to fetch the user's picture (`GET /users/{user_id}/avatar`, with the image's content\ndigest as `?v=`), present exactly when the registry holds one. Absent, not `null`, otherwise\n— a client then falls back to the control plane's identity-provider picture, or draws its\nown placeholder. Fetch it with the caller's bearer; it is not an `<img src>` address."},"email":{"type":["string","null"],"description":"Value of the `email` field."},"id":{"type":"string","description":"Stable identifier of this resource."},"name":{"type":["string","null"],"description":"Stable machine-readable name."},"role":{"type":"string","description":"Value of the `role` field."}}},"UserDto":{"type":"object","description":"The wire shape.","required":["id","created_at","updated_at"],"properties":{"created_at":{"type":"string","description":"Value of the `created_at` field."},"email":{"type":["string","null"],"description":"Value of the `email` field."},"enrichment":{"description":"The opaque provider blob. Absent, not `null`, when unset — \"never enriched\" and\n\"enriched with nothing\" are different answers."},"id":{"type":"string","description":"The durable principal id, unprefixed.\n\n`id`, not `user_id`: every other resource on this surface calls its own identifier `id`,\nand the published contract does here too. The column stays `user_id` — `users` is keyed on\nit and the filter grammar names it — so this is the one place the two spellings meet."},"name":{"type":["string","null"],"description":"Stable machine-readable name."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."}}},"UserProvisioning":{"type":"string","description":"How a user's account was created.","enum":["self_serve","federated","invited"]},"UserSessionDto":{"type":"object","description":"One of the caller's sign-in sessions.","required":["id","user_id","issued_via","status","created_at","last_seen_at"],"properties":{"created_at":{"type":"string","format":"date-time","description":"When the session started."},"id":{"type":"string","description":"The session id."},"ip":{"type":"string","description":"The client address the session was last seen from, when known."},"issued_via":{"$ref":"#/components/schemas/SessionIssuedVia","description":"How the session was signed in."},"last_seen_at":{"type":"string","format":"date-time","description":"When the session was last used."},"revoked_at":{"type":"string","format":"date-time","description":"When the session was revoked, if it was."},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Whether the session is still usable."},"user_agent":{"type":"string","description":"The client's user agent, when known."},"user_id":{"type":"string","description":"The user the session belongs to."}}},"UserSessionsPage":{"type":"object","description":"A page of the caller's sessions.","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserSessionDto"},"description":"The sessions on this page."},"page":{"$ref":"#/components/schemas/ControlPlanePage","description":"The cursor position of this page."}}},"UsersPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserDirectoryDto"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Users resources."},"WhoamiResponse":{"allOf":[{"$ref":"#/components/schemas/IntrospectedIdentity"},{"type":"object","required":["is_onboarded"],"properties":{"is_onboarded":{"type":"boolean","description":"Whether this caller has a personal workspace in this account. `false` with a valid token\nmeans \"authenticated but not provisioned here\"."}}}],"description":"Result returned by the Whoami operation."},"WithdrawBody":{"type":"object","description":"The body of `POST /releases/{release_id}/withdraw`.","properties":{"reason":{"type":["string","null"],"description":"Why. Free text, and the only record there is — unlike a blocked artifact, whose reason\nlives in its scan insight, a withdrawal has no other home for it."}},"additionalProperties":false},"WorkspaceArchiveAck":{"type":"object","description":"`POST /workspaces/{id}/archive` reply.","required":["id","workspace_status","subtree_size","archived_count","cascade_run_id"],"properties":{"archived_count":{"type":"integer","format":"int64","description":"How many nodes **this call** changed. `0` on a re-archive.","minimum":0},"cascade_run_id":{"type":"string","description":"The action run cascading the archive over the subtree's artifacts, projects and repos.\n\nThe workspace rows are archived synchronously — they are a handful of rows and the caller\nasked for them — but their *contents* can be thousands of artifacts, each with an\n`archive.pre` hook that may refuse. That is a run, not a request: poll\n`GET /action-runs/{cascade_run_id}` for its status and `…/jobs` for the per-item report,\nwhich names anything that refused and why.\n\nOn a re-archive: the cascade still in flight if there is one, otherwise the next attempt."},"id":{"type":"string","description":"Stable identifier of this resource."},"subtree_size":{"type":"integer","description":"How many nodes the subtree had, as the caller's receipted read saw it. Reported beside\n`archived_count` because the two differing is meaningful: it means some nodes were already\narchived, not that any were missed.","minimum":0},"workspace_status":{"type":"string","description":"Always `archived`, echoed so a client need not assume it."}}},"WorkspaceBulkCreateRequest":{"type":"object","description":"`POST /workspaces/bulk` body.","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateWorkspaceBody"},"description":"Up to 100 items, each exactly a `POST /workspaces` body."}}},"WorkspaceExport":{"type":"object","description":"`GET /workspaces/{id}/export` reply.\n\nThree flat lists rather than a tree: the export is first-level only, so nesting would imply a\ndepth it does not have.","required":["artifacts","projects","workspaces"],"properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactView"},"description":"Every artifact whose `workspace_id` is this workspace — direct members, L1 only."},"projects":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSummary"},"description":"The projects in this workspace."},"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/registry.WorkspaceView"},"description":"The **immediate** child workspaces. Not the whole subtree: a caller walking the tree asks for\neach child's own export, which keeps one response bounded by one workspace's contents."}}},"WorkspaceInvitationListDto":{"type":"object","description":"Pending invites targeting one workspace.","required":["invitations"],"properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceInvitationRow"},"description":"Value of the `invitations` field."}}},"WorkspaceInvitationRow":{"type":"object","description":"One pending invite into a workspace.","required":["invitation_id","email","role"],"properties":{"email":{"type":"string","description":"Value of the `email` field."},"invitation_id":{"type":"string","description":"Stable identifier of the related invitation resource."},"role":{"type":"string","description":"Value of the `role` field."}}},"WorkspaceRecommendationsPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/registry.WorkspaceRecommendation"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of WorkspaceRecommendations resources."},"WorkspaceSlot":{"type":"object","description":"One index's outcome. Exactly one of the payload and `error` is present.","required":["index","status_code"],"properties":{"error":{"oneOf":[{"$ref":"#/components/schemas/SlotError","description":"The problem document, when it failed."},{"type":"null"}],"description":"Error returned when the operation fails."},"index":{"type":"integer","description":"The item's position in the request, so a client can join a failure back to what\nit sent. Sent even on success, because a caller filtering to the failures still\nneeds the index of each.","minimum":0},"status_code":{"type":"integer","format":"int32","description":"The item's own success or failure status.","minimum":0},"workspace":{"oneOf":[{"$ref":"#/components/schemas/registry.WorkspaceView","description":"The resource, when this item succeeded."},{"type":"null"}],"description":"Value of the `workspace` field."}}},"WorkspacesBulkResponse":{"type":"object","description":"The batch response. Always `207`, even when every item succeeded.\n\nUniform on purpose: a client that has to branch on the envelope status before it can\nread the slots will get that branch wrong on the day one item fails.\n\n**No `created`/`failed` counters.** They were a convenience over `items`, and they are\nthe kind of derived field that goes stale: the published contract carries the slots\nalone, and `items.iter().filter(...)` is the same loop wherever it is written.","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceSlot"},"description":"Results aligned with the submitted item positions."}}},"WorkspacesPage":{"type":"object","required":["items","page"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/registry.WorkspaceView"},"description":"Items in this result."},"page":{"$ref":"#/components/schemas/registry.PageMeta","description":"The window this page was served under."}},"description":"Paginated collection of Workspaces resources."},"gateway.ArtifactIdentityRevealView":{"type":"object","description":"The public identity result for an artifact. An agent's client secret and API key are both\nrevealed once on create; the client secret is also kept in Gateway custody for the OBO broker.\nNeither credential appears on reads or in the hand-written [`std::fmt::Debug`] output below.\n\nThe `#[schema(as = …)]` name is the crud-side `ArtifactIdentityRevealView`'s: the two live in\ndifferent OpenAPI documents, and one component name means one client-visible shape.","required":["client_id","credential_kind"],"properties":{"api_key":{"type":["string","null"],"description":"The opaque API key — the agent's machine credential. Present on the create response and on a\nrotate that rotated the api_key. Reveal-once; capture it now."},"api_key_expires_at":{"type":["string","null"],"description":"The **api_key**'s expiry (RFC 3339), when the Control Plane TTLs it. The client secret carries\nno gateway-set expiry, so this names the api_key alone."},"client_id":{"type":"string","description":"The Control-Plane OIDC client id backing this identity. Not secret."},"client_secret":{"type":["string","null"],"description":"The client's own secret — the OBO/authorization-code credential. Present on the create\nresponse for an agent, and on a rotate that rotated the secret. Reveal-once; capture it now.\nGateway custody keeps its own copy, so the OBO broker never needs it handed back. Absent\nwhen the caller is an agent acting for a user (`registry_server::identity::reveal_for`)."},"credential_kind":{"type":"string","description":"The credential kind the row records as **primary** — `secret` for an agent client. The client\nholds two credentials (see `client_secret` and `api_key`); this names the one it authenticates\nwith."}}},"gateway.CapabilityMatrix":{"type":"object","description":"The caller's advisory `can_*` capability matrix on a resource.\n\nAdvisory only: it reflects what the caller may do, and is for a UI to gate\ncontrols on. It never authorizes a request — the platform decides that\nindependently on every call.\n\nDeliberately an open map rather than a typed struct. The authoritative\npermission tables are internal to the platform core, and lifting them into the\nSDK would put an authorization decision surface into every extension. An\nextension reads this matrix; it never derives one.","additionalProperties":{"type":"boolean"},"propertyNames":{"type":"string"}},"gateway.TraceStatsComparison":{"type":"object","description":"The prior-period payload, present when `compare = previous_period`.","required":["start_time_unix_seconds","end_time_unix_seconds","data"],"properties":{"data":{"$ref":"#/components/schemas/gateway.TraceStatsData"},"end_time_unix_seconds":{"type":"integer","format":"int64","description":"Prior window end, equal to the current window's start."},"start_time_unix_seconds":{"type":"integer","format":"int64","description":"Prior window start (unix epoch seconds, UTC)."}}},"gateway.TraceStatsData":{"oneOf":[{"type":"object","required":["results","request_type"],"properties":{"request_type":{"type":"string","enum":["scalar"],"description":"Value of the `request_type` field."},"results":{"type":"array","items":{"$ref":"#/components/schemas/gateway.TraceStatsScalarResult"},"description":"Value of the `results` field."}}},{"type":"object","required":["columns","rows","request_type"],"properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/gateway.TraceStatsTableColumn"},"description":"Value of the `columns` field."},"request_type":{"type":"string","enum":["table"],"description":"Value of the `request_type` field."},"rows":{"type":"array","items":{"$ref":"#/components/schemas/gateway.TraceStatsTableRow"},"description":"Value of the `rows` field."}}},{"type":"object","required":["series","request_type"],"properties":{"request_type":{"type":"string","enum":["time_series"],"description":"Value of the `request_type` field."},"series":{"type":"array","items":{"$ref":"#/components/schemas/gateway.TraceStatsSeries"},"description":"Value of the `series` field."}}}],"description":"The results, discriminated by the `request_type` that produced them."},"gateway.TraceStatsEnvelope":{"type":"object","description":"The statistics response.\n\nRaw values only — a client computes display deltas against `comparison`\nitself.","required":["data","meta"],"properties":{"comparison":{"oneOf":[{"$ref":"#/components/schemas/gateway.TraceStatsComparison"},{"type":"null"}],"description":"Value of the `comparison` field."},"data":{"$ref":"#/components/schemas/gateway.TraceStatsData"},"meta":{"$ref":"#/components/schemas/gateway.TraceStatsMeta"}}},"gateway.TraceStatsMeasure":{"type":"string","description":"What a query measures.","enum":["sessions","traces","spans","skill_invocations","tool_calls","tokens","uncached_input_tokens","cached_input_tokens","cache_write_tokens","output_tokens","active_users","active_visitors","error_rate","success_rate","tokens_per_trace","cost","latency_p50","latency_p90","latency_p99","score_value","scores"]},"gateway.TraceStatsMeta":{"type":"object","description":"Non-fatal notes about how a request was executed, plus the window it was\nexecuted over and how fresh the data is.","properties":{"as_of_unix_seconds":{"type":["integer","null"],"format":"int64","description":"When the data was computed (unix epoch seconds, UTC): the oldest cache\nentry among the current window's panels, or the request time when none\nwas served from cache. Now minus this value is the result's staleness.\nAbsent only from a trace engine older than the cache."},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal warnings produced while serving the request."},"window":{"oneOf":[{"$ref":"#/components/schemas/gateway.TraceStatsWindow","description":"The window the statistics were computed over: the requested window,\nwidened outward to the trace engine's read-cache grain (60 s by default)\nso identical dashboards share one cache entry. It always contains the\nrequested window. Absent only from a trace engine older than the cache."},{"type":"null"}],"description":"Value of the `window` field."}}},"gateway.TraceStatsScalarResult":{"type":"object","description":"One `scalar` result.","required":["query_name","measure"],"properties":{"measure":{"$ref":"#/components/schemas/gateway.TraceStatsMeasure"},"query_name":{"type":"string","description":"Value of the `query_name` field."},"unit":{"type":["string","null"],"description":"Value of the `unit` field."},"value":{"type":["number","null"],"format":"double","description":"Absent when the measure has no value in this window (e.g. `cost` with no\ncost data) — distinct from zero."}}},"gateway.TraceStatsSeries":{"type":"object","description":"One query's `time_series` result.","required":["query_name","measure","points"],"properties":{"measure":{"$ref":"#/components/schemas/gateway.TraceStatsMeasure"},"points":{"type":"array","items":{"$ref":"#/components/schemas/gateway.TraceStatsSeriesPoint"},"description":"Value of the `points` field."},"query_name":{"type":"string","description":"Value of the `query_name` field."},"unit":{"type":["string","null"],"description":"Value of the `unit` field."}}},"gateway.TraceStatsSeriesPoint":{"type":"object","description":"One time-series bucket beginning at a UTC Unix timestamp.","required":["timestamp_unix_seconds"],"properties":{"timestamp_unix_seconds":{"type":"integer","format":"int64","description":"Timestamp as Unix epoch seconds."},"value":{"type":["number","null"],"format":"double","description":"Value carried by this entry."}}},"gateway.TraceStatsTableColumn":{"type":"object","description":"One `table` column.","required":["name","column_type"],"properties":{"column_type":{"$ref":"#/components/schemas/gateway.TraceStatsTableColumnType"},"name":{"type":"string","description":"Stable machine-readable name."},"unit":{"type":["string","null"],"description":"Value of the `unit` field."}}},"gateway.TraceStatsTableColumnType":{"type":"string","description":"Whether a table column is a grouping dimension or a measure.","enum":["group","measure"]},"gateway.TraceStatsTableRow":{"type":"object","description":"One `table` row: dimension values and measure values, keyed by column name.","required":["groups","values"],"properties":{"groups":{"description":"Value of the `groups` field."},"values":{"description":"Values carried by this result."}}},"gateway.TraceStatsWindow":{"type":"object","description":"A statistics window in unix epoch seconds, UTC.","required":["start_time_unix_seconds","end_time_unix_seconds"],"properties":{"end_time_unix_seconds":{"type":"integer","format":"int64","description":"Window end, exclusive (unix epoch seconds, UTC)."},"start_time_unix_seconds":{"type":"integer","format":"int64","description":"Window start, inclusive (unix epoch seconds, UTC)."}}},"registry.PageMeta":{"type":"object","required":["limit","offset"],"properties":{"limit":{"type":"integer","format":"int32","description":"Maximum number of items to return.","minimum":0},"offset":{"type":"integer","format":"int32","description":"Rows skipped before this page.","minimum":0},"total":{"type":["integer","null"],"format":"int64","description":"Matching rows independent of `limit`/`offset`: a client has more when\n`offset + items.len() < total`.\n\nAbsent when the caller passed `count=false`, and absent rather than `0`, because \"not\ncounted\" and \"none\" are different answers.","minimum":0}},"description":"Published representation of PageMeta."},"registry.WorkspaceRecommendation":{"type":"object","description":"One workspace the caller should consider joining, and the evidence for it.","required":["workspace","reason","score"],"properties":{"matched_email":{"type":["string","null"],"description":"The detected contributor address that matched, as the source recorded it — which may differ\nfrom the caller's verified address when the match was on the resolved one. Present only on\n`detected_contributor`."},"reason":{"$ref":"#/components/schemas/registry.WorkspaceRecommendationReason","description":"The strongest signal behind this suggestion."},"resolved_via":{"type":["string","null"],"description":"How that address was resolved to the caller: `domain` or `exa`. Absent when the match was\non the source address directly, which is every row today — nothing on this stack writes a\nresolved address automatically."},"score":{"type":"number","format":"double","description":"The fused rank score.\n\n**Comparable within one response and meaningless across two** — it is a sum of reciprocal\nranks over this request's candidate set, not a probability and not a similarity. Never\nthreshold on an absolute value."},"workspace":{"$ref":"#/components/schemas/registry.WorkspaceView","description":"The workspace, rendered exactly as `GET /workspaces` renders it.\n\nNested rather than `#[serde(flatten)]`: a flattened struct renders as an `allOf` with\nsibling properties, which several generators handle badly, and the item genuinely *is* a\nworkspace plus a rationale rather than a workspace with extra columns."}}},"registry.WorkspaceRecommendationReason":{"type":"string","description":"Why a workspace is being suggested.\n\nOne reason per suggestion even when several signals contributed, because a client renders one\nsentence. `score` is what carries the fusion; this carries the headline.","enum":["detected_contributor","nearby","text_match"]},"registry.WorkspaceView":{"type":"object","required":["id","name","display_name","workspace_status","kind","root_workspace_id","org_wide","visibility","created_by","created_at","updated_by","updated_at"],"properties":{"artifact_count":{"type":["integer","null"],"format":"int64","description":"How many artifacts this workspace holds, and **only** when `include=artifact_counts`\nasked for it — then on **every** row of the page, `0` included.\n\nThe `discover`-band count the pre-Postgres stack served unconditionally and the cutover\ndropped: it is the affordance that lets someone decide whether a workspace is worth\njoining, and its absence made every unjoined row read \"0 skills\". The inverse of\n`member_count`'s absent-rather-than-zero rule, and deliberately so — a roster size is\nunknowable at `discover`, an artifact count is not, because it names nobody\n(`registry_tenancy::workspace::artifact_counts`).","minimum":0},"artifact_count_by_kind":{"type":["object","null"],"description":"The per-kind breakdown of [`Self::artifact_count`], which it sums to. Attached and absent\nwith it, always — two fields, one embed, so a client never sees a total it cannot explain.\n\nA kind with no artifacts here is **absent** rather than `0`: the map is what the workspace\nholds, not the kind registry. A `BTreeMap`, so the key order is stable across responses.","additionalProperties":{"type":"integer","format":"int64","minimum":0},"propertyNames":{"type":"string"}},"created_at":{"type":"string","description":"Value of the `created_at` field."},"created_by":{"type":"string","description":"Value of the `created_by` field."},"description":{"type":["string","null"],"description":"Human-readable description."},"display_name":{"type":"string","description":"Human-readable name."},"id":{"type":"string","description":"Stable identifier of this resource."},"kind":{"type":"string","description":"Domain discriminator for this resource."},"member_count":{"type":["integer","null"],"format":"int64","description":"Roster size, and **only** when `include=member_count` asked for it.\n\nAbsent rather than `0` when unrequested, so a client cannot read a missing embed as an\nempty workspace. Also absent for a workspace the caller can *discover* but not *read*:\nthe count is taken under a `Read` receipt on the membership rows while this list runs\nunder `Discover`, so a headcount is never a thing discovery alone reveals\n(`registry_tenancy::workspace::member_counts`).","minimum":0},"name":{"type":"string","description":"Stable machine-readable name."},"org_wide":{"type":"boolean","description":"Whether this workspace sits in the account's **shared** tree, and so is org-discoverable\nand self-joinable.\n\nDerived from the tree root, never stored, so a reparent moves it with the row. Not a\npublished field upstream — it is this stack's convenience — but it has to be *right*,\nand it was not: the previous derivation was `root_workspace_id != id || kind ==\nOrgDefault`, which is `true` for **every** non-root workspace, including every child of a\npersonal tree. A workspace inside someone's private space rendered as org-wide."},"parent_id":{"type":["string","null"],"description":"`None` for a singleton, which is a tree root."},"permissions":{"oneOf":[{"$ref":"#/components/schemas/gateway.CapabilityMatrix","description":"The caller's advisory `can_*` capability matrix, and **only** when `include=permissions`\nasked for it. Advisory only: a UI gates controls on it; it never authorizes a request."},{"type":"null"}],"description":"Value of the `permissions` field."},"root_workspace_id":{"type":"string","description":"Stable identifier of the related root workspace resource."},"updated_at":{"type":"string","description":"Value of the `updated_at` field."},"updated_by":{"type":"string","description":"Value of the `updated_by` field."},"visibility":{"type":"string","description":"`public` or `private` — how open this shared-tree workspace is: whether the\naccount can list it and self-join it. Meaningful only when `org_wide` is\ntrue; a personal-tree workspace is always `private`. Set on create (inherits\nthe parent when omitted) and changed by `PATCH /workspaces/{id}/visibility`."},"workspace_status":{"type":"string","description":"The lifecycle state.\n\n`workspace_status`, not `status`: it is the published spelling, and it is the name the\nfilter grammar already uses (`registry_model::workspace::Entity`'s `Field` is\n`workspace_status`). Serving `status` while accepting `filter[workspace_status]` meant a\nclient read a field it could not filter on."}},"description":"Published representation of Workspace."}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Forwarded inbound bearer token — verified by the gateway's auth layer."}}},"security":[{"bearer":[]}],"tags":[{"name":"apps","description":"Apps: what this account can install, and what it has."},{"name":"auth","description":"Token introspection."},{"name":"discovery","description":"Ranked search and grouped aggregation over the artifact plane."},{"name":"invitations","description":"Account invitations."},{"name":"oauth-grants","description":"Delegated-access grants, proxied to the control plane."},{"name":"organisations","description":"The caller's own account: profile, settings, avatar, roles, email domains and audit events."},{"name":"releases","description":"The release plane: what shipped, on which channel, under whose policy."},{"name":"repos","description":"Source repositories."},{"name":"service-accounts","description":"Machine identities the account owns."},{"name":"sessions","description":"User sessions, proxied to the control plane."},{"name":"users","description":"The account's directory of principals, and onboarding."},{"name":"workspaces","description":"Workspaces and their member rosters."}]}