{ "openapi": "3.1.0", "info": { "title": "Databasezy API", "description": "Managed multi-engine database hosting. Resource-oriented REST; every request is scoped to one organization. Errors are RFC 9457 problem details.", "license": { "name": "Apache-2.0" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.databasezy.com" }, { "url": "http://localhost:8080", "description": "local dev" } ], "paths": { "/healthz": { "get": { "tags": [ "system" ], "summary": "Liveness/readiness probe.", "operationId": "healthz", "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/v1/engines": { "get": { "tags": [ "catalogue" ], "summary": "List catalogue engines with their availability (`coming_soon` ones cannot be ordered).", "operationId": "engines", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EngineDto" } } } } } } } }, "/v1/invites/{token}/accept": { "post": { "tags": [ "members" ], "summary": "Accept an invite with the token from the email. The signed-in user joins the org\nwith the invited role; when the user's email is known it must match the invite.", "operationId": "accept", "parameters": [ { "name": "token", "in": "path", "description": "Invite token from the email link", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Joined; the org with your role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgDto" } } } }, "402": { "description": "seat_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Invite expired, revoked or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/me": { "get": { "tags": [ "account" ], "summary": "The caller: profile, session assurance (MFA / aal) and organizations with roles.", "operationId": "me", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs": { "get": { "tags": [ "orgs" ], "summary": "List the organizations the caller belongs to (an API key sees only its own org).", "operationId": "list", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgDto" } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "orgs" ], "summary": "Create an organization. The caller becomes its `owner`. API keys cannot create orgs.", "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}": { "get": { "tags": [ "orgs" ], "summary": "Get one organization.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/actions/close": { "post": { "tags": [ "orgs" ], "summary": "Close the organization (owner, MFA session): every live instance is deleted with\nthe plan's retention window or, with `erase_everything`, erased immediately; all API\nkeys are revoked. Members keep read access to the closed org.", "operationId": "close", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseOrgRequest" } } }, "required": true }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseOrgResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/alerts": { "get": { "tags": [ "alerts" ], "summary": "Recent alerts for the org: quota thresholds, backup and instance failures, security\nevents concerning the org. Newest first.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "include_acknowledged", "in": "query", "description": "Include acknowledged alerts (default true).", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "min_severity", "in": "query", "description": "Only alerts at or above this severity (`info`, `warning`, `critical`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertListDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/alerts/{alert_id}/actions/acknowledge": { "post": { "tags": [ "alerts" ], "summary": "Acknowledge an alert (hides it from `include_acknowledged=false` views).", "operationId": "acknowledge", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "alert_id", "in": "path", "description": "Alert id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/api-keys": { "get": { "tags": [ "api-keys" ], "summary": "List active API keys (metadata only), service-account keys included and flagged.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_ApiKeyDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "api-keys" ], "summary": "Create an API key. The response contains the secret `key`; it is never shown again.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKeyDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/api-keys/{key_id}": { "delete": { "tags": [ "api-keys" ], "summary": "Revoke an API key immediately.", "operationId": "revoke", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "description": "API key id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/api-keys/{key_id}/actions/unsuspend": { "post": { "tags": [ "api-keys" ], "summary": "Lift a suspension placed by an automatic security response (docs/20 §3). The key\nworks again at once; the lift is audited.", "operationId": "unsuspend", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "description": "API key id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/approvals": { "get": { "tags": [ "approvals" ], "summary": "Approval requests visible to the caller: org admins see all; team leads see their\nteams'; everyone sees their own (`mine=true`).", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "`pending` (default), `approved`, `denied`, `expired` or `all`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "team_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "mine", "in": "query", "description": "Only requests made by the caller.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_ApprovalDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/approvals/{approval_id}": { "get": { "tags": [ "approvals" ], "summary": "One approval request (requester, team leads and org admins).", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "approval_id", "in": "path", "description": "Approval request id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/approvals/{approval_id}/actions/approve": { "post": { "tags": [ "approvals" ], "summary": "Approve: the stored request goes through the normal create path (validation, team\nlimits and quota re-checked; policy and budget skipped) as the requester.", "operationId": "approve", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "approval_id", "in": "path", "description": "Approval request id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideApprovalRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not pending, expired or the instance conflicts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The request no longer validates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/approvals/{approval_id}/actions/deny": { "post": { "tags": [ "approvals" ], "summary": "Deny with a reason (required).", "operationId": "deny", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "approval_id", "in": "path", "description": "Approval request id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideApprovalRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecisionDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/audit": { "get": { "tags": [ "audit" ], "summary": "The org's audit log, newest first (credential reveals, member and key changes,\nstaff impersonation, security responses, ...).", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Inclusive start (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "description": "Exclusive end (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "`next_cursor` of the previous page.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "1..=1000, default 100.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "action", "in": "query", "description": "Exact action, e.g. `credentials.reveal`, `member.remove`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "actor_id", "in": "query", "description": "Exact actor id (`usr_...`, `key_...`, staff id).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPageDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/audit/export": { "get": { "tags": [ "audit" ], "summary": "CSV export of the filtered audit log (up to 50 000 rows; narrow `from`/`to` for\nmore). The export itself is audited.", "operationId": "export", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Inclusive start (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "description": "Exclusive end (RFC 3339).", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "`next_cursor` of the previous page.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "1..=1000, default 100.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "action", "in": "query", "description": "Exact action, e.g. `credentials.reveal`, `member.remove`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "actor_id", "in": "query", "description": "Exact actor id (`usr_...`, `key_...`, staff id).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "text/csv attachment", "content": { "text/csv": {} } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/audit/siem-deliveries": { "get": { "tags": [ "audit" ], "summary": "SIEM deliveries of the org's audit log.", "operationId": "list_siem", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiemDeliveryDto" } } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "audit" ], "summary": "Stream the org's audit log to a webhook or S3 bucket.", "operationId": "create_siem", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiemDeliveryRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiemDeliveryDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/audit/siem-deliveries/{delivery_id}": { "delete": { "tags": [ "audit" ], "summary": "Remove a SIEM delivery.", "operationId": "delete_siem", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "delivery_id", "in": "path", "description": "Delivery id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/audit/siem-deliveries/{delivery_id}/actions/{action}": { "post": { "tags": [ "audit" ], "summary": "`enable` or `disable` a SIEM delivery.", "operationId": "toggle_siem", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "delivery_id", "in": "path", "description": "Delivery id", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "`enable` or `disable`", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`{id, enabled}`" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/backups/health": { "get": { "tags": [ "backups" ], "summary": "Monthly customer-visible backup health (docs/09 §6): Team and Enterprise only.", "operationId": "health", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupHealthDto" } } } }, "403": { "description": "Plan below Team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/ca.pem": { "get": { "tags": [ "instances" ], "summary": "CA chains of every cell hosting the org's instances (all cells when none is\nplaced yet), concatenated.", "operationId": "org_ca", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PEM bundle", "content": { "application/x-pem-file": { "schema": { "type": "string" } } } }, "503": { "description": "No CA registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/compliance": { "get": { "tags": [ "compliance" ], "summary": "Compliance status: BAA, MFA policy, secure placement availability.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/compliance/baa/sign": { "post": { "tags": [ "compliance" ], "summary": "Sign the BAA (owner, MFA session). Requires a plan that offers secure placement\n(Team+). Sets `mfa_required` for the org.", "operationId": "sign_baa", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignBaaRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceDto" } } } }, "403": { "description": "Not the owner, or `mfa_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "This version is already signed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/cost-report": { "get": { "tags": [ "usage" ], "summary": "Monthly cost report per team and cost centre (CSV or JSON).", "operationId": "cost_report", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "description": "`YYYY-MM` (UTC); defaults to the current month.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "format", "in": "query", "description": "`json` (default) or `csv`; `Accept: text/csv` also selects CSV.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "JSON, or `text/csv` with `format=csv`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostReportDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/credits": { "get": { "tags": [ "growth" ], "summary": "Credits granted to the org (referrals, promo codes, programmes).", "operationId": "list_credits", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CreditGrantDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/enterprise": { "get": { "tags": [ "enterprise" ], "summary": "The enterprise account this org is the parent of.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "enterprise" ], "summary": "Turn this org into an enterprise parent (owner, Enterprise plan).", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnterpriseRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseDto" } } } }, "402": { "description": "Enterprise plan required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] }, "patch": { "tags": [ "enterprise" ], "summary": "Contract terms, consolidated invoicing and global policies (owner of the parent).", "operationId": "update", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnterpriseRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/enterprise/sso": { "get": { "tags": [ "enterprise" ], "summary": "SAML SSO / SCIM status (placeholder until ZB-166).", "operationId": "get_sso", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "put": { "tags": [ "enterprise" ], "summary": "Record the SAML IdP metadata (status `pending_verification`; the SAML bridge of\nZB-166 verifies it and flips the status to `active`).", "operationId": "put_sso", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSsoRequest" } } }, "required": true }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/enterprise/subsidiaries": { "get": { "tags": [ "enterprise" ], "summary": "Subsidiary orgs.", "operationId": "list_subsidiaries", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubsidiaryDto" } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "enterprise" ], "summary": "Attach an org the caller also owns as a subsidiary.", "operationId": "add_subsidiary", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSubsidiaryRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/enterprise/subsidiaries/{subsidiary_id}": { "delete": { "tags": [ "enterprise" ], "summary": "Detach a subsidiary (it keeps its own plan and invoices from the next period).", "operationId": "remove_subsidiary", "parameters": [ { "name": "org_id", "in": "path", "description": "Parent (billing) organization id", "required": true, "schema": { "type": "string" } }, { "name": "subsidiary_id", "in": "path", "description": "Subsidiary org id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Detached" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/events": { "get": { "tags": [ "events" ], "summary": "Stream every customer event of the org.", "operationId": "org_events", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "Last-Event-ID", "in": "header", "description": "Resume after this event id (best effort)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "`text/event-stream`: `id`, `event` (type) and `data` (envelope); comment heartbeat every 15 s", "content": { "text/event-stream": {} } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances": { "get": { "tags": [ "instances" ], "summary": "List all instances in the org.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_InstanceDto" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}": { "get": { "tags": [ "instances" ], "summary": "Get an instance.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "instances" ], "summary": "Delete an instance. Sets `desired_status=deleted`; data is retained for the plan's\nretention window before being purged.", "operationId": "remove", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Deletion requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "patch": { "tags": [ "instances" ], "summary": "Change size, storage, engine version, placement, maintenance window or name.", "operationId": "update", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInstanceRequest" } } }, "required": true }, "responses": { "200": { "description": "Settings applied (`applied`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceUpdateDto" } } } }, "202": { "description": "Sagas requested (`accepted`), or a team lead's approval is needed (`approval_required`, body `ApprovalRequiredDto`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceUpdateDto" } } } }, "402": { "description": "Billing froze the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not running, being deleted, or a change of the same kind is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Plan, team quota, spending cap or validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/actions/erase": { "post": { "tags": [ "instances" ], "summary": "Full erasure (owner, docs/11 §9): purge immediately including the last backup,\noverriding the retention window. `confirm` must equal the instance name. The audit\nrow with `erasure_certificate_id` is the erasure certificate.", "operationId": "erase", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EraseInstanceRequest" } } }, "required": true }, "responses": { "202": { "description": "Erasure requested; `erasure_certificate_id` set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "403": { "description": "Not an owner, or `mfa_required`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already being deleted or erased", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`confirm` does not match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/actions/pause": { "post": { "tags": [ "instances" ], "summary": "Pause an instance (scale to zero, storage kept).", "operationId": "pause", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Pause requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Engine cannot pause or instance is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/actions/resume": { "post": { "tags": [ "instances" ], "summary": "Resume a paused instance.", "operationId": "resume", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Resume requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/backup-settings": { "get": { "tags": [ "backups" ], "summary": "Backup settings: plan caps, the customer's overrides and the effective schedule.", "operationId": "settings_get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSettingsDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "patch": { "tags": [ "backups" ], "summary": "Update the backup settings within the plan caps (docs/09 §2 knobs). The backup\nservice applies them and re-emits the schedule to the cell.", "operationId": "settings_update", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupOverridesDto" } } }, "required": true }, "responses": { "202": { "description": "Accepted; effective schedule after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupSettingsDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/backups": { "get": { "tags": [ "backups" ], "summary": "Backups of an instance, newest first.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_BackupDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Backup catalogue unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "backups" ], "summary": "Request a manual snapshot. Counted against the plan's manual quota\n(docs/09 §2); the cell runs it asynchronously.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBackupRequest" } } }, "required": true }, "responses": { "202": { "description": "Backup requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupRequestedDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Quota reached or instance not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/backups/{backup_id}": { "get": { "tags": [ "backups" ], "summary": "One backup.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "backup_id", "in": "path", "description": "Backup id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/backups/{backup_id}/actions/restore": { "post": { "tags": [ "backups" ], "summary": "Restore a backup. Default `new_instance`: a new instance is created from the\nsource's spec and restored from the backup (the source is untouched). `in_place`\nneeds `confirm_name` equal to the instance name; the cell takes a pre-change backup\nfirst (docs/09 §5). `target_time` selects a point in time inside the PITR window.", "operationId": "restore", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "backup_id", "in": "path", "description": "Backup id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreRequest" } } }, "required": true }, "responses": { "202": { "description": "Restore requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/branches": { "get": { "tags": [ "instances" ], "summary": "Branches of an instance (instances with `branch_of` = this one).", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Source instance id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_InstanceDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "instances" ], "summary": "Create a branch of an instance.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Source instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBranchRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted; status is `requested`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/ca.pem": { "get": { "tags": [ "instances" ], "summary": "The CA chain of the instance's cell (PEM), for `sslrootcert` / `--tlsCAFile`.", "operationId": "instance_ca", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PEM bundle", "content": { "application/x-pem-file": { "schema": { "type": "string" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not placed on a cell yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No CA registered for the cell", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/capacity": { "get": { "tags": [ "instances" ], "summary": "What the instance can hold: storage use and growth, connections, memory pressure.", "operationId": "capacity", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapacityDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Metering is not configured or unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/changes": { "get": { "tags": [ "instances" ], "summary": "Size / storage / version / placement changes of an instance, newest first.", "operationId": "list_changes", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceChangesDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/console-sessions": { "post": { "tags": [ "instances" ], "summary": "Open a web console session on an instance.", "operationId": "create_session", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConsoleSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsoleSessionDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not placed on a cell yet / being deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit (shared class with credential reveal)" }, "503": { "description": "No console key for the cell", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/credentials/reveal": { "post": { "tags": [ "instances" ], "summary": "Mint a one-time URL that reveals the instance credentials once (GET on the cell\noperator). Requires `credentials:reveal` in the instance's team and an MFA session —\nor a service-account key with `credentials:reveal:integration` and\n`{\"purpose\": \"integration_env_sync\"}`.", "operationId": "reveal", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RevealRequest" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneTimeUrlDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not placed on a cell yet / being deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Reveal rate limit" }, "503": { "description": "No key for the cell", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/credentials/rotate": { "post": { "tags": [ "instances" ], "summary": "Mint a one-time URL that requests a credential rotation (POST on the cell\noperator; the previous password stays valid 10 minutes).", "operationId": "rotate", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneTimeUrlDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Reveal rate limit" }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/domains": { "get": { "tags": [ "network" ], "summary": "Custom domains of an instance.", "operationId": "list_domains", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainListDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "network" ], "summary": "Add a custom domain. The response carries the CNAME to create; the domain is\nverified immediately when the record already exists (then the cell requests its\ncertificate), otherwise call `…/actions/verify` once DNS has propagated.", "operationId": "add_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDomainRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The instance already has a domain, the hostname is taken, or the instance has no endpoint yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid hostname or plan quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/domains/{domain_id}": { "delete": { "tags": [ "network" ], "summary": "Remove the custom domain (the cell drops its route and certificate).", "operationId": "remove_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "description": "Domain id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/domains/{domain_id}/actions/verify": { "post": { "tags": [ "network" ], "summary": "Re-check the CNAME of a pending (or failed) domain.", "operationId": "verify_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "description": "Domain id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/events": { "get": { "tags": [ "events" ], "summary": "Stream the events of one instance.", "operationId": "instance_events", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "Last-Event-ID", "in": "header", "description": "Resume after this event id (best effort)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "`text/event-stream` of this instance's events", "content": { "text/event-stream": {} } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/logs": { "get": { "tags": [ "instances" ], "summary": "Engine logs: a single-use URL on the cell operator that streams the engine pod's\nlogs (`follow=true` keeps it open). Needs `instances:operate` in the instance's team\nand an MFA session.", "operationId": "logs", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "follow", "in": "query", "description": "Keep the stream open (up to 30 minutes).", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "tail_lines", "in": "query", "description": "Last N lines (default 500, max 5000).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "since_seconds", "in": "query", "description": "Only lines from the last S seconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "previous", "in": "query", "description": "The previous container's logs (after a crash).", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "redirect", "in": "query", "description": "Answer `307` to the stream URL instead of JSON.", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsUrlDto" } } } }, "307": { "description": "`redirect=true`: to the stream" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not placed on a cell yet / being deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit" }, "503": { "description": "No key for the cell", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/metrics": { "get": { "tags": [ "instances" ], "summary": "Hourly resource series for one instance from metering.", "operationId": "metrics", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "`1h`, `24h` (default) or `7d`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "metric", "in": "query", "description": "One of `cpu`, `storage`, `egress`, `connections`; all when absent.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Metering is not configured or unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/migrations": { "get": { "tags": [ "migrations" ], "summary": "Migration history for an instance, newest first.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_MigrationDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "migrations" ], "summary": "Start a migration into an instance. `upload` sources get a pre-signed PUT URL;\n`connection_string` sources hand the URL to the provisioner through a 24 h secret row\n(it is never stored on the migration). At most one migration runs per instance.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Target instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMigrationRequest" } } }, "required": true }, "responses": { "201": { "description": "Accepted; status is `pending`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/migrations/{migration_id}": { "get": { "tags": [ "migrations" ], "summary": "Status, progress, preflight report and verification of one migration.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "migration_id", "in": "path", "description": "Migration id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/migrations/{migration_id}/actions/cancel": { "post": { "tags": [ "migrations" ], "summary": "Cancel a migration that has not finished. The cell stops the job and deletes the\nsource secret; partially restored data stays on the target.", "operationId": "cancel", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "migration_id", "in": "path", "description": "Migration id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/migrations/{migration_id}/actions/cutover": { "post": { "tags": [ "migrations" ], "summary": "Stop continuous sync and reset sequences (`copy_and_sync` migrations that are\n`ready_for_cutover` or `syncing`).", "operationId": "cutover", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "migration_id", "in": "path", "description": "Migration id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Cutover requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/network": { "get": { "tags": [ "network" ], "summary": "Allow-list, mTLS and custom domain of an instance.", "operationId": "get_network", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "put": { "tags": [ "network" ], "summary": "Replace the allow-list and/or the client CA bundle (mTLS). Requires an MFA session.", "operationId": "put_network", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNetworkRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/pitr-window": { "get": { "tags": [ "backups" ], "summary": "The PITR window for an instance: engine support, plan days and the restorable range.", "operationId": "pitr_window", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PitrWindowDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/restores": { "get": { "tags": [ "backups" ], "summary": "Restores from or into an instance, newest first.", "operationId": "list_restores", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_RestoreDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/instances/{instance_id}/restores/{restore_id}": { "get": { "tags": [ "backups" ], "summary": "One restore from or into the instance, with the live progress of an in-place\nrestore (stage, bytes, ETA, when each stage was reached).", "operationId": "get_restore", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Instance id", "required": true, "schema": { "type": "string" } }, { "name": "restore_id", "in": "path", "description": "Restore id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/invites": { "get": { "tags": [ "members" ], "summary": "Pending invites.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_InviteDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "members" ], "summary": "Invite someone by email. Counts pending invites against the seat quota.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteDto" } } } }, "402": { "description": "seat_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/invites/{invite_id}": { "delete": { "tags": [ "members" ], "summary": "Revoke a pending invite.", "operationId": "revoke", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "invite_id", "in": "path", "description": "Invite id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/invoices": { "get": { "tags": [ "billing" ], "summary": "Finalised invoices (from billing) with hosted and PDF links.", "operationId": "invoices", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Billing is not configured or unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/me/permissions": { "get": { "tags": [ "roles" ], "summary": "The caller's effective org and team permissions (org role + custom roles + team\nroles), for portal gating.", "operationId": "my_permissions", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissionsDto" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/members": { "get": { "tags": [ "members" ], "summary": "List members with their role and MFA status, plus the seat summary.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembersResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/members/{user_id}": { "delete": { "tags": [ "members" ], "summary": "Remove a member (or leave the org yourself). The last owner cannot be removed; only\nowners remove owners.", "operationId": "remove", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "User id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "patch": { "tags": [ "members" ], "summary": "Change a member's org role. The new role may not exceed the caller's; only owners\nchange owners; the last owner cannot be demoted. Moving an auditor into a seat is\nsubject to the seat limit.", "operationId": "update_role", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "User id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberDto" } } } }, "402": { "description": "seat_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/metrics": { "get": { "tags": [ "observability" ], "summary": "Prometheus exposition for the org's instances (API key with `usage:read`).", "operationId": "metrics", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Prometheus text exposition 0.0.4", "content": { "text/plain": {} } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/migrations": { "get": { "tags": [ "migrations" ], "summary": "Every migration in the org (all target instances), newest first. Team-scoped\nmembers see migrations into their teams' instances.", "operationId": "list_org", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "description": "Only migrations in this status (`preflight`, `copying`, `completed`, ...).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_MigrationDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/permissions": { "get": { "tags": [ "roles" ], "summary": "The permission catalogue, grouped by area with human labels.", "operationId": "permissions", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionCatalogueDto" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/predefined-roles": { "get": { "tags": [ "roles" ], "summary": "Predefined roles with their default and effective (org-edited) permission sets.", "operationId": "list_predefined", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredefinedRolesDto" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/predefined-roles/{role}": { "patch": { "tags": [ "roles" ], "summary": "Replace a predefined role's permission set for this org (Team and Enterprise). Every\nrole except `owner` is editable; `org:read` is always kept and `org:delete` cannot be\ndelegated. The caller needs `members:manage`, cannot add permissions they do not hold\nand cannot remove `members:manage` from their own role. Applies to members and API\nkeys of that role immediately (a key is its role ∩ its scopes).", "operationId": "update_predefined", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "description": "admin, developer, viewer, billing or auditor", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRolePermissionsRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredefinedRoleDto" } } } }, "402": { "description": "Team and Enterprise plans only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing members:manage, or granting beyond the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Would remove the caller's own members:manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/predefined-roles/{role}/actions/reset": { "post": { "tags": [ "roles" ], "summary": "Reset a predefined role to the default permission set.", "operationId": "reset_predefined", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "role", "in": "path", "description": "admin, developer, viewer, billing or auditor", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredefinedRoleDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/programmes/applications": { "get": { "tags": [ "growth" ], "summary": "The org's programme applications and their review status.", "operationId": "list_programme_applications", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProgrammeApplicationDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "growth" ], "summary": "Apply for the startup or open-source credits programme (reviewed by staff).", "operationId": "apply_programme", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammeApplicationRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgrammeApplicationDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/project-roles": { "get": { "tags": [ "roles" ], "summary": "Project role assignments in the org. Callers without org-wide `projects:read` see\nonly their own assignments.", "operationId": "list_project_roles", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "query", "description": "Only this member's assignments.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectRoleAssignmentDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/projects": { "get": { "tags": [ "projects" ], "summary": "List projects.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_ProjectDto" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "projects" ], "summary": "Create a project.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/projects/{project_id}": { "get": { "tags": [ "projects" ], "summary": "Get a project.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "projects" ], "summary": "Delete an empty project.", "operationId": "remove", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Project still has instances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "patch": { "tags": [ "projects" ], "summary": "Rename a project or change its slug.", "operationId": "update", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/projects/{project_id}/instances": { "get": { "tags": [ "instances" ], "summary": "List instances in a project.", "operationId": "list_in_project", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_InstanceDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "instances" ], "summary": "Create an instance. Validates engine, version, size, region and placement against the\ncatalogue and the org's entitled plan (billing, falling back to the org row);\n`secure` placement requires a signed BAA. Team controls (docs/18 §4) apply: allowed\nengines / regions / placements, max size and team quota (422), then the team's\napproval policy and monthly budget — a request above them becomes an approval\nrequest (`202`, `approval.requested.v1`) instead of an instance. Otherwise the row is\nwritten with `status=requested` and `instance.requested.v1` is enqueued in the same\ntransaction (outbox, ADR-0007).", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInstanceRequest" } } }, "required": true }, "responses": { "201": { "description": "Accepted; status is `requested`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceDto" } } } }, "202": { "description": "Needs a team lead's approval (`approval_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequiredDto" } } } }, "402": { "description": "Billing froze the org (`billing_frozen`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid request (`validation`), or the engine is not orderable yet (`engine-not-available`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/projects/{project_id}/members": { "get": { "tags": [ "roles" ], "summary": "Members with a role on this project.", "operationId": "list_project_members", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectRoleAssignmentDto" } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/projects/{project_id}/members/{user_id}": { "put": { "tags": [ "roles" ], "summary": "Give a member a role on one project (Team and Enterprise): `admin`, `developer` or\n`viewer` (Read-only). The role carries its effective permissions in this org,\nnarrowed to project permissions. Needs `members:manage`; the caller must hold every\npermission the project role carries.", "operationId": "put_project_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "Member user id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutProjectRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRoleAssignmentDto" } } } }, "402": { "description": "Team and Enterprise plans only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "roles" ], "summary": "Remove a member's role on a project. Allowed on every plan so a downgraded org can\nstill clean up.", "operationId": "remove_project_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "project_id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "Member user id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/referrals": { "get": { "tags": [ "growth" ], "summary": "The org's referral code and credits earned.", "operationId": "get_referrals", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSummaryDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "growth" ], "summary": "Create (or return) the org's referral code.", "operationId": "create_referral", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSummaryDto" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSummaryDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/roles": { "get": { "tags": [ "roles" ], "summary": "List custom roles.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomRoleDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "roles" ], "summary": "Create a custom role. Its permissions must be a subset of the creator's.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomRoleRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomRoleDto" } } } }, "402": { "description": "Enterprise only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Exceeds the creator's permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/roles/{role_id}": { "delete": { "tags": [ "roles" ], "summary": "Delete a custom role and its assignments.", "operationId": "remove", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "Custom role id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/roles/{role_id}/assignments": { "get": { "tags": [ "roles" ], "summary": "Assignments of a custom role.", "operationId": "list_assignments", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "Custom role id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssignmentDto" } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "roles" ], "summary": "Assign a custom role to an org member at org scope, or at one team's scope (team\npermissions only). The assigner must hold every permission of the role there.", "operationId": "assign", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "Custom role id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssignmentRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/roles/{role_id}/assignments/{assignment_id}": { "delete": { "tags": [ "roles" ], "summary": "Remove an assignment.", "operationId": "unassign", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "Custom role id", "required": true, "schema": { "type": "string" } }, { "name": "assignment_id", "in": "path", "description": "Assignment id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/service-accounts": { "get": { "tags": [ "service-accounts" ], "summary": "List service accounts (disabled ones included, with `disabled_at`).", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_ServiceAccountDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "service-accounts" ], "summary": "Create a service account and its first key (the secret is returned once).", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedServiceAccountDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/service-accounts/{service_account_id}": { "get": { "tags": [ "service-accounts" ], "summary": "Get one service account.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "description": "Service account id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/service-accounts/{service_account_id}/actions/disable": { "post": { "tags": [ "service-accounts" ], "summary": "Disable a service account: every key is revoked immediately.", "operationId": "disable", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "description": "Service account id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/service-accounts/{service_account_id}/keys": { "post": { "tags": [ "service-accounts" ], "summary": "Mint an additional key for the account (rotation). Inherits the account's role.", "operationId": "create_key", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "description": "Service account id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKeyDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Account disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/spending-cap": { "put": { "tags": [ "billing" ], "summary": "Set the org's monthly spending cap. New instances and resizes that would take the\nmonth-to-date spend plus their monthly estimate over the cap are refused (422\n`spending_cap`). Needs `billing:manage`.", "operationId": "put_spending_cap", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendingCapRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/connections": { "get": { "tags": [ "sso" ], "summary": "SSO connections of the org.", "operationId": "list_connections", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SsoConnectionDto" } } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "sso" ], "summary": "Add an OIDC or SAML connection. OIDC connections are active at once (rendered into\nthe Kratos provider overlay); SAML connections are registered with the SAML bridge\nand stay `pending` (with `last_error`) until that succeeds.", "operationId": "create_connection", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSsoConnectionRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/connections/{connection_id}": { "get": { "tags": [ "sso" ], "summary": "One connection.", "operationId": "get_connection", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "description": "Connection id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "sso" ], "summary": "Remove a connection (and its SAML bridge registration). Domains enforcing it fall\nback to the org's other active connections.", "operationId": "delete_connection", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "description": "Connection id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] }, "patch": { "tags": [ "sso" ], "summary": "Rename, enable/disable, rotate OIDC settings or change the default role.", "operationId": "update_connection", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "connection_id", "in": "path", "description": "Connection id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoConnectionRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/domains": { "get": { "tags": [ "sso" ], "summary": "Claimed and verified email domains.", "operationId": "list_domains", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SsoDomainDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "sso" ], "summary": "Claim a domain; the answer names the TXT record that proves ownership.", "operationId": "create_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSsoDomainRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoDomainDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/domains/{domain_id}": { "delete": { "tags": [ "sso" ], "summary": "Release a domain (ends enforcement for it).", "operationId": "delete_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "description": "Domain id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] }, "patch": { "tags": [ "sso" ], "summary": "Turn SSO enforcement on or off (verified domains with an active connection only).", "operationId": "update_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "description": "Domain id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoDomainRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoDomainDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/domains/{domain_id}/actions/verify": { "post": { "tags": [ "sso" ], "summary": "Look up the TXT record and mark the domain verified. A domain is verified by at\nmost one organization.", "operationId": "verify_domain", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "description": "Domain id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checked; see `status` and `last_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoDomainDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/scim-groups": { "get": { "tags": [ "sso" ], "summary": "Groups pushed by the IdP and what they map to.", "operationId": "list_scim_groups", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroupMappingDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/scim-groups/{group_id}": { "patch": { "tags": [ "sso" ], "summary": "Set the team role and / or org role a group grants; members are updated at once.", "operationId": "update_scim_group", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "SCIM group id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScimGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroupMappingDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/scim-tokens": { "get": { "tags": [ "sso" ], "summary": "Active SCIM tokens (never the secret).", "operationId": "list_scim_tokens", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScimTokenDto" } } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "sso" ], "summary": "Issue a SCIM bearer token for the IdP (shown once; stored as SHA-256).", "operationId": "create_scim_token", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScimTokenRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedScimTokenDto" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/sso/scim-tokens/{token_id}": { "delete": { "tags": [ "sso" ], "summary": "Revoke a SCIM token.", "operationId": "revoke_scim_token", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "token_id", "in": "path", "description": "Token id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/support-grants": { "get": { "tags": [ "support" ], "summary": "List grants (active and past). Auditors may read.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_SupportGrantDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "support" ], "summary": "Issue a support grant.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSupportGrantRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportGrantDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/support-grants/{grant_id}": { "delete": { "tags": [ "support" ], "summary": "Revoke a grant immediately.", "operationId": "revoke", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "grant_id", "in": "path", "description": "Grant id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/teams": { "get": { "tags": [ "teams" ], "summary": "List teams. The default \"Everyone\" team is created on first use.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_TeamDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "teams" ], "summary": "Create a team (org admin). Plan limits: Free/Solo 1, Team and Enterprise unlimited.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDto" } } } }, "402": { "description": "plan_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/teams/{team_id}": { "get": { "tags": [ "teams" ], "summary": "Get a team.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "teams" ], "summary": "Delete an empty team (org admin). The default team cannot be deleted; move projects\naway first.", "operationId": "remove", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "patch": { "tags": [ "teams" ], "summary": "Update a team. Org admins change everything; a team lead may rename the team and set\nits cost centre. Quota, budget, approval policy and allowed lists are org-admin only.", "operationId": "update", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/teams/{team_id}/budget": { "get": { "tags": [ "teams" ], "summary": "Month-to-date spend against the team budget, plus live instance / storage counts.", "operationId": "budget", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamBudgetDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/teams/{team_id}/members": { "get": { "tags": [ "teams" ], "summary": "Team members and their team roles.", "operationId": "list_members", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMemberDto" } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/teams/{team_id}/members/{user_id}": { "put": { "tags": [ "teams" ], "summary": "Add an org member to the team or change their team role. Org admins, or the team's\nlead within their own role.", "operationId": "put_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "User id (must be an org member)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutTeamMemberRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "teams" ], "summary": "Remove a user from the team.", "operationId": "remove_member", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "team_id", "in": "path", "description": "Team id", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "User id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/usage": { "get": { "tags": [ "usage" ], "summary": "Usage grouped by team, cost centre, instance or metric (list-price costs).", "operationId": "usage", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "description": "`team` (default), `cost_centre`, `instance`, `metric` or `day` (UTC calendar\nday of the hourly rollups; each group also breaks down by instance).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "description": "Start (RFC 3339); defaults to the start of the current month.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "description": "End (RFC 3339, exclusive); defaults to now.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "List webhook endpoints.", "operationId": "list", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_WebhookDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "post": { "tags": [ "webhooks" ], "summary": "Register a webhook endpoint. The signing `secret` is returned exactly once.", "operationId": "create", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/webhooks/{webhook_id}": { "get": { "tags": [ "webhooks" ], "summary": "Get one webhook endpoint.", "operationId": "get", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "delete": { "tags": [ "webhooks" ], "summary": "Delete a webhook endpoint. Pending deliveries are dropped.", "operationId": "remove", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] }, "patch": { "tags": [ "webhooks" ], "summary": "Update URL, description, filters or enabled state.", "operationId": "update", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/webhooks/{webhook_id}/actions/rotate-secret": { "post": { "tags": [ "webhooks" ], "summary": "Rotate the signing secret. The new secret is returned once; deliveries after this\ncall are signed with it.", "operationId": "rotate_secret", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/orgs/{org_id}/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "webhooks" ], "summary": "Delivery log for one endpoint, newest first.", "operationId": "deliveries", "parameters": [ { "name": "org_id", "in": "path", "description": "Organization id", "required": true, "schema": { "type": "string" } }, { "name": "webhook_id", "in": "path", "description": "Webhook id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1..=200 (default 50).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_WebhookDeliveryDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "dev_user": [] } ] } }, "/v1/plans": { "get": { "tags": [ "catalogue" ], "summary": "List plans with quotas and allowed placements.", "operationId": "plans", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlanDto" } } } } } } } }, "/v1/regions": { "get": { "tags": [ "catalogue" ], "summary": "List regions.", "operationId": "regions", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RegionDto" } } } } } } } }, "/v1/sizes": { "get": { "tags": [ "catalogue" ], "summary": "List instance sizes.", "operationId": "sizes", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SizeDto" } } } } } } } }, "/v1/sso/discover": { "get": { "tags": [ "sso" ], "summary": "Which SSO provider (if any) an email should sign in with. Unauthenticated,\nrate limited per IP; never reveals the org.", "operationId": "discover", "parameters": [ { "name": "email", "in": "query", "description": "The email the user typed on the login page.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoDiscoveryDto" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "AddDomainRequest": { "type": "object", "required": [ "hostname" ], "properties": { "hostname": { "type": "string", "example": "db.acme.com" } } }, "AddSubsidiaryRequest": { "type": "object", "required": [ "org_id" ], "properties": { "org_id": { "type": "string", "description": "An org the caller owns." } } }, "AlertDto": { "type": "object", "required": [ "id", "kind", "severity", "title", "body", "created_at" ], "properties": { "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "instance_id": { "type": [ "string", "null" ] }, "kind": { "type": "string", "description": "`quota_threshold`, `quota_hard_limit`, `backup_failed`, `instance_failed`, `security`." }, "severity": { "type": "string", "description": "`info`, `warning` or `critical`." }, "title": { "type": "string" } } }, "AlertListDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AlertDto" } } } }, "ApiKeyDto": { "type": "object", "required": [ "id", "org_id", "name", "prefix", "role", "scopes", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "prefix": { "type": "string", "description": "First characters of the key, for identification." }, "role": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "service_account_id": { "type": [ "string", "null" ], "description": "Set for service-account keys." }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while an automatic security response suspends the key (docs/20 §3);\n`POST .../api-keys/{key_id}/actions/unsuspend` lifts it." }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApprovalDecisionDto": { "type": "object", "required": [ "approval" ], "properties": { "approval": { "$ref": "#/components/schemas/ApprovalDto" }, "instance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InstanceDto", "description": "The instance the approval created (`status=requested`)." } ] } } }, "ApprovalDto": { "type": "object", "required": [ "id", "org_id", "team_id", "project_id", "kind", "requester_id", "requester_type", "request", "reasons", "estimate", "status", "expires_at", "created_at" ], "properties": { "approver_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "estimate": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "instance_id": { "type": [ "string", "null" ], "description": "Instance created by the approval." }, "kind": { "type": "string", "description": "`instance.create`." }, "org_id": { "type": "string" }, "project_id": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "`size_above_threshold`, `placement_requires_approval`, `engine_requires_approval`,\n`over_budget`, `policy_requires_all`." }, "request": { "type": "object", "description": "The original create request." }, "requester_id": { "type": "string" }, "requester_type": { "type": "string" }, "status": { "type": "string", "description": "`pending`, `approved`, `denied` or `expired`." }, "team_id": { "type": "string" } } }, "ApprovalPolicy": { "type": "object", "description": "When a creation needs a lead's approval instead of happening (docs/18 §4).", "properties": { "engines": { "type": "array", "items": { "type": "string" }, "description": "Engines that need approval." }, "placements": { "type": "array", "items": { "type": "string" }, "description": "Placements that need approval (e.g. `secure`)." }, "require_for_all": { "type": "boolean", "description": "Every creation in the team needs approval." }, "sizes_above": { "type": [ "string", "null" ], "description": "Sizes strictly above this one need approval (e.g. `m2` → m4 and up).", "example": "m2" } } }, "ApprovalRequiredDto": { "type": "object", "description": "`202` body of `POST .../instances` when the creation needs a lead's approval.", "required": [ "status", "approval" ], "properties": { "approval": { "$ref": "#/components/schemas/ApprovalDto" }, "budget": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BudgetCheck" } ] }, "status": { "type": "string", "description": "Always `approval_required`." } } }, "AssignmentDto": { "type": "object", "required": [ "id", "custom_role_id", "user_id", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "custom_role_id": { "type": "string" }, "id": { "type": "string" }, "team_id": { "type": [ "string", "null" ] }, "user_id": { "type": "string" } } }, "AuditItemDto": { "type": "object", "description": "One audit entry (as the audit service returns it).", "required": [ "event_id", "ts", "actor", "action", "target", "outcome" ], "properties": { "action": { "type": "string" }, "actor": { "description": "`{type, id}`; type is `user`, `api_key`, `staff` or `system`." }, "diff": {}, "event_id": { "type": "string" }, "hash": { "type": [ "string", "null" ], "description": "Chain hash (audit service only)." }, "ip": { "type": [ "string", "null" ] }, "org_id": { "type": [ "string", "null" ] }, "outcome": { "type": "string" }, "request_id": { "type": [ "string", "null" ] }, "target": { "description": "`{type, id}`." }, "ts": { "type": "string" }, "user_agent": { "type": [ "string", "null" ] } } }, "AuditPageDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditItemDto" } }, "next_cursor": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "`audit` (hash-chained store) or `local_outbox` (dev fallback)." } } }, "BaaStatusDto": { "type": "object", "required": [ "signed", "current" ], "properties": { "current": { "type": "boolean", "description": "The signed version is the current one." }, "legal_entity": { "type": [ "string", "null" ] }, "signatory_name": { "type": [ "string", "null" ] }, "signatory_title": { "type": [ "string", "null" ] }, "signed": { "type": "boolean" }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "signed_by": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] } } }, "BackupCapsDto": { "type": "object", "description": "Plan ceiling for the backup knobs (docs/09 §2).", "required": [ "plan", "policy", "max_frequency", "max_retention_days", "pitr_days", "cross_region", "immutable", "retained_after_delete_days" ], "properties": { "cross_region": { "type": "boolean" }, "immutable": { "type": "boolean" }, "manual_max": { "type": [ "integer", "null" ], "format": "int64", "description": "Absent = unlimited.", "minimum": 0 }, "max_frequency": { "type": "string", "description": "`none`, `daily`, `hourly`." }, "max_retention_days": { "type": "integer", "format": "int32", "minimum": 0 }, "pitr_days": { "type": "integer", "format": "int32", "minimum": 0 }, "plan": { "type": "string" }, "policy": { "type": "string" }, "retained_after_delete_days": { "type": "integer", "format": "int32", "minimum": 0 } } }, "BackupDto": { "type": "object", "required": [ "id", "instance_id", "kind", "engine", "status", "size_bytes", "protected", "created_at" ], "properties": { "checksum": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "cross_region_location": { "type": [ "string", "null" ] }, "engine": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "immutable_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Object Lock retain-until; the backup cannot be deleted before this." }, "instance_id": { "type": "string" }, "kind": { "type": "string", "description": "`scheduled`, `manual`, `pre_change`." }, "label": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ], "description": "`s3://bucket/org_/inst_//`" }, "parent_backup_id": { "type": [ "string", "null" ] }, "protected": { "type": "boolean", "description": "The newest successful backup of the instance is never pruned." }, "size_bytes": { "type": "integer", "format": "int64" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`requested`, `running`, `completed`, `failed`, `pending_erasure`." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_ok": { "type": [ "boolean", "null" ] } } }, "BackupHealthDto": { "type": "object", "required": [ "org_id", "plan", "generated_at", "status", "instances" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceBackupHealthDto" } }, "org_id": { "type": "string" }, "plan": { "type": "string" }, "status": { "type": "string", "description": "`ok`, `warning`, `critical`." } } }, "BackupOverridesDto": { "type": "object", "description": "Customer overrides (each optional = plan default).", "properties": { "cross_region_target": { "type": [ "string", "null" ], "description": "Team+ only: region id for the copy." }, "frequency": { "type": [ "string", "null" ], "description": "`daily` or `hourly` (never above the plan)." }, "pitr_enabled": { "type": [ "boolean", "null" ], "description": "Plans whose backup policy includes PITR (Enterprise, or the PITR add-on)." }, "retention_days": { "type": [ "integer", "null" ], "format": "int32", "description": "`1..=max_retention_days`.", "minimum": 0 }, "schedule_time_utc": { "type": [ "string", "null" ], "description": "`HH:MM` UTC.", "example": "03:00" } } }, "BackupRequestedDto": { "type": "object", "description": "Returned on `POST .../backups`: the backup service creates the row when it consumes\n`backup.requested.v1`; poll `GET .../backups/{backup_id}`.", "required": [ "id", "instance_id", "kind", "status", "requested_at", "manual_used" ], "properties": { "id": { "type": "string" }, "instance_id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "manual_allowed": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "manual_used": { "type": "integer", "format": "int64", "description": "Manual snapshots used / allowed on the plan (`allowed` absent = unlimited)." }, "requested_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "Always `requested`." } } }, "BackupSettingsDto": { "type": "object", "required": [ "instance_id", "caps", "overrides", "effective" ], "properties": { "caps": { "$ref": "#/components/schemas/BackupCapsDto" }, "effective": { "$ref": "#/components/schemas/EffectiveScheduleDto" }, "instance_id": { "type": "string" }, "overrides": { "$ref": "#/components/schemas/BackupOverridesDto" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BudgetCheck": { "type": "object", "description": "Budget position of a team for an admission decision.", "required": [ "budget_cents", "mtd_cents", "request_monthly_cents", "source" ], "properties": { "budget_cents": { "type": "integer", "format": "int64" }, "mtd_cents": { "type": "number", "format": "double", "description": "Month-to-date spend (list price)." }, "request_monthly_cents": { "type": "number", "format": "double", "description": "Estimated monthly cost of the request." }, "source": { "type": "string", "description": "`metering` or `estimate` (control-plane shapes when metering is unavailable)." } } }, "CapacityDto": { "type": "object", "required": [ "instance_id", "storage_provisioned_gb", "storage_used_gb", "storage_used_ratio", "growth_gb_per_day", "connection_peak", "connection_limit", "memory_pressure", "samples" ], "properties": { "connection_limit": { "type": "integer", "format": "int32", "minimum": 0 }, "connection_peak": { "type": "integer", "format": "int32", "minimum": 0 }, "days_until_full": { "type": [ "number", "null" ], "format": "double", "description": "`null` when the instance is not growing." }, "growth_gb_per_day": { "type": "number", "format": "double", "description": "Linear fit over 7 days; negative when shrinking." }, "instance_id": { "type": "string" }, "measured_at": { "type": [ "string", "null" ], "format": "date-time" }, "memory_pressure": { "type": "number", "format": "double", "description": "Working set / memory limit (0..1+)." }, "samples": { "type": "integer", "format": "int32", "minimum": 0 }, "storage_provisioned_gb": { "type": "number", "format": "double" }, "storage_used_gb": { "type": "number", "format": "double" }, "storage_used_ratio": { "type": "number", "format": "double", "description": "Used / provisioned, 0..1." } } }, "CloseOrgRequest": { "type": "object", "description": "`POST /v1/orgs/{org_id}/actions/close`.", "required": [ "confirm" ], "properties": { "confirm": { "type": "string", "description": "Must equal the org slug.", "example": "acme-health" }, "erase_everything": { "type": "boolean", "description": "Erase every instance immediately (incl. the last backup) instead of keeping the\nplan's retention window (docs/11 §9)." } } }, "CloseOrgResponse": { "type": "object", "required": [ "org", "instances", "erase_everything" ], "properties": { "erase_everything": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "string" }, "description": "Instances whose deletion / erasure was requested." }, "org": { "$ref": "#/components/schemas/OrgDto" } } }, "ComplianceDto": { "type": "object", "required": [ "org_id", "baa", "current_baa_version", "baa_document", "mfa_required", "secure_placement_available", "secure_placement_plan_eligible" ], "properties": { "baa": { "$ref": "#/components/schemas/BaaStatusDto" }, "baa_document": { "type": "string", "description": "Where the current BAA text lives." }, "current_baa_version": { "type": "string", "description": "Current BAA document version customers must accept." }, "mfa_required": { "type": "boolean" }, "org_id": { "type": "string" }, "secure_placement_available": { "type": "boolean", "description": "`secure` placement is available (plan allows it and the BAA is signed)." }, "secure_placement_plan_eligible": { "type": "boolean", "description": "The plan allows secure placement at all (Team+)." } } }, "ConsoleSessionDto": { "type": "object", "required": [ "console_url", "token", "expires_at", "engine", "read_only", "session_id" ], "properties": { "ai_url": { "type": [ "string", "null" ], "description": "AI explain endpoint (`POST`, same token); `null` when AI is off for the session." }, "console_url": { "type": "string", "description": "Base URL of the console proxy for this instance (`…/v1/console/inst-…`); send\n`Authorization: Bearer `." }, "engine": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "read_only": { "type": "boolean" }, "session_id": { "type": "string", "description": "Token id (`jti`) for correlation with the proxy's audit trail." }, "token": { "type": "string" } } }, "CostLineDto": { "type": "object", "required": [ "team_id", "metric", "unit", "quantity", "unit_price_cents", "cost_cents" ], "properties": { "cost_centre": { "type": [ "string", "null" ] }, "cost_cents": { "type": "number", "format": "double" }, "metric": { "type": "string" }, "quantity": { "type": "number", "format": "double" }, "team_id": { "type": "string" }, "team_name": { "type": [ "string", "null" ] }, "unit": { "type": "string" }, "unit_price_cents": { "type": "number", "format": "double" } } }, "CostReportDto": { "type": "object", "required": [ "org_id", "month", "currency", "lines", "team_totals", "total_cost_cents", "source", "note" ], "properties": { "currency": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CostLineDto" } }, "month": { "type": "string" }, "note": { "type": "string", "description": "Allocation is at list price; plan allowances and discounts are applied on the\norg invoice, not per team." }, "org_id": { "type": "string" }, "source": { "type": "string" }, "team_totals": { "type": "object", "description": "Per team (team id → cents).", "additionalProperties": { "type": "number", "format": "double" }, "propertyNames": { "type": "string" } }, "total_cost_cents": { "type": "number", "format": "double" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string", "example": "ci-deploy" }, "role": { "type": [ "string", "null" ], "description": "Role the key acts as; may not exceed the creator's role. Defaults to `developer`.", "example": "developer" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Scopes such as `instances:read`, `backups:*` or `*` (default).", "example": [ "instances:read", "instances:write" ] } } }, "CreateAssignmentRequest": { "type": "object", "required": [ "user_id" ], "properties": { "team_id": { "type": [ "string", "null" ], "description": "Assign within one team (team permissions only); omitted = org scope." }, "user_id": { "type": "string" } } }, "CreateBackupRequest": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "description": "Free-text label shown in the portal (max 120 chars).", "example": "before schema migration" } } }, "CreateBranchRequest": { "type": "object", "required": [ "name" ], "properties": { "git_branch": { "type": [ "string", "null" ], "description": "Git branch a preview integration (Vercel / GitHub) creates this for.", "example": "feature/login" }, "name": { "type": "string", "description": "Branch instance name (DNS label, unique in the project).", "example": "feature-login" }, "source": { "type": [ "string", "null" ], "description": "What to branch from: `current` (default, the source's state now)." } } }, "CreateConsoleSessionRequest": { "type": "object", "properties": { "read_only": { "type": [ "boolean", "null" ], "description": "Ask for a read-only session. Callers without `credentials:reveal` in the\ninstance's team always get one." } } }, "CreateCustomRoleRequest": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string", "example": "DBA on-call" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Org permissions (`instances:read`, `backups:restore`, ...)." }, "team_permissions": { "type": "array", "items": { "type": "string" }, "description": "Team permissions (`instances:operate`, `credentials:rotate`, ...)." } } }, "CreateEnterpriseRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Group" } } }, "CreateInstanceRequest": { "type": "object", "required": [ "engine", "size" ], "properties": { "allow_cidrs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Client allow-list; defaults to everywhere." }, "cost_centre": { "type": [ "string", "null" ], "description": "Cost-centre tag for chargeback; defaults to the team's cost centre.", "example": "CC-4711" }, "engine": { "type": "string", "description": "Engine id from `GET /v1/engines`.", "example": "postgres" }, "engine_version": { "type": [ "string", "null" ], "description": "Engine version; defaults to the newest supported.", "example": "17" }, "ha": { "type": "boolean" }, "name": { "type": [ "string", "null" ], "description": "DNS-safe name, unique within the project; defaults to `-`.", "example": "orders-db" }, "placement": { "type": [ "string", "null" ], "description": "`shared` (default), `dedicated-node` or `secure` (needs a signed BAA).", "example": "shared" }, "pooler_enabled": { "type": "boolean" }, "region": { "type": [ "string", "null" ], "description": "Region id; defaults to the org's `region_default`.", "example": "us-east" }, "replicas": { "type": "integer", "format": "int32", "description": "Read replicas, engine and plan permitting.", "minimum": 0 }, "size": { "type": "string", "description": "Size id from `GET /v1/sizes`.", "example": "s1" }, "storage_gb": { "type": [ "integer", "null" ], "format": "int32", "description": "Provisioned storage in GB; defaults to 10 (1 on free).", "minimum": 0 }, "tags": { "type": [ "object", "null" ], "description": "Free-form tags (`key -> value`, at most 20) carried into usage and cost reports.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "CreateInviteRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "dev@acme.example" }, "role": { "type": [ "string", "null" ], "description": "Org role; defaults to `developer`.", "example": "developer" } } }, "CreateMigrationRequest": { "type": "object", "required": [ "source" ], "properties": { "mode": { "type": [ "string", "null" ], "description": "`copy` (default) or `copy_and_sync` (Postgres / MySQL connection sources).", "example": "copy" }, "options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MigrationOptionsRequest" } ] }, "source": { "$ref": "#/components/schemas/MigrationSourceRequest" } } }, "CreateOrgRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name.", "example": "Acme Health" }, "referral_code": { "type": [ "string", "null" ], "description": "Referral or promo code: credits the new org (and the referrer) through billing.", "example": "ACME-7Q2K" }, "region_default": { "type": [ "string", "null" ], "description": "Default region for new instances.", "example": "us-east" }, "slug": { "type": [ "string", "null" ], "description": "URL slug; derived from `name` when omitted.", "example": "acme-health" } } }, "CreateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Production" }, "slug": { "type": [ "string", "null" ], "example": "prod" }, "team_id": { "type": [ "string", "null" ], "description": "Owning team; defaults to the org's default team (\"Everyone\").", "example": "team_01j9..." } } }, "CreateScimTokenRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Okta SCIM" } } }, "CreateServiceAccountKeyRequest": { "type": "object", "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ], "example": "rotation-2026-10" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "CreateServiceAccountRequest": { "type": "object", "required": [ "name" ], "properties": { "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry of the first key." }, "name": { "type": "string", "example": "ci-deploy" }, "role": { "type": [ "string", "null" ], "description": "Role the account acts as; may not exceed the creator's role. Defaults to `developer`.", "example": "developer" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Scopes for the first key (default `*`)." } } }, "CreateSiemDeliveryRequest": { "type": "object", "required": [ "kind" ], "properties": { "from_now": { "type": "boolean", "description": "Only new events (default: from the start of the org's log)." }, "kind": { "type": "string", "description": "`webhook` (HTTPS POST of JSON batches, HMAC-signed with `secret`) or `s3`\n(NDJSON objects under `s3_bucket/s3_prefix`).", "example": "webhook" }, "s3_bucket": { "type": [ "string", "null" ] }, "s3_prefix": { "type": [ "string", "null" ] }, "secret": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "example": "https://siem.acme.io/databasezy" } } }, "CreateSsoConnectionRequest": { "type": "object", "required": [ "kind", "name" ], "properties": { "client_id": { "type": [ "string", "null" ], "description": "OIDC: client id and secret of the app registered at the IdP." }, "client_secret": { "type": [ "string", "null" ] }, "default_role": { "type": [ "string", "null" ], "description": "Role for members created through SSO / SCIM without a group mapping\n(`member` default; never `owner`)." }, "idp_metadata_url": { "type": [ "string", "null" ], "description": "SAML: IdP metadata URL (https) or the metadata XML." }, "idp_metadata_xml": { "type": [ "string", "null" ] }, "issuer_url": { "type": [ "string", "null" ], "description": "OIDC: issuer (discovery at `/.well-known/openid-configuration`).", "example": "https://acme.okta.com" }, "kind": { "type": "string", "description": "`oidc` or `saml`.", "example": "oidc" }, "name": { "type": "string", "example": "Acme Okta" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OIDC scopes (default `openid email profile`)." } } }, "CreateSsoDomainRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "acme.io" } } }, "CreateSupportGrantRequest": { "type": "object", "required": [ "scope", "staff_id" ], "properties": { "duration_hours": { "type": [ "integer", "null" ], "format": "int32", "description": "1..=72 hours (default 4).", "minimum": 0 }, "instance_id": { "type": [ "string", "null" ], "description": "Restrict to one instance; omitted = org metadata only." }, "reason": { "type": [ "string", "null" ] }, "scope": { "type": "string", "description": "`metadata`, `read_only` or `full`.", "example": "read_only" }, "staff_id": { "type": "string", "description": "The named staff member (staff id or email) the grant is issued to.", "example": "staff_ada" } } }, "CreateTeamRequest": { "type": "object", "required": [ "name" ], "properties": { "allowed_engines": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_placements": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_regions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "approval_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApprovalPolicy" } ] }, "budget_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Monthly budget in USD cents.", "example": 1000 }, "cost_centre": { "type": [ "string", "null" ], "example": "CC-4711" }, "name": { "type": "string", "example": "Platform" }, "quota": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TeamQuota" } ] }, "slug": { "type": [ "string", "null" ], "example": "platform" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "description": { "type": [ "string", "null" ] }, "events": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Event filters: `*` (default), `instance.*`, `instance.paused.v1`, `quota.*`, ...", "example": [ "instance.*", "quota.*" ] }, "url": { "type": "string", "description": "HTTPS URL (HTTP and private addresses are accepted outside production).", "example": "https://hooks.acme.example/databasezy" } } }, "CreatedApiKeyDto": { "allOf": [ { "$ref": "#/components/schemas/ApiKeyDto" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "The full secret key. Store it now." } } } ], "description": "Returned once, on creation. The `key` is never retrievable again." }, "CreatedScimTokenDto": { "allOf": [ { "$ref": "#/components/schemas/ScimTokenDto" }, { "type": "object", "required": [ "token", "scim_base_url" ], "properties": { "scim_base_url": { "type": "string", "description": "SCIM base URL to configure at the IdP." }, "token": { "type": "string", "description": "The bearer token for the IdP's SCIM app. Shown once." } } } ] }, "CreatedServiceAccountDto": { "type": "object", "description": "Returned once, on creation: the account and its first key (secret shown once).", "required": [ "service_account", "key" ], "properties": { "key": { "$ref": "#/components/schemas/CreatedApiKeyDto" }, "service_account": { "$ref": "#/components/schemas/ServiceAccountDto" } } }, "CreatedWebhookDto": { "allOf": [ { "$ref": "#/components/schemas/WebhookDto" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "HMAC-SHA256 key for `ZB-Signature` (`whsec_...`)." } } } ], "description": "Returned once, on creation: the signing `secret` is never shown again." }, "CreditGrantDto": { "type": "object", "required": [ "id", "amount_cents", "reason", "source", "status", "created_at" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "source": { "type": "string", "description": "`referral`, `referrer`, `promo`, `programme`." }, "status": { "type": "string", "description": "`queued` (waiting for billing), `applied`, `failed`." } } }, "CustomRoleDto": { "type": "object", "required": [ "id", "org_id", "name", "permissions", "team_permissions", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "team_permissions": { "type": "array", "items": { "type": "string" } } } }, "DecideApprovalRequest": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Required when denying.", "example": "Use m2 until the load test proves otherwise" } } }, "DomainDto": { "type": "object", "required": [ "id", "instance_id", "hostname", "cname_target", "status", "created_at" ], "properties": { "cname_target": { "type": "string", "description": "Point a CNAME record for `hostname` at this value." }, "created_at": { "type": "string", "format": "date-time" }, "hostname": { "type": "string" }, "id": { "type": "string" }, "instance_id": { "type": "string" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`pending`, `verified` or `failed`." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DomainListDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DomainDto" } } } }, "EffectivePermissionsDto": { "type": "object", "description": "The caller's effective permissions (portal gating).", "required": [ "org_role", "permissions", "teams", "all_teams" ], "properties": { "all_teams": { "type": "array", "items": { "type": "string" }, "description": "Team permissions held in every team." }, "org_role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "projects": { "type": "object", "description": "Project id → org permissions held there through a project-scoped role.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "teams": { "type": "object", "description": "Team id → team permissions held there (teams with a team-level grant only).", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } } } }, "EffectiveScheduleDto": { "type": "object", "description": "The schedule the cell runs (as last handed to the operator).", "required": [ "frequency", "schedule_time_utc", "retention_days", "pitr_days", "cross_region", "immutable", "applied" ], "properties": { "applied": { "type": "boolean", "description": "Whether the operator has been handed this schedule yet." }, "cron": { "type": [ "string", "null" ] }, "cross_region": { "type": "boolean" }, "cross_region_target": { "type": [ "string", "null" ] }, "frequency": { "type": "string" }, "immutable": { "type": "boolean" }, "pitr_days": { "type": "integer", "format": "int32", "minimum": 0 }, "retention_days": { "type": "integer", "format": "int32", "minimum": 0 }, "schedule_time_utc": { "type": "string" } } }, "EndpointDto": { "type": "object", "required": [ "host", "port" ], "properties": { "host": { "type": "string" }, "port": { "type": "integer", "format": "int32" } } }, "EngineAvailability": { "type": "string", "description": "Whether an engine can be ordered (ZB-276).", "enum": [ "available", "preview", "coming_soon" ] }, "EngineDto": { "type": "object", "required": [ "id", "name", "category", "family", "versions", "wire", "port", "free", "wave", "availability", "pitr", "pausable", "features", "license", "license_gate" ], "properties": { "availability": { "$ref": "#/components/schemas/EngineAvailability", "description": "`available` and `preview` engines can be ordered; `coming_soon` engines are\nlisted but creates are refused with `engine-not-available`." }, "category": { "type": "string" }, "default_version": { "type": [ "string", "null" ] }, "family": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "free": { "type": "boolean" }, "id": { "type": "string" }, "license": { "type": "string" }, "license_gate": { "type": "boolean" }, "name": { "type": "string" }, "pausable": { "type": "boolean" }, "pitr": { "type": "boolean" }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "versions": { "type": "array", "items": { "type": "string" }, "description": "Supported versions, newest first." }, "wave": { "type": "integer", "format": "int32", "description": "Roadmap wave (1 = MVP, 2 = Phase 2, 3 = Phase 4). Kept for compatibility; use\n`availability` to decide whether the engine can be ordered.", "minimum": 0 }, "wire": { "type": "string" } } }, "EnterpriseDto": { "type": "object", "required": [ "id", "name", "parent_org_id", "consolidated_invoicing", "policies", "sso", "subsidiaries", "created_at", "updated_at" ], "properties": { "committed_spend_cents": { "type": [ "integer", "null" ], "format": "int64" }, "consolidated_invoicing": { "type": "boolean" }, "contract_end": { "type": [ "string", "null" ], "format": "date-time" }, "contract_start": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string" }, "net_terms_days": { "type": [ "integer", "null" ], "format": "int32" }, "parent_org_id": { "type": "string" }, "po_number": { "type": [ "string", "null" ] }, "policies": { "type": "object" }, "sso": { "$ref": "#/components/schemas/SsoDto" }, "subsidiaries": { "type": "array", "items": { "$ref": "#/components/schemas/SubsidiaryDto" } }, "updated_at": { "type": "string", "format": "date-time" } } }, "EraseInstanceRequest": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "type": "string", "description": "Must equal the instance name.", "example": "orders-db" } } }, "FieldError": { "type": "object", "description": "One field-level validation failure.", "required": [ "field", "message" ], "properties": { "field": { "type": "string", "description": "JSON pointer-ish field name, e.g. `size` or `placement`." }, "message": { "type": "string" } } }, "Health": { "type": "object", "required": [ "status", "database", "events", "cache" ], "properties": { "cache": { "type": "string", "description": "`valkey` or `memory` (single-replica fallback)." }, "database": { "type": "string" }, "events": { "type": "string" }, "status": { "type": "string" } } }, "InstanceBackupHealthDto": { "type": "object", "required": [ "instance_id", "engine", "status", "failures_30d", "backups_retained", "stored_bytes", "retention_compliant", "cross_region", "cross_region_copies", "immutable" ], "properties": { "backups_retained": { "type": "integer", "format": "int64" }, "cron": { "type": [ "string", "null" ] }, "cross_region": { "type": "boolean" }, "cross_region_copies": { "type": "integer", "format": "int64" }, "engine": { "type": "string" }, "failures_30d": { "type": "integer", "format": "int64" }, "immutable": { "type": "boolean" }, "instance_id": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_successful_backup_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_verified_ok": { "type": [ "boolean", "null" ] }, "last_verified_restore_at": { "type": [ "string", "null" ], "format": "date-time" }, "oldest_retained_at": { "type": [ "string", "null" ], "format": "date-time" }, "pitr_days": { "type": [ "integer", "null" ], "format": "int32" }, "retention_compliant": { "type": "boolean", "description": "Retention is met when the oldest retained backup covers the window (or the\ninstance is younger than the window)." }, "retention_days": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "type": "string", "description": "`ok`, `warning`, `critical`, `none` (no schedule)." }, "stored_bytes": { "type": "integer", "format": "int64" } } }, "InstanceChangeDto": { "type": "object", "required": [ "id", "instance_id", "kind", "from_value", "to_value", "status", "requested_by", "created_at" ], "properties": { "approval_id": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "from_value": { "type": "string" }, "id": { "type": "string" }, "instance_id": { "type": "string" }, "kind": { "type": "string", "description": "`resize`, `storage_grow`, `version_upgrade` or `placement`." }, "message": { "type": [ "string", "null" ] }, "requested_by": { "type": "string" }, "status": { "type": "string", "description": "`requested`, `completed`, `failed` or `superseded`." }, "to_value": { "type": "string" } } }, "InstanceChangesDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceChangeDto" } } } }, "InstanceDto": { "type": "object", "required": [ "id", "org_id", "project_id", "name", "engine", "engine_version", "size", "region", "tier", "placement", "status", "desired_status", "storage_gb", "pooler_enabled", "replicas", "ha", "allow_cidrs", "endpoints", "tags", "created_at", "updated_at", "mtls" ], "properties": { "allow_cidrs": { "type": "array", "items": { "type": "string" } }, "branch_of": { "type": [ "string", "null" ], "description": "Source instance when this instance is a branch." }, "cost_centre": { "type": [ "string", "null" ], "description": "Cost-centre tag for chargeback." }, "created_at": { "type": "string", "format": "date-time" }, "custom_domain": { "type": [ "string", "null" ] }, "desired_status": { "type": "string", "description": "Customer intent: `running`, `paused`, `deleted` or `erased`." }, "endpoint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EndpointDto", "description": "Primary public endpoint: the gateway host and listener port (443 for HTTP engines,\n8443 on single-IP regions; 5432 / 3306 / ... for TCP wires). `null` until ready." } ] }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/PortEndpointDto" }, "description": "Every public endpoint (primary first, then e.g. the Qdrant / Weaviate `-grpc` host\nor ClickHouse native 9440). Empty until the instance has an endpoint." }, "engine": { "type": "string" }, "engine_version": { "type": "string" }, "erasure_certificate_id": { "type": [ "string", "null" ], "description": "Set once full erasure was requested; the audit row with this id is the\nerasure certificate." }, "git_branch": { "type": [ "string", "null" ], "description": "Git branch a preview integration created this branch for." }, "ha": { "type": "boolean" }, "id": { "type": "string" }, "maintenance_window": { "type": [ "string", "null" ], "description": "Maintenance window (`sun 03:00-05:00`, UTC); `null` = platform default." }, "mtls": { "type": "boolean", "description": "Client certificates are required (a client CA bundle is configured)." }, "name": { "type": "string" }, "org_id": { "type": "string" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "placement": { "type": "string" }, "pooler_enabled": { "type": "boolean" }, "pooler_endpoint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EndpointDto", "description": "Transaction-mode pooler endpoint (PostgreSQL / TimescaleDB with `pooler_enabled`):\nthe direct host with `-pool` appended to its first label, same port. `null`\nwithout a pooler or before the instance has an endpoint." } ] }, "project_id": { "type": "string" }, "region": { "type": "string" }, "replicas": { "type": "integer", "format": "int32" }, "size": { "type": "string" }, "status": { "type": "string", "description": "Actual state (docs/04-provisioning.md §2)." }, "status_message": { "type": [ "string", "null" ] }, "status_reason": { "type": [ "string", "null" ] }, "storage_gb": { "type": "integer", "format": "int32" }, "tags": { "type": "object", "description": "Free-form tags." }, "team_id": { "type": [ "string", "null" ], "description": "Owning team (from the project, docs/18 §2)." }, "tier": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InstanceUpdateDto": { "type": "object", "required": [ "status", "instance", "changes" ], "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceChangeDto" } }, "instance": { "$ref": "#/components/schemas/InstanceDto" }, "status": { "type": "string", "description": "`accepted` (sagas requested, 202) or `applied` (settings only, 200)." } } }, "InviteDto": { "type": "object", "description": "A pending invite. The token only ever travels in the invite email.", "required": [ "id", "org_id", "email", "role", "invited_by", "expires_at", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "invited_by": { "type": "string" }, "org_id": { "type": "string" }, "role": { "type": "string" } } }, "InvoiceDto": { "type": "object", "required": [ "id", "status", "amount_due_cents", "currency", "held" ], "properties": { "amount_due_cents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "held": { "type": "boolean", "description": "Held for review (reconciliation or a security freeze) and not yet released." }, "hosted_invoice_url": { "type": [ "string", "null" ], "description": "Stripe-hosted invoice page." }, "id": { "type": "string", "description": "Stripe invoice id." }, "pdf_url": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`draft`, `open`, `paid`, `void` or `uncollectible`." } } }, "InvoiceListDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "LogsUrlDto": { "type": "object", "required": [ "url", "method", "expires_at", "instance_id", "cell_id", "follow", "token_id" ], "properties": { "cell_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "follow": { "type": "boolean" }, "instance_id": { "type": "string" }, "method": { "type": "string" }, "token_id": { "type": "string" }, "url": { "type": "string", "description": "`GET` it directly (browser / CLI); it works once and streams `text/plain`." } } }, "MeDto": { "type": "object", "required": [ "session", "orgs" ], "properties": { "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/MeOrgDto" } }, "session": { "$ref": "#/components/schemas/MeSessionDto" }, "user": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MeUserDto", "description": "`null` for API keys and impersonation." } ] } } }, "MeOrgDto": { "type": "object", "required": [ "id", "slug", "name", "plan_id", "tier", "role", "mfa_required", "accessible" ], "properties": { "accessible": { "type": "boolean", "description": "The session can act in this org (false: MFA step-up needed)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "mfa_required": { "type": "boolean", "description": "Members must use MFA (signed BAA or Enterprise plan): the session is refused\nbelow aal2. Otherwise MFA is optional (enforced only once the user enrolled)." }, "name": { "type": "string" }, "plan_id": { "type": "string" }, "role": { "type": "string", "description": "The caller's role (`impersonated` for staff)." }, "slug": { "type": "string" }, "tier": { "type": "string" } } }, "MeSessionDto": { "type": "object", "required": [ "kind", "aal", "mfa", "scopes" ], "properties": { "aal": { "type": "string", "description": "`aal1` or `aal2` (API keys and impersonation count as `aal2`)." }, "api_key_id": { "type": [ "string", "null" ], "description": "API key id (`kind = api_key`)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "kind": { "type": "string", "description": "`session`, `api_key` or `impersonation`." }, "mfa": { "type": "boolean", "description": "The session completed MFA." }, "scopes": { "type": "array", "items": { "type": "string" } }, "service_account_id": { "type": [ "string", "null" ] }, "sso_provider": { "type": [ "string", "null" ], "description": "Kratos OIDC provider of an SSO session." }, "staff_email": { "type": [ "string", "null" ], "description": "Impersonating staff (`kind = impersonation`)." } } }, "MeUserDto": { "type": "object", "required": [ "id", "mfa_enrolled" ], "properties": { "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "email": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "mfa_enrolled": { "type": "boolean", "description": "The user has enrolled a second factor (seen at aal2)." }, "name": { "type": [ "string", "null" ] } } }, "MemberDto": { "type": "object", "required": [ "user_id", "role", "mfa_enrolled", "seat", "joined_at" ], "properties": { "email": { "type": [ "string", "null" ] }, "invited_by": { "type": [ "string", "null" ] }, "joined_at": { "type": "string", "format": "date-time" }, "mfa_enrolled": { "type": "boolean", "description": "The user has completed MFA on a session (Kratos aal2)." }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "seat": { "type": "boolean", "description": "Whether this membership consumes a seat." }, "user_id": { "type": "string" } } }, "MembersResponse": { "type": "object", "required": [ "items", "seats" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemberDto" } }, "next_cursor": { "type": [ "string", "null" ] }, "seats": { "$ref": "#/components/schemas/SeatsDto" } } }, "MetricPointDto": { "type": "object", "required": [ "t", "v" ], "properties": { "t": { "type": "string", "format": "date-time", "description": "Start of the hourly bucket." }, "v": { "type": "number", "format": "double" } } }, "MetricSeriesDto": { "type": "object", "required": [ "metric", "unit", "source_metric", "points" ], "properties": { "metric": { "type": "string", "description": "`cpu`, `storage`, `egress` or `connections`." }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/MetricPointDto" } }, "source_metric": { "type": "string", "description": "Metering metric the series comes from." }, "unit": { "type": "string", "description": "`cu`, `gb` or `connections`." } } }, "MetricsDto": { "type": "object", "required": [ "instance_id", "range", "granularity", "from", "to", "series", "note" ], "properties": { "from": { "type": "string", "format": "date-time" }, "granularity": { "type": "string", "description": "Always `1h`: hourly rollups." }, "instance_id": { "type": "string" }, "note": { "type": "string" }, "range": { "type": "string" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeriesDto" } }, "to": { "type": "string", "format": "date-time" } } }, "MigrationDto": { "type": "object", "required": [ "id", "org_id", "instance_id", "engine", "source_kind", "source", "mode", "status", "options", "created_by", "created_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "engine": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "instance_id": { "type": "string" }, "message": { "type": [ "string", "null" ], "description": "Human hint (e.g. uploads not configured on this deployment)." }, "mode": { "type": "string" }, "options": { "description": "`include`, `exclude`, `drop_target`, `reverse_sync`." }, "org_id": { "type": "string" }, "preflight": {}, "progress": { "description": "Latest progress: `stage`, object/byte counters, `message`, and for continuous\nsync `lag_seconds`, `ready_for_cutover`, `cutover_downtime_ms`, `cutover_aborted`." }, "provider": { "type": [ "string", "null" ] }, "snapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MigrationSnapshotDto", "description": "Run-level progress for the portal's timeline (ZB-267): phase and phase history,\nbytes done / total, objects, rate, ETA, sync lag and per-object rows. On a single\nmigration read, `phase` is `target_provisioning` while the target instance is\nstill starting." } ] }, "source": { "description": "Redacted source description (host, port, database, format, source instance)." }, "source_kind": { "type": "string" }, "status": { "type": "string", "description": "`pending`, `preflight`, `copying`, `verifying`, `syncing`, `ready_for_cutover`,\n`cutting_over`, `completed`, `failed`, `cancelled`. An aborted cutover goes back\nfrom `cutting_over` to `syncing`." }, "updated_at": { "type": "string", "format": "date-time" }, "upload_expires_in": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "upload_key": { "type": [ "string", "null" ], "description": "Object key of the upload (upload sources)." }, "upload_url": { "type": [ "string", "null" ], "description": "Pre-signed PUT URL for the upload; only on creation, valid for `upload_expires_in` seconds." }, "verification": {} } }, "MigrationObjectProgress": { "type": "object", "description": "One table / collection.", "properties": { "bytes_done": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "bytes_total": { "type": [ "integer", "null" ], "format": "int64", "default": null, "minimum": 0 }, "kind": { "type": [ "string", "null" ], "description": "`table`, `collection`, `keys`, ...", "default": null }, "name": { "type": "string", "default": "" }, "rows": { "type": [ "integer", "null" ], "format": "int64", "default": null, "minimum": 0 }, "rows_total": { "type": [ "integer", "null" ], "format": "int64", "default": null, "minimum": 0 }, "state": { "type": "string", "description": "`pending`, `running` or `done`.", "default": "", "example": "running" } } }, "MigrationOptionsRequest": { "type": "object", "properties": { "drop_target": { "type": "boolean", "description": "Drop existing objects in the target before restoring." }, "exclude": { "type": "array", "items": { "type": "string" }, "description": "Tables / collections / key patterns to skip." }, "include": { "type": "array", "items": { "type": "string" }, "description": "Tables / collections / key patterns to copy (all when empty)." }, "reverse_sync": { "type": "boolean", "description": "`copy_and_sync` only: after cutover keep replicating target → source so the\nold database stays a rollback path (`ZB_REVERSE_SYNC` on the agent)." } } }, "MigrationPhase": { "type": "string", "description": "Timeline phase of a migration run.", "enum": [ "target_provisioning", "preflight", "compatible", "incompatible", "copying", "verifying", "syncing", "cutover", "completed", "failed", "cancelled" ] }, "MigrationPhaseMark": { "type": "object", "description": "When the run entered a phase.", "required": [ "phase", "at" ], "properties": { "at": { "type": "string", "description": "RFC 3339." }, "phase": { "$ref": "#/components/schemas/MigrationPhase" } } }, "MigrationSnapshotDto": { "type": "object", "description": "Latest run-level progress: what the portal's stage timeline and progress bar show.", "properties": { "bytes_done": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "bytes_estimated": { "type": "boolean", "description": "`bytes_done` is derived from finished objects (the engine tools report no bytes).", "default": false }, "bytes_total": { "type": [ "integer", "null" ], "format": "int64", "description": "Preflight size estimate, raised when the tools report larger totals.", "default": null, "minimum": 0 }, "current": { "type": [ "string", "null" ], "description": "Table / collection being copied.", "default": null }, "error": { "type": [ "string", "null" ], "default": null }, "eta_seconds": { "type": [ "integer", "null" ], "format": "int64", "default": null, "minimum": 0 }, "lag_seconds": { "type": [ "number", "null" ], "format": "double", "description": "Continuous sync: seconds behind the source.", "default": null }, "message": { "type": [ "string", "null" ], "default": null }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/MigrationObjectProgress" }, "default": [] }, "objects_done": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "objects_total": { "type": "integer", "format": "int64", "default": 0, "minimum": 0 }, "phase": { "oneOf": [ { "$ref": "#/components/schemas/MigrationPhase" } ], "default": "preflight" }, "phases": { "type": "array", "items": { "$ref": "#/components/schemas/MigrationPhaseMark" }, "description": "Phase history, oldest first.", "default": [] }, "rate_bytes_per_sec": { "type": [ "number", "null" ], "format": "double", "description": "Smoothed copy rate.", "default": null }, "ready_for_cutover": { "type": [ "boolean", "null" ], "default": null }, "started_at": { "type": [ "string", "null" ], "default": null }, "target_status": { "type": [ "string", "null" ], "description": "Target instance status while it is not ready yet (`provisioning`, ...).", "default": null }, "updated_at": { "type": [ "string", "null" ], "default": null } } }, "MigrationSourceRequest": { "type": "object", "required": [ "kind" ], "properties": { "filename": { "type": [ "string", "null" ], "description": "`upload`: original file name, used to derive the format.", "example": "app.dump" }, "format": { "type": [ "string", "null" ], "description": "`upload`: file format (`pg_custom`, `sql`, `sql_gz`, `rdb`, `sqlite`, `duckdb`,\n`bson_tar`, `csv`, `parquet`). Derived from `filename` when omitted.", "example": "pg_custom" }, "instance_id": { "type": [ "string", "null" ], "description": "`zerobase`: the source instance id (same org)." }, "kind": { "type": "string", "description": "`connection_string`, `upload` or `zerobase`.", "example": "connection_string" }, "provider": { "type": [ "string", "null" ], "description": "Provider preset override; auto-detected from the hostname when omitted.", "example": "neon" }, "url": { "type": [ "string", "null" ], "description": "`connection_string`: the source URL (never stored on the migration row).", "example": "postgres://user:pw@ep-x.us-east-2.aws.neon.tech/db?sslmode=require" } } }, "MtlsDto": { "type": "object", "required": [ "enabled", "subjects" ], "properties": { "enabled": { "type": "boolean", "description": "Client certificates signed by the uploaded CA are required." }, "not_after": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest expiry in the bundle." }, "sha256": { "type": [ "string", "null" ], "description": "Hex SHA-256 of the uploaded PEM." }, "subjects": { "type": "array", "items": { "type": "string" }, "description": "Subjects of the CA certificates in the bundle." } } }, "NetworkDto": { "type": "object", "required": [ "instance_id", "allow_cidrs", "mtls", "revision" ], "properties": { "allow_cidrs": { "type": "array", "items": { "type": "string" } }, "custom_domain": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DomainDto", "description": "The instance's custom domain (pending or verified), if any." } ] }, "instance_id": { "type": "string" }, "mtls": { "$ref": "#/components/schemas/MtlsDto" }, "revision": { "type": "integer", "format": "int64", "description": "Revision of the network state sent to the cell." } } }, "OneTimeUrlDto": { "type": "object", "description": "A one-time URL on the cell operator.", "required": [ "url", "method", "expires_at", "instance_id", "cell_id", "audience", "token_id" ], "properties": { "audience": { "type": "string", "description": "`reveal` or `rotate`." }, "cell_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "instance_id": { "type": "string" }, "method": { "type": "string", "description": "`GET` for reveal, `POST` for rotate." }, "token_id": { "type": "string", "description": "Token id (`jti`) for correlation with the operator's audit trail." }, "url": { "type": "string", "description": "Fetch this URL directly from the browser/CLI; it works once." } } }, "OrgDto": { "type": "object", "required": [ "id", "slug", "name", "tier", "plan_id", "mfa_required", "region_default", "created_at", "usage_alert_percent" ], "properties": { "baa_signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "baa_version": { "type": [ "string", "null" ], "description": "Version of the BAA that was accepted (`compliance/baa/VERSION`)." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set once the owner closed the org; instances are being deleted or erased." }, "created_at": { "type": "string", "format": "date-time" }, "frozen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the org is frozen for a security review: mutations answer `423\norg_frozen`, reads keep working." }, "id": { "type": "string" }, "mfa_required": { "type": "boolean", "description": "Members must authenticate with MFA (set when the BAA is signed)." }, "my_role": { "type": [ "string", "null" ], "description": "The caller's role (`GET /v1/orgs/{org_id}`); `impersonated` for a staff\nimpersonation session." }, "name": { "type": "string" }, "plan_id": { "type": "string" }, "region_default": { "type": "string" }, "role": { "type": [ "string", "null" ], "description": "The caller's role in this org." }, "slug": { "type": "string" }, "spending_cap_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Monthly spending cap (list price, cents); `null` = no cap." }, "tier": { "type": "string" }, "usage_alert_percent": { "type": "integer", "format": "int32", "description": "Usage alert threshold, percent of the cap." } } }, "PageResponse_ApiKeyDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "name", "prefix", "role", "scopes", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "prefix": { "type": "string", "description": "First characters of the key, for identification." }, "role": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "service_account_id": { "type": [ "string", "null" ], "description": "Set for service-account keys." }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while an automatic security response suspends the key (docs/20 §3);\n`POST .../api-keys/{key_id}/actions/unsuspend` lifts it." }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_until": { "type": [ "string", "null" ], "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_ApprovalDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "team_id", "project_id", "kind", "requester_id", "requester_type", "request", "reasons", "estimate", "status", "expires_at", "created_at" ], "properties": { "approver_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "estimate": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "instance_id": { "type": [ "string", "null" ], "description": "Instance created by the approval." }, "kind": { "type": "string", "description": "`instance.create`." }, "org_id": { "type": "string" }, "project_id": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "`size_above_threshold`, `placement_requires_approval`, `engine_requires_approval`,\n`over_budget`, `policy_requires_all`." }, "request": { "type": "object", "description": "The original create request." }, "requester_id": { "type": "string" }, "requester_type": { "type": "string" }, "status": { "type": "string", "description": "`pending`, `approved`, `denied` or `expired`." }, "team_id": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_BackupDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "instance_id", "kind", "engine", "status", "size_bytes", "protected", "created_at" ], "properties": { "checksum": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "cross_region_location": { "type": [ "string", "null" ] }, "engine": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "immutable_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Object Lock retain-until; the backup cannot be deleted before this." }, "instance_id": { "type": "string" }, "kind": { "type": "string", "description": "`scheduled`, `manual`, `pre_change`." }, "label": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ], "description": "`s3://bucket/org_/inst_//`" }, "parent_backup_id": { "type": [ "string", "null" ] }, "protected": { "type": "boolean", "description": "The newest successful backup of the instance is never pruned." }, "size_bytes": { "type": "integer", "format": "int64" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`requested`, `running`, `completed`, `failed`, `pending_erasure`." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "verified_ok": { "type": [ "boolean", "null" ] } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_InstanceDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "project_id", "name", "engine", "engine_version", "size", "region", "tier", "placement", "status", "desired_status", "storage_gb", "pooler_enabled", "replicas", "ha", "allow_cidrs", "endpoints", "tags", "created_at", "updated_at", "mtls" ], "properties": { "allow_cidrs": { "type": "array", "items": { "type": "string" } }, "branch_of": { "type": [ "string", "null" ], "description": "Source instance when this instance is a branch." }, "cost_centre": { "type": [ "string", "null" ], "description": "Cost-centre tag for chargeback." }, "created_at": { "type": "string", "format": "date-time" }, "custom_domain": { "type": [ "string", "null" ] }, "desired_status": { "type": "string", "description": "Customer intent: `running`, `paused`, `deleted` or `erased`." }, "endpoint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EndpointDto", "description": "Primary public endpoint: the gateway host and listener port (443 for HTTP engines,\n8443 on single-IP regions; 5432 / 3306 / ... for TCP wires). `null` until ready." } ] }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/PortEndpointDto" }, "description": "Every public endpoint (primary first, then e.g. the Qdrant / Weaviate `-grpc` host\nor ClickHouse native 9440). Empty until the instance has an endpoint." }, "engine": { "type": "string" }, "engine_version": { "type": "string" }, "erasure_certificate_id": { "type": [ "string", "null" ], "description": "Set once full erasure was requested; the audit row with this id is the\nerasure certificate." }, "git_branch": { "type": [ "string", "null" ], "description": "Git branch a preview integration created this branch for." }, "ha": { "type": "boolean" }, "id": { "type": "string" }, "maintenance_window": { "type": [ "string", "null" ], "description": "Maintenance window (`sun 03:00-05:00`, UTC); `null` = platform default." }, "mtls": { "type": "boolean", "description": "Client certificates are required (a client CA bundle is configured)." }, "name": { "type": "string" }, "org_id": { "type": "string" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "placement": { "type": "string" }, "pooler_enabled": { "type": "boolean" }, "pooler_endpoint": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EndpointDto", "description": "Transaction-mode pooler endpoint (PostgreSQL / TimescaleDB with `pooler_enabled`):\nthe direct host with `-pool` appended to its first label, same port. `null`\nwithout a pooler or before the instance has an endpoint." } ] }, "project_id": { "type": "string" }, "region": { "type": "string" }, "replicas": { "type": "integer", "format": "int32" }, "size": { "type": "string" }, "status": { "type": "string", "description": "Actual state (docs/04-provisioning.md §2)." }, "status_message": { "type": [ "string", "null" ] }, "status_reason": { "type": [ "string", "null" ] }, "storage_gb": { "type": "integer", "format": "int32" }, "tags": { "type": "object", "description": "Free-form tags." }, "team_id": { "type": [ "string", "null" ], "description": "Owning team (from the project, docs/18 §2)." }, "tier": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_InviteDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "A pending invite. The token only ever travels in the invite email.", "required": [ "id", "org_id", "email", "role", "invited_by", "expires_at", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "invited_by": { "type": "string" }, "org_id": { "type": "string" }, "role": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_MigrationDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "instance_id", "engine", "source_kind", "source", "mode", "status", "options", "created_by", "created_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "engine": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "instance_id": { "type": "string" }, "message": { "type": [ "string", "null" ], "description": "Human hint (e.g. uploads not configured on this deployment)." }, "mode": { "type": "string" }, "options": { "description": "`include`, `exclude`, `drop_target`, `reverse_sync`." }, "org_id": { "type": "string" }, "preflight": {}, "progress": { "description": "Latest progress: `stage`, object/byte counters, `message`, and for continuous\nsync `lag_seconds`, `ready_for_cutover`, `cutover_downtime_ms`, `cutover_aborted`." }, "provider": { "type": [ "string", "null" ] }, "snapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MigrationSnapshotDto", "description": "Run-level progress for the portal's timeline (ZB-267): phase and phase history,\nbytes done / total, objects, rate, ETA, sync lag and per-object rows. On a single\nmigration read, `phase` is `target_provisioning` while the target instance is\nstill starting." } ] }, "source": { "description": "Redacted source description (host, port, database, format, source instance)." }, "source_kind": { "type": "string" }, "status": { "type": "string", "description": "`pending`, `preflight`, `copying`, `verifying`, `syncing`, `ready_for_cutover`,\n`cutting_over`, `completed`, `failed`, `cancelled`. An aborted cutover goes back\nfrom `cutting_over` to `syncing`." }, "updated_at": { "type": "string", "format": "date-time" }, "upload_expires_in": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "upload_key": { "type": [ "string", "null" ], "description": "Object key of the upload (upload sources)." }, "upload_url": { "type": [ "string", "null" ], "description": "Pre-signed PUT URL for the upload; only on creation, valid for `upload_expires_in` seconds." }, "verification": {} } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_ProjectDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "slug", "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "slug": { "type": "string" }, "team_id": { "type": [ "string", "null" ], "description": "Owning team; `null` until the default team is assigned." }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_RestoreDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "backup_id", "source_instance_id", "target_instance_id", "mode", "status", "created_at", "updated_at" ], "properties": { "backup_id": { "type": "string" }, "backup_size_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Size of the backup being restored, when known." }, "bytes_restored": { "type": "integer", "format": "int64", "description": "Bytes restored as reported by the restore (0 until known)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "estimated_downtime_minutes": { "type": [ "integer", "null" ], "format": "int32", "description": "Expected downtime for in-place restores, shown up front (docs/09 §5).", "minimum": 0 }, "id": { "type": "string" }, "mode": { "type": "string", "description": "`new_instance` or `in_place`." }, "pre_change_backup_id": { "type": [ "string", "null" ], "description": "In-place: the backup taken right before the restore." }, "progress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RestoreProgressDto", "description": "Live progress of an in-place restore (ZB-272); absent until the restore starts." } ] }, "source_instance_id": { "type": "string" }, "status": { "type": "string", "description": "`requested`, `pre_change_backup`, `restoring`, `completed`, `failed`." }, "target_instance_id": { "type": "string" }, "target_time": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_ServiceAccountDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "name", "role", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "role": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_SupportGrantDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "scope", "staff_id", "created_by", "created_at", "expires_at", "active" ], "properties": { "active": { "type": "boolean", "description": "Not expired and not revoked." }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "instance_id": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_by": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "staff_id": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_TeamDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "slug", "name", "default", "quota", "approval_policy", "allowed_engines", "allowed_regions", "allowed_placements", "created_at", "updated_at" ], "properties": { "allowed_engines": { "type": "array", "items": { "type": "string" } }, "allowed_placements": { "type": "array", "items": { "type": "string" } }, "allowed_regions": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ApprovalPolicy" }, "budget_cents": { "type": [ "integer", "null" ], "format": "int64" }, "cost_centre": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "default": { "type": "boolean", "description": "The org's default \"Everyone\" team." }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "quota": { "$ref": "#/components/schemas/TeamQuota" }, "slug": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_WebhookDeliveryDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "endpoint_id", "event_id", "event_type", "status", "attempts", "next_attempt_at", "created_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "endpoint_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_status_code": { "type": [ "integer", "null" ], "format": "int32" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "`pending`, `delivered` or `failed`." } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PageResponse_WebhookDto": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "org_id", "url", "events", "enabled", "failure_count", "created_by", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } }, "failure_count": { "type": "integer", "format": "int32", "description": "Consecutive failed deliveries." }, "id": { "type": "string" }, "org_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page; absent on the last page." } } }, "PermissionCatalogueDto": { "type": "object", "description": "Every org permission, grouped by area with human labels.", "required": [ "groups" ], "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionGroupDto" } } } }, "PermissionDto": { "type": "object", "description": "One permission in the catalogue.", "required": [ "id", "label", "description", "project_scoped", "locked" ], "properties": { "description": { "type": "string" }, "id": { "type": "string", "example": "instances:read" }, "label": { "type": "string", "example": "View instances" }, "locked": { "type": "boolean", "description": "Cannot be toggled on a predefined role (`org:read` always on, `org:delete`\nowner-only)." }, "project_scoped": { "type": "boolean", "description": "Carried by project-scoped roles." } } }, "PermissionGroupDto": { "type": "object", "description": "A group of permissions (portal checklist section).", "required": [ "id", "label", "permissions" ], "properties": { "id": { "type": "string", "example": "instances" }, "label": { "type": "string", "example": "Instances & projects" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } } } }, "PitrWindowDto": { "type": "object", "required": [ "instance_id", "engine", "supported", "pitr_days" ], "properties": { "earliest": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest restorable point (the oldest base inside the window), if any." }, "engine": { "type": "string" }, "instance_id": { "type": "string" }, "latest": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest restorable point (now, when continuous archiving is on)." }, "pitr_days": { "type": "integer", "format": "int32", "minimum": 0 }, "reason": { "type": [ "string", "null" ] }, "supported": { "type": "boolean", "description": "Whether the engine and plan support point-in-time recovery." } } }, "PlanDto": { "type": "object", "required": [ "id", "name", "tier", "base_price_cents", "card_required", "overage_allowed", "contract", "included_instances", "included_compute_credit_cents", "included_storage_gb_per_instance", "included_egress_gb", "included_backup_gb", "quotas", "backup_policy", "placements", "addons", "retained_after_delete_days", "log_retention_days", "features" ], "properties": { "addons": { "type": "array", "items": { "type": "string" }, "description": "Add-on ids (PITR, custom domains) the plan may buy." }, "backup_policy": { "type": "string" }, "base_price_cents": { "type": "integer", "format": "int64", "minimum": 0 }, "card_required": { "type": "boolean" }, "contract": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "extra_seat_price_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Extra-seat price in USD cents; `null` = extra seats not sold, `0` = included.", "minimum": 0 }, "features": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "included_backup_gb": { "type": "integer", "format": "int64", "minimum": 0 }, "included_compute_credit_cents": { "type": "integer", "format": "int64", "description": "Monthly compute credit in USD cents (applied once per org per month).", "minimum": 0 }, "included_egress_gb": { "type": "integer", "format": "int64", "minimum": 0 }, "included_instances": { "type": "integer", "format": "int64", "description": "Instances covered by the plan fee (via the compute credit); more are billed per size.", "minimum": 0 }, "included_storage_gb_per_instance": { "type": "number", "format": "double", "description": "Disk included per instance (GB)." }, "log_retention_days": { "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "overage_allowed": { "type": "boolean" }, "placements": { "type": "array", "items": { "type": "string" } }, "quotas": { "$ref": "#/components/schemas/PlanQuotasDto" }, "retained_after_delete_days": { "type": "integer", "format": "int32", "minimum": 0 }, "sla": { "type": [ "string", "null" ] }, "spend_cap_default": { "type": [ "boolean", "null" ], "description": "Whether the spend cap is on by default (`null` = plan has no spend cap)." }, "support": { "type": [ "string", "null" ] }, "tier": { "type": "string" } } }, "PlanQuotasDto": { "type": "object", "required": [ "instances", "max_size", "storage_per_instance_gb", "total_storage_gb", "members", "projects", "custom_domains", "read_replicas" ], "properties": { "custom_domains": { "type": "integer", "format": "int64" }, "instances": { "type": "integer", "format": "int64", "description": "`-1` means unlimited." }, "max_size": { "type": "string" }, "members": { "type": "integer", "format": "int64" }, "projects": { "type": "integer", "format": "int64" }, "read_replicas": { "type": "integer", "format": "int64" }, "storage_per_instance_gb": { "type": "integer", "format": "int64" }, "total_storage_gb": { "type": "integer", "format": "int64" } } }, "PortEndpointDto": { "type": "object", "description": "One public gateway endpoint of an instance (docs/06 §2): the host and listener port\ncustomers connect to, never the engine pod port.", "required": [ "name", "host", "port", "wire", "grpc" ], "properties": { "grpc": { "type": "boolean", "description": "HTTP/2 end to end (gRPC clients)." }, "host": { "type": "string", "example": "qdrant-01j9abc-grpc.us-east.databasezy.com" }, "name": { "type": "string", "description": "`db` (the primary port) or a catalogue `extra_ports` key: `grpc` (Qdrant /\nWeaviate gRPC under a `-grpc` host), `native` (ClickHouse native TLS, 9440),\n`http` (QuestDB REST + ILP over HTTP).", "example": "grpc" }, "port": { "type": "integer", "format": "int32", "description": "Gateway listener: 443 for HTTP engines (8443 on single-IP regions), 8443\nClickHouse HTTPS, 9440 ClickHouse native, 5432 / 3306 / 6379 / 27017 TCP wires.", "example": 443 }, "wire": { "type": "string", "description": "`postgres`, `mysql`, `resp`, `mongodb`, `http` or `tcp_tls`.", "example": "http" } } }, "PredefinedRoleDto": { "type": "object", "description": "A predefined org role with its default and effective permission sets.", "required": [ "role", "label", "description", "editable", "customized", "default_permissions", "permissions", "project_assignable" ], "properties": { "customized": { "type": "boolean", "description": "The org changed the default set." }, "default_permissions": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "editable": { "type": "boolean", "description": "The org may edit this role's permissions (every role except `owner`)." }, "label": { "type": "string", "example": "Read-only" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Effective set in this org (the edited set or the default)." }, "project_assignable": { "type": "boolean", "description": "Can be assigned on a single project (`admin`, `developer`, `viewer`)." }, "role": { "type": "string", "description": "Wire value (`viewer` is labelled \"Read-only\").", "example": "viewer" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_by": { "type": [ "string", "null" ] } } }, "PredefinedRolesDto": { "type": "object", "description": "Predefined roles of the org.", "required": [ "plan_eligible", "can_edit", "roles" ], "properties": { "can_edit": { "type": "boolean", "description": "`plan_eligible` and the caller holds `members:manage`." }, "plan_eligible": { "type": "boolean", "description": "The plan includes editable roles and project-scoped roles (Team, Enterprise)." }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/PredefinedRoleDto" } } } }, "Problem": { "type": "object", "description": "RFC 9457 body.", "required": [ "type", "title", "status" ], "properties": { "detail": { "type": [ "string", "null" ] }, "errors": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/FieldError" } }, "required_permission": { "type": [ "string", "null" ], "description": "Permission that was required (403 only)." }, "status": { "type": "integer", "format": "int32", "minimum": 0 }, "title": { "type": "string" }, "type": { "type": "string", "description": "Problem type URI." } } }, "ProgrammeApplicationDto": { "type": "object", "required": [ "id", "programme", "status", "company_name", "description", "contact_email", "created_at" ], "properties": { "company_name": { "type": "string" }, "contact_email": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "string" }, "programme": { "type": "string" }, "repository_url": { "type": [ "string", "null" ] }, "review_notes": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`pending`, `approved`, `rejected`, `withdrawn`." }, "website": { "type": [ "string", "null" ] } } }, "ProgrammeApplicationRequest": { "type": "object", "required": [ "programme", "company_name", "description", "contact_email" ], "properties": { "company_name": { "type": "string", "example": "Acme Labs" }, "contact_email": { "type": "string" }, "description": { "type": "string", "description": "What you are building and how Databasezy fits (20-5000 characters)." }, "details": { "description": "Free-form extra answers (funding stage, team size, stars, licence, ...)." }, "programme": { "type": "string", "description": "`startup` or `oss`.", "example": "startup" }, "repository_url": { "type": [ "string", "null" ], "description": "OSS: the project repository." }, "website": { "type": [ "string", "null" ] } } }, "ProjectDto": { "type": "object", "required": [ "id", "org_id", "slug", "name", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "slug": { "type": "string" }, "team_id": { "type": [ "string", "null" ], "description": "Owning team; `null` until the default team is assigned." }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectRoleAssignmentDto": { "type": "object", "description": "A member's role on one project.", "required": [ "project_id", "project_name", "user_id", "role", "created_by", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "project_id": { "type": "string" }, "project_name": { "type": "string" }, "role": { "type": "string", "description": "`admin`, `developer` or `viewer` (Read-only).", "example": "developer" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" } } }, "PutProjectRoleRequest": { "type": "object", "description": "Set a member's role on a project.", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "`admin`, `developer` or `viewer` (Read-only).", "example": "developer" } } }, "PutSsoRequest": { "type": "object", "required": [ "idp_metadata_url" ], "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Email domains routed to this IdP." }, "idp_metadata_url": { "type": "string", "description": "SAML IdP metadata URL (https).", "example": "https://login.microsoftonline.com/.../federationmetadata.xml" }, "scim_enabled": { "type": "boolean" } } }, "PutTeamMemberRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "`lead`, `developer`, `operator` or `viewer`.", "example": "developer" } } }, "ReferralCodeDto": { "type": "object", "required": [ "code", "kind", "credit_cents", "referrer_credit_cents", "redemptions", "created_at" ], "properties": { "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "credit_cents": { "type": "integer", "format": "int64", "description": "Credit for the org that signs up with the code (cents, USD)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "kind": { "type": "string", "description": "`referral` or `promo`." }, "max_redemptions": { "type": [ "integer", "null" ], "format": "int32" }, "redemptions": { "type": "integer", "format": "int32" }, "referrer_credit_cents": { "type": "integer", "format": "int64", "description": "Credit for this org per redemption." } } }, "ReferralSummaryDto": { "type": "object", "required": [ "earned_cents" ], "properties": { "code": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReferralCodeDto" } ] }, "earned_cents": { "type": "integer", "format": "int64", "description": "Credits earned from referrals (queued + applied), cents." }, "signup_url": { "type": [ "string", "null" ], "description": "Signup link with the code." } } }, "RegionDto": { "type": "object", "required": [ "id", "name", "tiers", "available" ], "properties": { "available": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "tiers": { "type": "array", "items": { "type": "string" } } } }, "RestoreDto": { "type": "object", "required": [ "id", "backup_id", "source_instance_id", "target_instance_id", "mode", "status", "created_at", "updated_at" ], "properties": { "backup_id": { "type": "string" }, "backup_size_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Size of the backup being restored, when known." }, "bytes_restored": { "type": "integer", "format": "int64", "description": "Bytes restored as reported by the restore (0 until known)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "estimated_downtime_minutes": { "type": [ "integer", "null" ], "format": "int32", "description": "Expected downtime for in-place restores, shown up front (docs/09 §5).", "minimum": 0 }, "id": { "type": "string" }, "mode": { "type": "string", "description": "`new_instance` or `in_place`." }, "pre_change_backup_id": { "type": [ "string", "null" ], "description": "In-place: the backup taken right before the restore." }, "progress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RestoreProgressDto", "description": "Live progress of an in-place restore (ZB-272); absent until the restore starts." } ] }, "source_instance_id": { "type": "string" }, "status": { "type": "string", "description": "`requested`, `pre_change_backup`, `restoring`, `completed`, `failed`." }, "target_instance_id": { "type": "string" }, "target_time": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RestoreProgressDto": { "type": "object", "description": "Latest progress of an in-place restore.", "required": [ "stage", "stages" ], "properties": { "bytes_done": { "type": [ "integer", "null" ], "format": "int64" }, "bytes_total": { "type": [ "integer", "null" ], "format": "int64" }, "eta_seconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated seconds until the data is restored." }, "message": { "type": [ "string", "null" ] }, "stage": { "type": "string", "description": "`safety_backup`, `stopping_connections`, `restoring`, `verifying`, `back_online`,\n`completed`, `failed`." }, "stages": { "type": "object", "description": "When each stage was first reached (`stage` -> RFC 3339).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When this snapshot was reported." } } }, "RestoreRequest": { "type": "object", "properties": { "confirm_name": { "type": [ "string", "null" ], "description": "In-place only: the instance name typed by the customer as confirmation." }, "mode": { "type": [ "string", "null" ], "description": "`new_instance` (default, safe) or `in_place` (requires `confirm_name`).", "example": "new_instance" }, "name": { "type": [ "string", "null" ], "description": "New instance only: name (default `-restore-`)." }, "project_id": { "type": [ "string", "null" ], "description": "New instance only: project for the new instance (default: the source's)." }, "size": { "type": [ "string", "null" ], "description": "New instance only: size override (default: the source's)." }, "target_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Point-in-time target (RFC 3339) inside the PITR window; omit to restore the\nbackup as taken." } } }, "RevealRequest": { "type": "object", "description": "Optional reveal body.", "properties": { "purpose": { "type": [ "string", "null" ], "description": "`integration_env_sync`: service-account keys with the\n`credentials:reveal:integration` scope, no MFA step-up." } } }, "ScimGroupMappingDto": { "type": "object", "required": [ "id", "display_name", "team_role", "members", "updated_at" ], "properties": { "display_name": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "members": { "type": "integer", "format": "int64" }, "org_role": { "type": [ "string", "null" ], "description": "Org role of the group's members, if the group grants one." }, "team_id": { "type": [ "string", "null" ], "description": "Team the group maps to." }, "team_role": { "type": "string", "description": "Team role of the group's members (`lead`, `developer`, `operator`, `viewer`)." }, "updated_at": { "type": "string", "format": "date-time" } } }, "ScimTokenDto": { "type": "object", "required": [ "id", "name", "prefix", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "id": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First characters, for identification." } } }, "SeatsDto": { "type": "object", "description": "Seat usage (docs/18 §5): a seat is a human member above `auditor`.", "required": [ "used", "pending_invites", "extra_seats_allowed", "extra" ], "properties": { "extra": { "type": "integer", "format": "int32", "description": "Seats currently above `included` (billed as extra seats).", "minimum": 0 }, "extra_seats_allowed": { "type": "boolean", "description": "The plan bills seats above `included` instead of refusing them." }, "included": { "type": [ "integer", "null" ], "format": "int32", "description": "Included in the plan; absent = unlimited.", "minimum": 0 }, "pending_invites": { "type": "integer", "format": "int32", "description": "Pending invites that will take a seat once accepted.", "minimum": 0 }, "used": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ServiceAccountDto": { "type": "object", "required": [ "id", "org_id", "name", "role", "created_by", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "role": { "type": "string" } } }, "SiemDeliveryDto": { "type": "object", "description": "A delivery as the audit service returns it (the secret never comes back).", "required": [ "id", "kind", "enabled", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "delivered_count": { "type": "integer", "format": "int64" }, "enabled": { "type": "boolean" }, "failures": { "type": "integer", "format": "int32" }, "id": { "type": "string" }, "kind": { "type": "string", "description": "`webhook` or `s3`." }, "last_delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "s3_bucket": { "type": [ "string", "null" ] }, "s3_prefix": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "SignBaaRequest": { "type": "object", "required": [ "legal_entity", "signatory_name", "signatory_title", "accepted_version" ], "properties": { "accepted_version": { "type": "string", "description": "Must equal the current BAA version (`GET .../compliance` → `current_baa_version`).", "example": "v1" }, "legal_entity": { "type": "string", "example": "Acme Health, Inc." }, "signatory_name": { "type": "string", "example": "Ada Lovelace" }, "signatory_title": { "type": "string", "example": "Chief Privacy Officer" } } }, "SizeDto": { "type": "object", "required": [ "id", "tiers", "cpu", "memory", "max_storage_gb", "max_connections", "cu_per_hour", "price_cents_per_hour", "monthly_price_cents" ], "properties": { "cpu": { "type": "string" }, "cu_per_hour": { "type": "number", "format": "double", "description": "Capacity units (1 CU = 1 vCPU + 4 GiB); not the price." }, "id": { "type": "string" }, "max_connections": { "type": "integer", "format": "int32", "minimum": 0 }, "max_storage_gb": { "type": "integer", "format": "int32", "minimum": 0 }, "memory": { "type": "string" }, "monthly_price_cents": { "type": "integer", "format": "int64", "description": "List price for a 730-hour month in USD cents.", "minimum": 0 }, "price_cents_per_hour": { "type": "number", "format": "double", "description": "Compute price of one running hour in USD cents." }, "tiers": { "type": "array", "items": { "type": "string" } } } }, "SpendingCapRequest": { "type": "object", "properties": { "alert_percent": { "type": [ "integer", "null" ], "format": "int32", "description": "Alert threshold, percent of the cap (1-100, default 80)." }, "cap_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Monthly cap on list-price spend (cents); `null` removes the cap." } } }, "SsoConnectionDto": { "type": "object", "required": [ "id", "org_id", "kind", "name", "status", "provider_id", "config", "has_client_secret", "default_role", "created_by", "created_at", "updated_at" ], "properties": { "callback_url": { "type": [ "string", "null" ], "description": "Redirect / ACS target to register at the IdP (Kratos callback for OIDC; the\nbridge's ACS for SAML is shown by the bridge)." }, "config": { "description": "Non-secret settings (issuer, client id, scopes, metadata URL)." }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "default_role": { "type": "string" }, "has_client_secret": { "type": "boolean", "description": "Whether a client secret is stored (never returned)." }, "id": { "type": "string" }, "kind": { "type": "string", "description": "`oidc` or `saml`." }, "last_error": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "org_id": { "type": "string" }, "provider_id": { "type": "string", "description": "Kratos provider id; start a login with\n`/self-service/login/browser` + `provider=`." }, "status": { "type": "string", "description": "`pending` (SAML bridge registration outstanding), `active` or `disabled`." }, "updated_at": { "type": "string", "format": "date-time" } } }, "SsoDiscoveryDto": { "type": "object", "description": "`GET /v1/sso/discover?email=`: what the login page should offer.", "required": [ "sso_required", "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/SsoProviderHint" }, "description": "Providers to offer (Kratos `provider` values); empty when the domain has none." }, "sso_required": { "type": "boolean", "description": "The domain is verified by an org with SSO enforced." } } }, "SsoDomainDto": { "type": "object", "required": [ "id", "domain", "status", "txt_record_name", "txt_record_value", "enforce_sso", "created_at" ], "properties": { "connection_id": { "type": [ "string", "null" ], "description": "Restrict enforcement to one connection (any active one when absent)." }, "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": "string" }, "enforce_sso": { "type": "boolean", "description": "Members at this domain must sign in through SSO." }, "id": { "type": "string" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`pending` or `verified`." }, "txt_record_name": { "type": "string", "description": "TXT record to create for verification." }, "txt_record_value": { "type": "string" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "SsoDto": { "type": "object", "description": "SAML SSO / SCIM placeholder (ZB-166 builds the bridge).", "required": [ "status", "domains", "scim_enabled" ], "properties": { "connection_id": { "type": [ "string", "null" ] }, "domains": { "type": "array", "items": { "type": "string" } }, "idp_metadata_url": { "type": [ "string", "null" ] }, "scim_enabled": { "type": "boolean" }, "status": { "type": "string", "description": "`not_configured`, `pending_verification` or `active`." } } }, "SsoProviderHint": { "type": "object", "required": [ "provider_id", "name", "kind" ], "properties": { "kind": { "type": "string" }, "name": { "type": "string" }, "provider_id": { "type": "string" } } }, "SubsidiaryDto": { "type": "object", "required": [ "org_id", "slug", "name", "plan_id" ], "properties": { "name": { "type": "string" }, "org_id": { "type": "string" }, "plan_id": { "type": "string" }, "slug": { "type": "string" } } }, "SupportGrantDto": { "type": "object", "required": [ "id", "org_id", "scope", "staff_id", "created_by", "created_at", "expires_at", "active" ], "properties": { "active": { "type": "boolean", "description": "Not expired and not revoked." }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "instance_id": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_by": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "staff_id": { "type": "string" } } }, "TeamBudgetDto": { "type": "object", "description": "Team budget position for the current calendar month (list prices).", "required": [ "team_id", "month", "mtd_cents", "instances", "storage_gb", "source" ], "properties": { "budget_cents": { "type": [ "integer", "null" ], "format": "int64" }, "instances": { "type": "integer", "format": "int64" }, "month": { "type": "string" }, "mtd_cents": { "type": "number", "format": "double" }, "remaining_cents": { "type": [ "number", "null" ], "format": "double", "description": "`budget - mtd`; absent without a budget." }, "source": { "type": "string", "description": "`metering` or `estimate`." }, "storage_gb": { "type": "integer", "format": "int64" }, "team_id": { "type": "string" } } }, "TeamDto": { "type": "object", "required": [ "id", "org_id", "slug", "name", "default", "quota", "approval_policy", "allowed_engines", "allowed_regions", "allowed_placements", "created_at", "updated_at" ], "properties": { "allowed_engines": { "type": "array", "items": { "type": "string" } }, "allowed_placements": { "type": "array", "items": { "type": "string" } }, "allowed_regions": { "type": "array", "items": { "type": "string" } }, "approval_policy": { "$ref": "#/components/schemas/ApprovalPolicy" }, "budget_cents": { "type": [ "integer", "null" ], "format": "int64" }, "cost_centre": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "default": { "type": "boolean", "description": "The org's default \"Everyone\" team." }, "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "quota": { "$ref": "#/components/schemas/TeamQuota" }, "slug": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TeamMemberDto": { "type": "object", "required": [ "team_id", "user_id", "role", "added_by", "added_at" ], "properties": { "added_at": { "type": "string", "format": "date-time" }, "added_by": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "team_id": { "type": "string" }, "user_id": { "type": "string" } } }, "TeamQuota": { "type": "object", "description": "Team quota (docs/18 §4): a subset of the org's; absent = org quota only.", "properties": { "instances": { "type": [ "integer", "null" ], "format": "int64", "description": "Live instances in the team." }, "max_size": { "type": [ "string", "null" ], "description": "Largest size the team may create (hard limit, 422).", "example": "m2" }, "storage_gb": { "type": [ "integer", "null" ], "format": "int64", "description": "Provisioned storage (GB) across the team." } } }, "UpdateEnterpriseRequest": { "type": "object", "properties": { "committed_spend_cents": { "type": [ "integer", "null" ], "format": "int64" }, "consolidated_invoicing": { "type": [ "boolean", "null" ], "description": "One invoice on the parent for every subsidiary (billing, ZB-168)." }, "contract_end": { "type": [ "string", "null" ], "format": "date-time" }, "contract_start": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ] }, "net_terms_days": { "type": [ "integer", "null" ], "format": "int32", "description": "0, 15, 30, 45, 60 or 90." }, "po_number": { "type": [ "string", "null" ] }, "policies": { "type": [ "object", "null" ], "description": "Global policies applied to subsidiaries (free-form, e.g. `{\"mfa_required\": true}`)." } } }, "UpdateInstanceRequest": { "type": "object", "properties": { "engine_version": { "type": [ "string", "null" ], "description": "Target engine version (same engine; minor or major upgrade, never a downgrade)." }, "maintenance_window": { "type": [ "string", "null" ], "description": "`sun 03:00-05:00` (UTC, at least one hour); `null` restores the default.", "example": "sun 03:00-05:00" }, "name": { "type": [ "string", "null" ], "description": "New name (DNS label, unique in the project)." }, "placement": { "type": [ "string", "null" ], "description": "`shared`, `dedicated-node` or `secure` (secure needs a signed BAA). Moves the\ninstance to a cell of the matching tier." }, "size": { "type": [ "string", "null" ], "description": "Target size (`GET /v1/sizes`); runs the Resize saga.", "example": "m4" }, "storage_gb": { "type": [ "integer", "null" ], "format": "int32", "description": "Grow provisioned storage (GB). Storage never shrinks.", "minimum": 0 } } }, "UpdateMemberRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "example": "developer" } } }, "UpdateNetworkRequest": { "type": "object", "properties": { "allow_cidrs": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Client allow-list (1-50 CIDRs); `0.0.0.0/0` + `::/0` allows everyone.", "example": [ "203.0.113.0/24", "2001:db8::/32" ] }, "client_ca_pem": { "type": [ "string", "null" ], "description": "PEM CA certificate(s) client certificates must chain to; `null` disables mTLS." } } }, "UpdateProjectRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "team_id": { "type": [ "string", "null" ], "description": "Move the project (and the cost allocation of its instances) to another team." } } }, "UpdateRolePermissionsRequest": { "type": "object", "description": "Replace a predefined role's permission set.", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "org:read", "projects:read", "instances:read", "usage:read" ] } } }, "UpdateScimGroupRequest": { "type": "object", "properties": { "org_role": { "type": [ "string", "null" ], "description": "`admin`, `developer`, `billing`, `viewer`, `auditor`, `member`; empty clears." }, "team_role": { "type": [ "string", "null" ] } } }, "UpdateSsoConnectionRequest": { "type": "object", "properties": { "client_id": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ] }, "default_role": { "type": [ "string", "null" ] }, "issuer_url": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "status": { "type": [ "string", "null" ], "description": "`active` or `disabled`." } } }, "UpdateSsoDomainRequest": { "type": "object", "properties": { "connection_id": { "type": [ "string", "null" ], "description": "Empty string clears it." }, "enforce_sso": { "type": [ "boolean", "null" ] } } }, "UpdateTeamRequest": { "type": "object", "description": "Every field optional; `null` clears nullable settings (`cost_centre`,\n`budget_cents`). Budgets, quotas, policy and allowed lists need `members:manage`\non the org (org admin); a team lead may rename and set the cost centre.", "properties": { "allowed_engines": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_placements": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_regions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "approval_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApprovalPolicy" } ] }, "budget_cents": { "type": [ "integer", "null" ], "format": "int64" }, "cost_centre": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quota": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TeamQuota" } ] }, "slug": { "type": [ "string", "null" ] } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ], "description": "Re-enabling resets `failure_count`." }, "events": { "type": [ "array", "null" ], "items": { "type": "string" } }, "url": { "type": [ "string", "null" ] } } }, "UsageDto": { "type": "object", "required": [ "org_id", "group_by", "from", "to", "currency", "groups", "total_cost_cents", "source" ], "properties": { "currency": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "group_by": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/UsageGroupDto" } }, "org_id": { "type": "string" }, "source": { "type": "string", "description": "`metering` (hourly rollups) or `estimate` (control-plane shapes)." }, "to": { "type": "string", "format": "date-time" }, "total_cost_cents": { "type": "number", "format": "double" } } }, "UsageGroupDto": { "type": "object", "required": [ "key", "quantities", "cost_cents" ], "properties": { "by_instance": { "type": [ "object", "null" ], "description": "`group_by=day` only: quantity per instance and metric that day.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number", "format": "double" }, "propertyNames": { "type": "string" } }, "propertyNames": { "type": "string" } }, "cost_cents": { "type": "number", "format": "double", "description": "List-price cost in USD cents." }, "key": { "type": "string", "description": "Team id, cost centre, instance id, metric or day (`YYYY-MM-DD`); `unassigned`\nwhen untagged." }, "name": { "type": [ "string", "null" ], "description": "Team name when grouped by team." }, "quantities": { "type": "object", "description": "Quantity per metric (`cu_hours`, `storage_gb_hours`, `egress_gb`, ...).", "additionalProperties": { "type": "number", "format": "double" }, "propertyNames": { "type": "string" } } } }, "WebhookDeliveryDto": { "type": "object", "required": [ "id", "endpoint_id", "event_id", "event_type", "status", "attempts", "next_attempt_at", "created_at" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "endpoint_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_status_code": { "type": [ "integer", "null" ], "format": "int32" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "`pending`, `delivered` or `failed`." } } }, "WebhookDto": { "type": "object", "required": [ "id", "org_id", "url", "events", "enabled", "failure_count", "created_by", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } }, "failure_count": { "type": "integer", "format": "int32", "description": "Consecutive failed deliveries." }, "id": { "type": "string" }, "org_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } }, "WebhookSecretDto": { "type": "object", "required": [ "id", "secret" ], "properties": { "id": { "type": "string" }, "secret": { "type": "string" } } } }, "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer", "bearerFormat": "zb_...", "description": "Org-scoped API key, `Authorization: Bearer zb_...`" }, "dev_user": { "type": "apiKey", "in": "header", "name": "x-zb-dev-user", "description": "Development only (ZB_DEV_AUTH=1): simulate a user session by id (`usr_...`); `X-ZB-Dev-AAL: aal1` simulates a user with no second factor (aal1 session), `aal1-enrolled` an enrolled user who has not completed MFA (403 `mfa_required`). Any handler that lists `dev_user` also accepts a Kratos session cookie or token." }, "impersonation": { "type": "apiKey", "in": "header", "name": "x-zb-impersonation", "description": "Staff impersonation token from zb-admin-api (HS256, aud zb-api, <= 60 min). Read-mostly; every request is audited and answered with `ZB-Impersonated-By`." }, "session_cookie": { "type": "apiKey", "in": "cookie", "name": "ory_kratos_session", "description": "Ory Kratos session cookie (portal). Verified via `whoami`, cached 30 s." }, "session_token": { "type": "apiKey", "in": "header", "name": "X-Session-Token", "description": "Ory Kratos session token (CLI, MCP). Also accepted as a non-`zb_` bearer token." } } }, "tags": [ { "name": "system", "description": "Health and metadata" }, { "name": "catalogue", "description": "Engines, plans, sizes and regions" }, { "name": "orgs", "description": "Organizations" }, { "name": "projects", "description": "Projects group instances inside an org" }, { "name": "instances", "description": "Database instances (desired state)" }, { "name": "api-keys", "description": "Org-scoped API keys" }, { "name": "members", "description": "Org members, invites and seats (docs/18)" }, { "name": "service-accounts", "description": "Machine members with API keys; never a seat" }, { "name": "compliance", "description": "BAA and MFA policy (docs/10 §4)" }, { "name": "support", "description": "Customer-issued support access grants (docs/11 §9)" }, { "name": "events", "description": "Server-sent events for instance, org, quota, backup and migration events" }, { "name": "audit", "description": "Org audit log, CSV export and SIEM delivery (docs/11 §5)" }, { "name": "observability", "description": "Prometheus scrape endpoint per org (Datadog / Grafana Cloud)" }, { "name": "growth", "description": "Referral and promo credits, startup / OSS programme" }, { "name": "migrations", "description": "Move a database into an instance: connection string, upload or another instance" }, { "name": "webhooks", "description": "Signed webhooks for instance, quota, backup, migration and org events" }, { "name": "backups", "description": "Backups, restores (new instance or in-place), point-in-time recovery and backup settings" }, { "name": "teams", "description": "Teams, team members, quotas, budgets and approval policies (docs/18)" }, { "name": "approvals", "description": "Approval requests for creations above a team's threshold or budget" }, { "name": "usage", "description": "Usage and cost by team and cost centre; monthly cost report" }, { "name": "roles", "description": "Custom roles (Enterprise) and effective permissions" }, { "name": "enterprise", "description": "Enterprise accounts: subsidiaries, consolidated invoicing, contract terms, SSO" }, { "name": "sso", "description": "Enterprise SSO (OIDC, SAML via bridge), verified domains, SCIM provisioning tokens (Team+)" }, { "name": "account", "description": "The caller: profile, session assurance, organizations" }, { "name": "billing", "description": "Invoices and the org spending cap" }, { "name": "alerts", "description": "Quota, backup, instance and security alerts for the org" }, { "name": "network", "description": "Allow-list, mTLS client CA and custom domains" } ] }