{ "x-provenance": { "repo": "daytona/rlp", "source": "api/openapi.json", "generated-by": "make contracts" }, "components": { "schemas": { "AcceptPrivacyPolicyRequest": { "description": "Body of `POST /me/privacy-policy/accept`: the version the user was shown\nand accepts. It must equal the version the platform requires now, so an\nacceptance made against a status read from an older configuration (a\nrolling restart that changed the version, or a stale dashboard tab) is\nrefused instead of being recorded as consent to text the user never saw.", "properties": { "version": { "type": "string" } }, "required": [ "version" ], "type": "object" }, "AcceptedInvitationResponse": { "properties": { "org_id": { "format": "uuid", "type": "string" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "org_id", "role", "roles" ], "type": "object" }, "AccessTokenResp": { "description": "`POST \u2026/access-token` response.", "properties": { "access_token": { "description": "The sandbox access token (RFC 9068 `at+jwt`, ES256,\n`aud: daytona:toolbox`). Returned only here \u2014 never logged, never\nstored, never on any other endpoint (secrets rule).", "format": "password", "type": "string" }, "expires_at": { "description": "Absolute expiry (RFC 3339). The token cannot be refreshed \u2014 mint a\nfresh one through this route instead.", "format": "date-time", "type": "string" }, "operations": { "description": "The granted operations, canonical order \u2014 echoes what the token's\n`scope` claim carries.", "items": { "type": "string" }, "type": "array" }, "ports": { "description": "The granted ports (sorted, deduped), or null for all ports.", "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": [ "array", "null" ] }, "token_type": { "description": "Always `Bearer`.", "example": "Bearer", "type": "string" } }, "required": [ "access_token", "token_type", "expires_at", "operations" ], "type": "object" }, "AddGlobalRefReq": { "properties": { "note": { "type": [ "string", "null" ] }, "ref": { "type": "string" } }, "required": [ "ref" ], "type": "object" }, "AddProjectMemberReq": { "properties": { "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id" ], "type": "object" }, "AddProjectMembersBulkReq": { "properties": { "user_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "user_ids" ], "type": "object" }, "AddProjectServiceAccountReq": { "properties": { "service_account_id": { "format": "uuid", "type": "string" } }, "required": [ "service_account_id" ], "type": "object" }, "AddedProjectMembersResponse": { "properties": { "added": { "items": { "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "added" ], "type": "object" }, "AddedProjectServiceAccountsResponse": { "properties": { "added": { "items": { "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "added" ], "type": "object" }, "AdminImageSummary": { "properties": { "global": { "type": "boolean" }, "id": { "type": "string" }, "indexed_bytes": { "format": "int64", "type": "integer" }, "indexed_layers": { "format": "int64", "type": "integer" }, "layer_count": { "format": "int32", "type": [ "integer", "null" ] }, "manifest_name": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "status", "global", "indexed_layers", "indexed_bytes" ], "type": "object" }, "AdminPortalLinkReq": { "additionalProperties": false, "description": "`POST /orgs/:id/identity-providers/workos-admin-portal-link` body.", "properties": { "intent": { "$ref": "#/components/schemas/PortalIntent", "description": "`sso` configures an SSO connection; `dsync` a directory (SCIM) sync." } }, "required": [ "intent" ], "type": "object" }, "AdminPortalLinkResponse": { "properties": { "url": { "description": "The WorkOS Admin Portal URL. It expires five minutes after issuance.", "type": "string" } }, "required": [ "url" ], "type": "object" }, "ApiErrorCode": { "description": "Stable machine-readable codes emitted by `DAYTONA_API`.", "enum": [ "ORG_SUSPENDED", "PROJECT_BUDGET_EXCEEDED", "FEATURE_FLAG_DISABLED", "ENTITLEMENT_REQUIRED", "EMAIL_ACCESS_DENIED", "SIGNUP_NOT_INVITED", "OVERLOADED", "RATE_LIMITED", "LIMIT_EXCEEDED", "IF_MATCH_REQUIRED", "STALE_NETWORK_POLICY_REVISION", "NETWORK_POLICY_DOMAINS_REQUIRE_BLOCK_ALL", "NETWORK_POLICY_TRANSITION_IN_PROGRESS", "BILLING_DISABLED", "BILLING_UNREACHABLE", "SEARCH_NOT_CONFIGURED", "SEARCH_UNAVAILABLE", "UNSUPPORTED_VOLUME_TYPE", "BUCKET_CREATE_FAILED", "BUCKET_DELETE_FAILED", "BUCKET_NOT_EMPTY", "ORIGIN_IMPORT_ONLY", "READ_ONLY_UNSUPPORTED", "WORKLOAD_PLANE_ELSEWHERE", "MANAGEMENT_PLANE_ELSEWHERE", "INVOCATION_TIMEOUT", "INSTANCE_UNREACHABLE", "INSTANCE_CREATE_FAILED", "NOT_SUPPORTED_FOR_CLASS", "INVALID_FOR_SOURCE", "IDENTITY_NOT_FOUND", "WORKOS_SYNC_DISABLED", "USAGE_UNAVAILABLE", "BAD_RANGE", "BAD_RESOLUTION", "BAD_RUNNER", "BILLING_FORBIDDEN", "BILLING_ERROR", "BUILD_LOG_BATCH_TOO_LARGE", "PLACEMENT_UNAVAILABLE", "TOPOLOGY_NOT_READY", "PLACEMENT_ROUTER_REQUIRED", "PLACEMENT_AUTHORITY_REQUIRED", "CROSS_CELL_PLACEMENT_UNSUPPORTED", "SOURCE_AMBIGUOUS", "CREATE_OPERATION_RETIRED", "CREATE_BODY_TOO_LARGE", "PLACEMENT_CONTEXT_TOO_LARGE", "PLACEMENT_RECEIPT_TOO_LARGE", "NO_ACTIVE_RESERVATION", "NO_FREE_SLOT", "RESERVATION_NOT_FOUND", "NO_MAC_AVAILABLE", "AUTO_RESERVE_LIMIT_REACHED", "IDEMPOTENCY_KEY_REUSED", "INSUFFICIENT_BALANCE", "CHARGE_FAILED", "CHECKPOINT_PENDING", "NO_CHECKPOINT", "SECRETS_UNSUPPORTED_ON_MACOS", "CHECKPOINT_FAILED", "HARDWARE_REPLY_TOO_LARGE", "ECR_CREDENTIALS_INVALID", "ECR_ACCOUNT_MISMATCH", "ECR_OWNERSHIP_UNVERIFIABLE", "IMAGE_NOT_FOUND", "IMAGE_NOT_READY", "IMAGE_BUILD_FAILED", "DEFAULT_IMAGE_NOT_CONFIGURED", "IMAGE_FORMAT_OUTDATED", "IMAGE_CLASS_MISMATCH", "IMAGE_NAME_TAKEN", "IMAGE_NAME_RESERVED", "IDLE_OUT_OF_RANGE", "CREATE_TTL_OUT_OF_RANGE", "SNAPSHOT_NOT_FOUND", "SNAPSHOT_NOT_READY", "SNAPSHOT_CLASS_MISMATCH", "IMPORTED_KEY_ALWAYS_SYNCED", "KEY_SYNC_NOT_APPLICABLE", "V1_BRIDGE_UNAVAILABLE", "V1_SANDBOX_NOT_FOUND", "V1_SANDBOX_NOT_IMPORTABLE", "V1_BACKUP_REGISTRY_UNCONFIGURED", "V1_MIGRATION_DEFAULT_PROJECT_ONLY", "NOT_FOUND", "UNAUTHORIZED", "FORBIDDEN", "BAD_REQUEST", "PAYMENT_REQUIRED", "METHOD_NOT_ALLOWED", "REQUEST_TIMEOUT", "CONFLICT", "GONE", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_ENTITY", "TOO_MANY_REQUESTS", "SERVICE_UNAVAILABLE", "NOT_IMPLEMENTED", "BAD_GATEWAY", "GATEWAY_TIMEOUT", "INTERNAL_SERVER_ERROR" ], "type": "string", "x-daytona-open-enum": true }, "ArchivedServiceAccountResponse": { "properties": { "archived": { "format": "uuid", "type": "string" }, "revoked_keys": { "minimum": 0, "type": "integer" } }, "required": [ "archived", "revoked_keys" ], "type": "object" }, "AuditConfigReq": { "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ], "type": "object" }, "AuditConfigResponse": { "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ], "type": "object" }, "AuditLogRow": { "description": "The \u00a73.1 row as both adapters return it (\u00a73.5). `epoch_id`/`seq` ride to\nboth backends as ordinary fields for \u00a75.3 gap detection, but [`list`]\nstrips them from the tenant response (`TENANT_HIDDEN`). Shared with the\nOpenSearch publisher (\u00a73.6): the `_bulk` docs are serialized from this same\nstruct, which is what makes the two adapters' pages byte-identical for the\nsame rows.", "properties": { "action": { "type": "string" }, "actor_created_by": { "description": "The key's minting user, snapshotted at flush for human-minted project\nkeys and org keys (#941). NULL for non-key actors, for key actors\nwhose minter is unknown (CLI-minted keys, rows written before the\ncolumn existed, enrichment failure) \u2014 and masked to NULL unless the\ncaller holds `read:members`, the permission that guards member\nidentity (organization API keys never reveal it).", "format": "uuid", "type": [ "string", "null" ] }, "actor_email": { "type": [ "string", "null" ] }, "actor_key_id": { "format": "uuid", "type": [ "string", "null" ] }, "actor_key_prefix": { "type": [ "string", "null" ] }, "actor_kind": { "type": "string" }, "actor_service_account_id": { "description": "The key's owning service account, snapshotted at flush for SA-owned\nproject keys (#941), durable against the key row's ~7-day\npost-revocation reap. NULL for non-key actors \u2014 and for key actors\nwhose owner is unknown (rows written before the column existed,\nenrichment failure).", "format": "uuid", "type": [ "string", "null" ] }, "actor_user_id": { "format": "uuid", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "error_message": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "ip_address": { "type": [ "string", "null" ] }, "metadata": {}, "org_id": { "format": "uuid", "type": "string" }, "plane": { "type": "string" }, "project_id": { "format": "uuid", "type": [ "string", "null" ] }, "status_code": { "format": "int32", "type": "integer" }, "target_id": { "type": [ "string", "null" ] }, "target_type": { "type": "string" }, "user_agent": { "type": [ "string", "null" ] } }, "required": [ "id", "org_id", "plane", "actor_kind", "action", "target_type", "status_code", "created_at" ], "type": "object" }, "AuditLogsResponse": { "properties": { "logs": { "description": "The backend rows, passed through VERBATIM: an audit record is a\ncompliance artefact, so the query API never re-decodes (and can\nnever drop or reshape) what the store returned. `AuditLogRow` is the\ndocumented shape; both adapters produce it, and the store's own\nshape tests pin them to it.", "items": { "$ref": "#/components/schemas/AuditLogRow" }, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "logs" ], "type": "object" }, "AuditScenarios": { "description": "The supported audit scenarios, grouped by target type.", "properties": { "targets": { "description": "One entry per target type, sorted by target type.", "items": { "$ref": "#/components/schemas/AuditTargetScenario" }, "type": "array" } }, "required": [ "targets" ], "type": "object" }, "AuditTargetScenario": { "description": "Actions the audit log can record against one target type.", "properties": { "actions": { "description": "Actions that can appear against this target type, sorted\nalphabetically.", "example": [ "create", "delete", "start", "stop" ], "items": { "type": "string" }, "type": "array" }, "target_type": { "description": "Resource type the actions apply to \u2014 the `target_type` of the audit\nrows the query API returns.", "example": "sandbox", "type": "string" } }, "required": [ "target_type", "actions" ], "type": "object" }, "AutomaticTopUpRequest": { "description": "Request shape for PUT /orgs/{id}/billing/wallet/automatic-top-up. {\"disabled\": true} alone clears the rule; otherwise billing accepts the dollar amounts and applies its own validation ladder.", "properties": { "disabled": { "type": [ "boolean", "null" ] }, "target_amount": { "format": "double", "type": [ "number", "null" ] }, "threshold_amount": { "format": "double", "type": [ "number", "null" ] } }, "type": "object" }, "AutomaticTopUpResponse": { "properties": { "disabled": { "type": "boolean" }, "target_amount": { "format": "double", "type": "number" }, "threshold_amount": { "format": "double", "type": "number" } }, "required": [ "threshold_amount", "target_amount", "disabled" ], "type": "object" }, "BackfillResp": { "properties": { "considered": { "minimum": 0, "type": "integer" }, "failed": { "minimum": 0, "type": "integer" }, "indexed": { "minimum": 0, "type": "integer" }, "layers_written": { "minimum": 0, "type": "integer" }, "more": { "type": "boolean" } }, "required": [ "considered", "indexed", "failed", "layers_written", "more" ], "type": "object" }, "BalanceApplicableToResponse": { "properties": { "product_names": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "product_tags": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "BalanceListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BalanceResponse" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_page": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ], "type": "object" }, "BalanceNotificationRequest": { "description": "Request shape for PUT /orgs/{id}/billing/balance-notification. `enabled=false` may omit `threshold_amount`; billing requires the threshold only when enabling the rule and enforces its own $5-$50,000 bounds.", "properties": { "enabled": { "type": "boolean" }, "threshold_amount": { "format": "double", "type": "number" } }, "required": [ "enabled" ], "type": "object" }, "BalanceNotificationResponse": { "properties": { "enabled": { "type": "boolean" }, "threshold_amount": { "format": "double", "type": "number" } }, "required": [ "enabled", "threshold_amount" ], "type": "object" }, "BalanceResponse": { "properties": { "applicable_to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BalanceApplicableToResponse" } ] }, "balance_cents": { "format": "double", "type": "number" }, "created_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "granted_amount_cents": { "format": "double", "type": "number" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "name", "created_at", "balance_cents", "granted_amount_cents" ], "type": "object" }, "BillingAddressResponse": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "state": { "type": "string" } }, "required": [ "line1", "line2", "city", "state", "postal_code", "country" ], "type": "object" }, "BillingEmailRequest": { "properties": { "billing_email": { "type": [ "string", "null" ] } }, "type": "object" }, "BillingEmailResponse": { "properties": { "billing_email": { "type": [ "string", "null" ] }, "effective_email": { "type": [ "string", "null" ] } }, "type": "object" }, "BillingInfoResponse": { "properties": { "address": { "$ref": "#/components/schemas/BillingAddressResponse" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "tax_ids": { "items": { "$ref": "#/components/schemas/BillingTaxIdResponse" }, "type": "array" } }, "required": [ "name", "email", "phone", "address", "tax_ids" ], "type": "object" }, "BillingTaxIdResponse": { "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "BucketCredentialsReq": { "description": "Credentials for an external bucket, as project-secret NAMES. The values\nnever enter the API: the runner fetches them over the sealed channel.", "properties": { "access_key_secret": { "example": "AWS_KEY", "type": "string" }, "secret_key_secret": { "example": "AWS_SECRET", "type": "string" } }, "required": [ "access_key_secret", "secret_key_secret" ], "type": "object" }, "BucketOptionsReq": { "description": "The customer's own bucket, for a bucket volume with origin `external`.", "properties": { "credentials": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BucketCredentialsReq" } ] }, "endpoint": { "description": "Non-AWS S3 endpoint (`http(s)://\u2026`); absent or empty means AWS.", "type": [ "string", "null" ] }, "name": { "example": "corp-data", "type": "string" }, "origin": { "description": "Only `external` (the default) is accepted here. `platform` buckets are\nrequested by omitting this whole object, and `claimed` is import-only.", "type": [ "string", "null" ] }, "path_style": { "type": "boolean" }, "prefix": { "description": "Key prefix the volume is scoped to. A trailing `/` is added if missing.", "type": [ "string", "null" ] }, "region": { "description": "Absent => the deployment's default bucket region.", "type": [ "string", "null" ] } }, "required": [ "name" ], "type": "object" }, "BuildLogChunk": { "properties": { "data_base64": { "type": "string" }, "next_offset": { "type": "string" }, "start_offset": { "type": "string" } }, "required": [ "data_base64", "start_offset", "next_offset" ], "type": "object" }, "BuildLogDone": { "properties": { "cursor": { "type": [ "string", "null" ] }, "output_complete": { "type": "boolean" }, "reason": { "$ref": "#/components/schemas/BuildLogDoneReason" }, "status": { "type": "string" } }, "required": [ "status", "reason", "output_complete" ], "type": "object" }, "BuildLogDoneReason": { "enum": [ "terminal", "deadline", "not_applicable", "resource_deleted" ], "type": "string", "x-daytona-open-enum": true }, "BuildLogError": { "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "retryable": { "type": "boolean" }, "trace_id": { "type": [ "string", "null" ] } }, "required": [ "error", "code", "retryable" ], "type": "object" }, "BuildLogGap": { "properties": { "dropped_bytes": { "type": "string" }, "first_available_offset": { "type": "string" }, "reason": { "$ref": "#/components/schemas/BuildLogGapReason" }, "requested_offset": { "type": "string" } }, "required": [ "reason", "requested_offset", "first_available_offset", "dropped_bytes" ], "type": "object" }, "BuildLogGapReason": { "enum": [ "truncated" ], "type": "string", "x-daytona-open-enum": true }, "BuildLogSourceChanged": { "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "type": "object" }, "BuildLogState": { "description": "Public SSE payload schemas. The proxy emits these, not the API. Offsets are\ndecimal strings (raw bytes, not Unicode positions); event IDs are opaque\nparent-scoped cursors and occur only after delivered bytes/acknowledged gaps.", "properties": { "deadline": { "format": "date-time", "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "status" ], "type": "object" }, "BuildLogUnavailable": { "properties": { "reason": { "type": "string" } }, "required": [ "reason" ], "type": "object" }, "BuildLogsUrl": { "description": "Absolute canonical regional proxy URL for once, text-follow and SSE reads.", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "ChargeListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ChargeResponse" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ], "type": "object" }, "ChargeResponse": { "properties": { "amount_cents": { "format": "int64", "type": "integer" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": "string" }, "failure_message": { "type": [ "string", "null" ] }, "has_pdf": { "type": "boolean" }, "has_stripe_invoice": { "type": "boolean" }, "id": { "type": "string" }, "receipt_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "stripe_invoice_url": { "type": [ "string", "null" ] } }, "required": [ "id", "amount_cents", "currency", "status", "description", "created_at", "has_pdf", "has_stripe_invoice" ], "type": "object" }, "ClassInfo": { "description": "A class-registry row, as served by GET /network-classes and /disk-classes.\n\n`tier` (migration 0056, PLAN-HOST-CLASS-TIERS.md) is a single global rank\nper dimension (`1` = lowest). Exposed for discovery + e2e assertions; the\nplacement mechanic lives on the runner, so no client consumes it yet.", "properties": { "id": { "example": "standard", "type": "string" }, "name": { "type": "string" }, "tier": { "format": "int32", "type": "integer" } }, "required": [ "id", "name", "tier" ], "type": "object" }, "Config": { "description": "The `/config` response body.", "properties": { "analytics_url": { "description": "Public base URL of the rlp-analytics spending service\n(PLAN-ANALYTICS-SERVICE.md), set by the operator and trimmed of a\ntrailing slash. `null` when unset \u2014 or when the value is not an\n`http(s)://host[:port][/path]` base (see `analytics_base_url`) \u2014 the\ndashboard then shows no spending analytics. The URL itself is\npublished (unlike the billing service's) because the browser calls\nrlp-analytics directly, with its own bearer; the dashboard passes it\nthrough `safeUrl` like `toolbox_url`.", "type": [ "string", "null" ] }, "api_url": { "description": "Public base URL of this API when the deployment advertises one.", "type": [ "string", "null" ] }, "billing_enabled": { "description": "Whether the member-facing billing surface is wired\n(PLAN-BILLING-WALLET.md). A boolean rather than the URL because the\nbrowser never talks to rlp-billing directly (D1) \u2014 it only needs to know\nwhether to render Billing.", "type": "boolean" }, "build_sha": { "description": "Full commit SHA this API was built from; `unknown` when unstamped.", "type": "string" }, "build_time": { "description": "RFC 3339 UTC instant the build ran, for example\n`2026-10-02T14:03:11Z`; `unknown` when unstamped.", "type": "string" }, "docs_url": { "description": "Public documentation site URL for this deployment.", "type": [ "string", "null" ] }, "featureFlags": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FeatureFlagsPublicConfig", "description": "Feature-flag override echo (PLAN-FEATURE-FLAGS.md D4). `null` unless the\noperator forced at least one catalog key on for this deployment \u2014\ndashboards whose management plane is unavailable (dev-auth preview\nsessions) still see forced features through this block. Flag keys are\nnot secrets (they live in the repo's catalog)." } ] }, "oidc": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OidcPublicConfig", "description": "OIDC login parameters for the SPA. `null` when browser login is not\nconfigured for this deployment." } ] }, "posthog": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PosthogPublicConfig", "description": "PostHog product-analytics keys for the dashboard\n(PLAN-POSTHOG-ANALYTICS.md D1). `null` unless browser analytics is\nconfigured for this deployment. The project API key is a public,\nwrite-only key by design (D6); exposing it here matches upstream and\nleaks nothing." } ] }, "ssh_gateway": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SshGatewayConfig", "description": "SSH gateway endpoint clients should use. `null` when the deployment does\nnot publish one." } ] }, "toolbox_url": { "description": "Toolbox proxy base URL the browser should use. A deployment-specific\nbrowser override wins over the general proxy URL when both are set.", "type": [ "string", "null" ] }, "version": { "description": "Platform version this API was built as (PLAN-BUILD-IDENTITY.md): the\nlatest published release, for example `2.0.0-alpha.1`; `0.0.0-dev` for\nan unstamped build. The same value `GET /health` reports.", "type": "string" } }, "required": [ "billing_enabled", "version", "build_sha", "build_time" ], "type": "object" }, "CpuArchAvailability": { "description": "Availability of one CPU architecture across the covered regions.", "properties": { "available": { "description": "`regions` is non-empty.", "type": "boolean" }, "id": { "example": "amd64", "type": "string" }, "regions": { "description": "Covered regions with a live linux-pool runner of this arch, sorted.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "available", "regions" ], "type": "object" }, "CpuCatalogRegion": { "description": "One region the catalog answer covers, with what a fully unhinted create\nresolves to there (D6).", "properties": { "default_arch": { "description": "The region's `default_cpu_arch`, or `amd64` when unset (the\nbare-subject convention).", "example": "amd64", "type": "string" }, "default_type": { "description": "The region's `default_cpu_type`, when set: autofill pins an unhinted\ncreate to this slug. Its own `cpu_types` entry says whether it is live.", "type": [ "string", "null" ] }, "id": { "example": "us-west-1", "type": "string" } }, "required": [ "id", "default_arch" ], "type": "object" }, "CpuCatalogResp": { "description": "`GET /cpu-catalog` body.", "properties": { "arches": { "description": "Always exactly two entries, `amd64` then `arm64`.", "items": { "$ref": "#/components/schemas/CpuArchAvailability" }, "type": "array" }, "cpu_types": { "description": "One entry per registry row, in `GET /cpu-types` order\n(`cpu_arch, tier, id`).", "items": { "$ref": "#/components/schemas/CpuTypeAvailability" }, "type": "array" }, "regions": { "description": "Every region the answer covers, in catalog order.", "items": { "$ref": "#/components/schemas/CpuCatalogRegion" }, "type": "array" } }, "required": [ "regions", "arches", "cpu_types" ], "type": "object" }, "CpuTypeAvailability": { "description": "One `cpu_types` registry row with its availability across the covered\nregions. The four registry fields are `GET /cpu-types`'s, unchanged.", "properties": { "available": { "description": "`exact_regions \u222a fallback_regions` is non-empty.", "type": "boolean" }, "cpu_arch": { "example": "amd64", "type": "string" }, "exact_regions": { "description": "Covered regions where a live linux-pool runner declares this slug as\nits `cpu_type`, sorted.", "items": { "type": "string" }, "type": "array" }, "fallback_regions": { "description": "Covered regions where a live linux-pool runner lists this slug in\n`cpu_serves` (a higher same-arch tier lazy-polling it) and none\ndeclares it, sorted. A region is in at most one of the two lists.", "items": { "type": "string" }, "type": "array" }, "id": { "example": "zen5", "type": "string" }, "name": { "type": "string" }, "tier": { "format": "int32", "type": "integer" } }, "required": [ "id", "name", "cpu_arch", "tier", "available", "exact_regions", "fallback_regions" ], "type": "object" }, "CpuTypeInfo": { "description": "A `cpu_types` registry row, as served by GET /cpu-types.\n\n`tier` (migration 0056, PLAN-HOST-CLASS-TIERS.md) is a per-arch rank\n(`1` = lowest). It is exposed for discovery + e2e assertions; the placement\nmechanic itself lives on the runner (lazy-poll shared-durable fallback), so\nno client consumes `tier` yet.", "properties": { "cpu_arch": { "example": "amd64", "type": "string" }, "id": { "example": "zen5", "type": "string" }, "name": { "type": "string" }, "tier": { "format": "int32", "type": "integer" } }, "required": [ "id", "name", "cpu_arch", "tier" ], "type": "object" }, "CreateEndpointReq": { "properties": { "port": { "format": "int32", "type": "integer" }, "public": { "type": "boolean" } }, "required": [ "port" ], "type": "object" }, "CreateGlobalRegionReq": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "CreateGpuSandboxFromSnapshotReq": { "additionalProperties": false, "description": "Only the fields a checkpoint restore honours today. `volumes`,\n`object_store_mounts`, `egress_policy`, `secrets` and `persistent` are not\nfields of this body at all \u2014 a GPU checkpoint restore cannot apply them, and\nPLAN-CREATION-SHAPE \u00a72 makes that a shape fact (`deny_unknown_fields`), not\na runtime 400.", "properties": { "create_ttl": { "format": "int64", "type": [ "integer", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "labels": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "lifecycle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleReq" } ] }, "name": { "type": [ "string", "null" ] }, "ports": { "items": { "$ref": "#/components/schemas/PortRequest" }, "type": "array" }, "region": { "type": [ "string", "null" ] }, "snapshot": { "type": "string" }, "wait": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "snapshot" ], "type": "object" }, "CreateGpuSandboxReq": { "additionalProperties": false, "properties": { "cpu": { "format": "double", "type": [ "number", "null" ] }, "create_ttl": { "format": "int64", "type": [ "integer", "null" ] }, "env": { "additionalProperties": { "type": "string" }, "description": "Sandbox-specific environment variables (real values, verbatim). Names\nmust satisfy the shared guest-env rules: POSIX-ish identifiers, and\nnames in the platform's reserved namespaces (the daemon's own `RLP`\nprefix followed by an underscore, and `DAYTONA_` other than\n`DAYTONA_SANDBOX_TOKEN`, `DAYTONA_API_URL`, `DAYTONA_OTEL_ENDPOINT` and\n`DAYTONA_DOCKER_START`) fail the create with 400 naming the key.", "propertyNames": { "type": "string" }, "type": "object" }, "gpu": { "items": { "type": "string" }, "type": "array" }, "gpu_host": { "format": "int32", "minimum": 0, "type": "integer" }, "idempotency_key": { "type": [ "string", "null" ] }, "image": { "type": "string" }, "labels": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "lifecycle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleReq" } ] }, "mem_max_mib": { "description": "Per-sandbox memory limit in MiB; same semantics as `vcpus_max`.", "format": "int32", "type": [ "integer", "null" ] }, "mem_mib": { "format": "int32", "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "ports": { "items": { "$ref": "#/components/schemas/PortRequest" }, "type": "array" }, "region": { "description": "Target region slug (PLAN-REGIONS.md). Absent => resolved default.", "type": [ "string", "null" ] }, "scratch_max_mib": { "description": "Per-sandbox disk limit in MiB: the writable layer's size. Same semantics\nas `vcpus_max`; a disk-snapshot restore requires it equal to the\ncaptured disk, or absent.", "format": "int32", "type": [ "integer", "null" ] }, "scratch_mib": { "format": "int32", "type": [ "integer", "null" ] }, "secrets": { "items": { "type": "string" }, "type": "array" }, "user": { "type": [ "string", "null" ] }, "vcpus": { "format": "int32", "type": [ "integer", "null" ] }, "vcpus_max": { "description": "Per-sandbox vCPU limit in whole vCPUs (PLAN-BURSTABLE-ONLY.md): the boot\nshape and the CPU ceiling. Absent => the system cap. Set equal to the\nrequest for a fixed shape.", "format": "int32", "type": [ "integer", "null" ] }, "wait": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "image" ], "type": "object" }, "CreateImageCaptureReq": { "properties": { "idle": { "description": "Idle-retention window in seconds for an ANONYMOUS image: the image is\ndeleted once this long has passed without a sandbox being created from\nit (every create from the image restarts the clock). Only without\n`name` (a named image is permanent; `idle` with `name` is `400`). The\nsame rule as `POST /images`: omitted or `-1` \u21d2 the server maximum\n(`DAYTONA_ANON_IMAGE_MAX_IDLE`, 7 days by default); `1 \u2026 max` \u21d2 that\nwindow; `0`, `< -1` or `> max` \u21d2 `400 IDLE_OUT_OF_RANGE` (the body\ncarries `max`). Promote the image (`PATCH /images/{id}`) to keep it.", "example": 86400, "format": "int64", "type": [ "integer", "null" ] }, "name": { "example": "my-image", "type": [ "string", "null" ] } }, "type": "object" }, "CreateImageJson": { "properties": { "cpu_arch": { "description": "CPU architecture to build for \u2014 `amd64` or `arm64`. Absent => the\nregion's default (PLAN-ARM64.md \u00a72.2).\n\nThe same Dockerfile produces a different image per architecture, so\nthis is part of the build's content key: an amd64 and an arm64 build of\none Dockerfile are two builds that never adopt each other\n(PLAN-BUILD-DEDUPE.md). It also pins which runners may serve the build.", "example": "arm64", "type": [ "string", "null" ] }, "dockerfile": { "description": "An inline, self-contained Dockerfile body to build (no `COPY`/`ADD` of\nlocal files \u2014 use the `multipart/form-data` variant to upload a real\nbuild context). The API synthesizes the trivial single-file context for\nyou. Mutually exclusive with `source`.", "example": "FROM alpine:3.20\nRUN apk add --no-cache curl\n", "type": [ "string", "null" ] }, "idle": { "description": "Idle-retention window in seconds for an ANONYMOUS image: the image is\ndeleted once this long has passed without a sandbox being created from\nit (every create from the image restarts the clock). Only without\n`name` (a named image is permanent; `idle` with `name` is `400`).\nAccepted: omitted or `-1` \u21d2 the server maximum\n(`DAYTONA_ANON_IMAGE_MAX_IDLE`, 7 days by default); `1 \u2026 max` \u21d2 that\nwindow. `0`, values below `-1`, and values above the maximum \u21d2\n`400 IDLE_OUT_OF_RANGE` (the body carries `max`).", "example": 86400, "format": "int64", "type": [ "integer", "null" ] }, "name": { "example": "my-base-image", "type": [ "string", "null" ] }, "region": { "description": "Target region for the build (PLAN-REGIONS.md). Absent => resolved\ndefault. The image is homed in this region; other regions replicate it\non first use.", "type": [ "string", "null" ] }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImageSource", "description": "{\"type\":\"registry\",\"ref\":\"node:20\"} | {\"type\":\"named\",...}\n\nMutually exclusive with `dockerfile`; exactly one is required." } ] } }, "type": "object" }, "CreateImageMultipart": { "description": "Schema-only: the `multipart/form-data` variant of `POST /images` (a\nDockerfile build with an uploaded context). Mirrors `parse_multipart_image`\n\u2014 keep the two in sync.", "properties": { "context": { "description": "The build-context tar.", "format": "binary", "type": "string" }, "cpu_arch": { "description": "CPU architecture to build for (`amd64` | `arm64`). Absent/empty =>\nthe region's default. Sent as a text part.", "type": [ "string", "null" ] }, "dockerfile": { "description": "Path of the Dockerfile within the context. Defaults to `Dockerfile`.", "type": [ "string", "null" ] }, "idle": { "format": "int64", "type": [ "integer", "null" ] }, "name": { "example": "my-base-image", "type": [ "string", "null" ] }, "region": { "description": "Target region for the build (PLAN-REGIONS.md). Absent/empty => resolved\ndefault.", "type": [ "string", "null" ] } }, "required": [ "context" ], "type": "object" }, "CreateImageResp": { "description": "Response for `POST /images`: the enqueued build. Field order is\nalphabetical to keep the wire bytes identical to the former\n`serde_json::json!` construction (BTreeMap key order).", "properties": { "image_id": { "example": "img_7fJk2mQpXv9dLc3RtY", "type": "string" }, "job_id": { "description": "The build's CURRENT attempt. For an adopted image this is the job that\nalready produced it, not a job this call enqueued \u2014 so it is not\nevidence that a build was started. `null` when the image was reused\nand no build job is on record for it (an anonymous registry import\nwhose pull job has been pruned): poll `GET /images/{id}` for status\ninstead \u2014 the image id, not a job id, is the handle to wait on.", "format": "uuid", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "region": { "description": "Home region the image is built in (PLAN-REGIONS.md).", "type": "string" }, "status": { "description": "The build's status. `pending` for a build this call enqueued, and\n`building` when it joined one already in flight \u2014 but `ready` when the\nimage was ADOPTED from an identical build that had already finished\n(PLAN-BUILD-DEDUPE.md), in which case no build runs and the image is\nusable immediately. Poll `GET /images` (or the job) for progress.", "example": "pending", "type": "string" } }, "required": [ "image_id", "region", "status" ], "type": "object" }, "CreateInvitationResponse": { "properties": { "accept_url": { "description": "The invitation link, carrying the single-use `dtni_` token \u2014 present\nONLY when the api has no SMTP mailer configured, so a deployment\nwithout email can hand the link over out of band\n(PLAN-INVITATION-EMAIL.md D7). `null` when the invitation email was\nhanded to the mailer: the secret then has exactly one copy. Absolute\nwhen the api knows the dashboard's URL, else the dashboard-relative\npath `/dashboard/user/invitations?token=\u2026`.", "type": [ "string", "null" ] }, "email": { "type": "string" }, "expires_at": { "description": "When the invitation stops being acceptable (RFC 3339).", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "org_id", "email", "role", "roles", "expires_at" ], "type": "object" }, "CreateInviteReq": { "properties": { "email": { "type": "string" }, "roles": { "description": "Absent \u21d2 `[\"developer\"]`; an explicit empty array is a 400.", "items": { "type": "string" }, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "email" ], "type": "object" }, "CreateKeyReq": { "properties": { "expires_at": { "description": "Optional expiry (D11); must be in the future. Absent = never expires.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "project_permissions": { "description": "Required (PLAN-API-KEY-PERMISSIONS.md D4): the key's permissions are ALWAYS\nexplicit \u2014 no defaults, no implied full-power set, and at least one\npermission is required (D18); an ABSENT field or empty array is a 400.\n`Option` in Rust only so the handler can answer that specific 400; the\ncontract marks it required so generated clients cannot omit it.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "service_account_id": { "description": "PLAN-SERVICE-ACCOUNTS.md D6: mint this key for a service account in the\nproject's org rather than for the calling user; requires\n`write:service_accounts` (issue #926). Absent = the caller owns the\nkey, exactly as today.", "format": "uuid", "type": [ "string", "null" ] }, "sync_to_v1": { "description": "Whether the v1 \u2194 v2 key sync may copy this key to Daytona v1. Absent\n= `true`. Only a key a person mints in the organization's `default`\nproject is ever copied; elsewhere the field is ignored and the\nresponse says `false`. A v1 copy can read every sandbox, snapshot and\nregistry of the organization on v1, which has no read permissions;\n`false` keeps the key on this platform only. Changeable later with\n`PATCH /api-keys/{id}`.", "type": [ "boolean", "null" ] } }, "required": [ "project_permissions" ], "type": "object" }, "CreateMacosSandboxReq": { "additionalProperties": false, "description": "POST /sandboxes/macos body. `deny_unknown_fields`: fields of other classes\n(volumes, egress, docker, gpu, resource requests and limits, \u2026) are named\n400s. There is no size: every macOS sandbox gets a fixed half of the Mac's\ncores and memory (each limit equal to its request), reported on the\nsandbox once it runs.", "properties": { "auto_renew": { "description": "With `reservation: \"new\"` only: whether the bought lease renews itself\nwhile a sandbox is active on it. Defaults to the organization's\nauto-reserve setting.", "type": [ "boolean", "null" ] }, "create_ttl": { "description": "Seconds the sandbox may take to reach `running` (default\n`DAYTONA_CREATE_TTL_DEFAULT`, `-1` = the server max). Past it the\nsandbox is deleted. The budget runs while the sandbox waits for a Mac,\nincluding one whose lease this create bought: that lease stays bought\nand charged when the sandbox is deleted.", "format": "int64", "type": [ "integer", "null" ] }, "env": { "additionalProperties": { "type": "string" }, "description": "Sandbox-specific environment variables. Names must satisfy the shared\nguest-env rules.", "propertyNames": { "type": "string" }, "type": "object" }, "idempotency_key": { "description": "Idempotency key; the `Idempotency-Key` header wins if both are set.\nIt also covers a lease the create buys: a retry never buys two.", "type": [ "string", "null" ] }, "image": { "description": "The macOS base image, by name or `img_\u2026` id: one of the global macOS\nimages the deployment seeds from `DAYTONA_MACOS_GOLDEN_IMAGES`\n(`base-macos` unless configured otherwise). The Mac clones the base it\nholds under that name.", "example": "base-macos", "type": "string" }, "labels": { "additionalProperties": { "type": "string" }, "description": "Control-plane-only labels.", "propertyNames": { "type": "string" }, "type": "object" }, "lifecycle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleReq", "description": "Sandbox lifecycle policy (idle stop/delete budgets and a wall-clock\ndeadline). The `pause` action and wake-on-request are linux-only; use\n`POST /sandboxes/{id}/pause` to pause a macOS sandbox. The project's\nlifecycle defaults do not apply to a macOS sandbox: a field that this\nrequest does not set gets the platform default." } ] }, "name": { "description": "Optional sandbox name (defaults to `sandbox-`).", "type": [ "string", "null" ] }, "persistent": { "description": "Keep the disk across stop and lease end: every stop writes a\ncheckpoint, and `start` restores it on any Mac the organization leases.", "type": "boolean" }, "ports": { "items": { "$ref": "#/components/schemas/PortRequest" }, "type": "array" }, "region": { "description": "Target region slug. Absent => the named reservation's region, else the\nresolved default.", "type": [ "string", "null" ] }, "reservation": { "description": "Which Mac lease admits the sandbox. Absent: a free slot on one of the\norganization's leases in the region; with none free and the\norganization's auto-reserve setting on, the create buys a 24-hour\nlease (`origin: auto`, `auto_renew: true`) and the sandbox waits in\n`pending` until a Mac takes it. `\"new\"`: always buy a lease for this\nsandbox (no opt-in needed). A reservation id: exactly that lease.", "example": "new", "type": [ "string", "null" ] }, "secrets": { "description": "Not supported on macOS (there is no egress substitution); a non-empty\nlist is a 400 `secrets_unsupported_on_macos`.", "items": { "type": "string" }, "type": "array" }, "wait": { "description": "Seconds to hold the response until the sandbox is `running`, capped at\n`DAYTONA_CREATE_WAIT_MAX` (3 by default). Absent holds for the cap; `0`\nanswers at once; a negative value answers 400. The response carries the\nstatus when the hold ends: `running` if the sandbox got there in time,\nas a warm Mac's claim usually does, otherwise its status then, such as\n`pending`.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "image" ], "type": "object" }, "CreateOrgKeyReq": { "properties": { "expires_at": { "description": "Optional expiry (D11); must be in the future. Absent = never expires.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Required \u2014 org keys have no dashboard auto-mint flow, so there is no\nimplicit-\"default\" convenience (or rotation semantics) here. `Option`\nin Rust only for the specific 400; required in the contract.", "type": "string" }, "org_permissions": { "description": "Required, validated against the ORG vocabulary (D4/D18/D19): explicit,\nat least one, project permissions are unknown values here.", "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "name", "org_permissions" ], "type": "object" }, "CreateOrgReq": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateProjectReq": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateReservationReq": { "additionalProperties": false, "description": "POST /reservations body.", "properties": { "auto_renew": { "description": "Renew the lease near each period end while a macOS sandbox is active\non it. Defaults to the organization's auto-reserve setting.", "type": [ "boolean", "null" ] }, "region": { "description": "Region slug whose Macs to lease from.", "example": "local", "type": "string" }, "vms_per_mac": { "description": "macOS VMs this lease allows at once (1 or 2; default 2, Apple's limit).", "example": 2, "format": "int32", "type": [ "integer", "null" ] } }, "required": [ "region" ], "type": "object" }, "CreateSandboxFromSnapshotReq": { "additionalProperties": false, "description": "POST /sandboxes/from-snapshot body (PLAN-CREATION-SHAPE \u00a72).\n\nShared fields only \u2014 no cpu/memory/disk/spot/env/user (those are fixed by\nthe captured memory image). `deny_unknown_fields` makes the compile-time\nabsence of those fields a runtime 400 for callers who send them.\nOnly the fields a memory restore honours today. `volumes` and `secrets`\nare not fields of this body until `restore_vm_internal` supports them \u2014 a\nsilently dropped field is worse than a 400, and PLAN-CREATION-SHAPE \u00a72\nmakes the difference a shape fact (`deny_unknown_fields`) rather than a\nruntime guard. Neither is `persistent`: the restored sandbox inherits the\npersistence of the sandbox the snapshot was captured from.", "properties": { "create_ttl": { "format": "int64", "type": [ "integer", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "labels": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "lifecycle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleReq" } ] }, "name": { "type": [ "string", "null" ] }, "ports": { "items": { "$ref": "#/components/schemas/PortRequest" }, "type": "array" }, "region": { "type": [ "string", "null" ] }, "snapshot": { "description": "Snapshot name or `snap_\u2026` id. Required.", "type": "string" }, "wait": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "snapshot" ], "type": "object" }, "CreateSandboxReq": { "additionalProperties": false, "description": "POST /sandboxes body (PLAN-CREATION-SHAPE \u00a72).\n\n`image` is a string: a registered name or a typed `img_\u2026` id; omitted, the\ncell's platform default image (PLAN-PLATFORM-IMAGES.md).\nDockerfile-in-create, registry refs, and the old `VmImageInput` object\nforms are removed \u2014 use `POST /images` to build first.", "properties": { "cpu": { "format": "double", "type": [ "number", "null" ] }, "cpu_arch": { "type": [ "string", "null" ] }, "cpu_type": { "type": [ "string", "null" ] }, "create_ttl": { "description": "Budget in seconds for the sandbox to reach `running` before being\ndeleted. Omitted => `DAYTONA_CREATE_TTL_DEFAULT` (3600). `-1` =>\n`DAYTONA_CREATE_TTL_MAX` (86400). `0`/`<-1`/`>MAX` => 400.", "format": "int64", "type": [ "integer", "null" ] }, "env": { "additionalProperties": { "type": "string" }, "description": "Sandbox-specific environment variables (real values, verbatim). Names\nmust be POSIX-ish identifiers (`[A-Za-z_][A-Za-z0-9_]*`); names in the\nplatform's reserved namespaces (the daemon's own `RLP` prefix followed\nby an underscore, and `DAYTONA_*` other than `DAYTONA_SANDBOX_TOKEN`,\n`DAYTONA_API_URL`, `DAYTONA_OTEL_ENDPOINT` and `DAYTONA_DOCKER_START`)\nfail the create with 400 naming the key.", "propertyNames": { "type": "string" }, "type": "object" }, "idempotency_key": { "type": [ "string", "null" ] }, "image": { "description": "Image name or `img_\u2026` id. Omit to boot the platform default image.", "type": [ "string", "null" ] }, "labels": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "lifecycle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleReq" } ] }, "mem_max_mib": { "description": "Per-sandbox memory limit in MiB; same semantics as `vcpus_max`.", "format": "int32", "type": [ "integer", "null" ] }, "mem_mib": { "format": "int32", "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "network_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkPolicyInput" } ] }, "persistent": { "type": "boolean" }, "ports": { "items": { "$ref": "#/components/schemas/PortRequest" }, "type": "array" }, "region": { "type": [ "string", "null" ] }, "scratch_max_mib": { "description": "Per-sandbox disk limit in MiB: the writable layer's size. Same semantics\nas `vcpus_max`; a disk-snapshot restore requires it equal to the\ncaptured disk, or absent.", "format": "int32", "type": [ "integer", "null" ] }, "scratch_mib": { "format": "int32", "type": [ "integer", "null" ] }, "secrets": { "items": { "type": "string" }, "type": "array" }, "spot": { "type": "boolean" }, "user": { "type": [ "string", "null" ] }, "vcpus": { "format": "int32", "type": [ "integer", "null" ] }, "vcpus_max": { "description": "Per-sandbox vCPU limit in whole vCPUs (PLAN-BURSTABLE-ONLY.md): the boot\nshape and the CPU ceiling. Absent => the system cap. Set equal to the\nrequest for a fixed shape.", "format": "int32", "type": [ "integer", "null" ] }, "volumes": { "items": { "$ref": "#/components/schemas/VolumeMountReq" }, "type": "array" }, "wait": { "description": "Server-hold seconds. Omitted => `DAYTONA_CREATE_WAIT_MAX` (3).\n`0` => respond immediately. `<0` => 400.", "format": "int64", "type": [ "integer", "null" ] } }, "type": "object" }, "CreateServiceAccountReq": { "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "roles": { "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "name", "roles" ], "type": "object" }, "CreateSnapshotReq": { "additionalProperties": false, "properties": { "name": { "example": "my-snapshot", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateSnapshotResp": { "description": "Snapshot-capture response: the pending snapshot + its capture job.\n(Fields are declared alphabetically to match the former `json!` response \u2014\nserde_json without `preserve_order` serializes maps in key order.)", "properties": { "job_id": { "format": "uuid", "type": "string" }, "kind": { "description": "The captured kind: `full` (linux) or `checkpoint` (gpu).", "type": "string" }, "name": { "type": "string" }, "snapshot_id": { "description": "The snapshot's typed id (`snap_\u2026`), the same spelling `GET /snapshots`\nlists and `POST /sandboxes/from-snapshot` accepts.", "example": "snap_7fJk2mQpXv9dLc3RtY", "type": "string" }, "status": { "description": "Always `pending` \u2014 capture runs asynchronously on the VM's runner.", "type": "string" }, "vm_id": { "description": "External id (external VM id (base58 body with optional region tag, or a bare UUID)) of the source VM.", "type": "string" } }, "required": [ "job_id", "kind", "name", "snapshot_id", "status", "vm_id" ], "type": "object" }, "CreateVmResp": { "description": "Response for `POST /sandboxes` \u2014 the fresh create, the idempotent replay, and the\nsnapshot-restore paths all share this shape. Field order is alphabetical to\nkeep the wire bytes identical to the former `serde_json::json!` construction.", "properties": { "access_token": { "description": "The sandbox's data-plane access token, returned ONCE at create time.\nNull on an idempotent replay (the original create already returned\nit). While the deployment's data-plane compat window is open (the\nship default) this is the non-expiring per-VM `dtnv_\u2026` token; once\nthe deployment flips compat off it is a full-grant sandbox JWT whose\nexpiry rides in `access_token_expires_at` (PLAN-SANDBOX-TOKEN-JWT.md).", "format": "password", "type": [ "string", "null" ] }, "access_token_expires_at": { "description": "Expiry of `access_token` (RFC 3339). Null while the compat window has\n`access_token` carrying the non-expiring `dtnv_` credential, and null\non an idempotent replay; set once the compat flip makes\n`access_token` a sandbox JWT \u2014 mint a fresh token via\n`POST /sandboxes/{id}/access-token` before it lapses.", "format": "date-time", "type": [ "string", "null" ] }, "create_ttl_expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "image": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VmArtifactRef", "description": "The image the sandbox boots \u2014 for a create without `image`, the\nplatform default it resolved to (PLAN-PLATFORM-IMAGES.md). The same\n`{id, name}` as `GET /sandboxes/{id}`. Omitted for a sandbox restored\nfrom a memory snapshot." } ] }, "job_id": { "description": "Create/restore job id. Null on an idempotent replay.", "format": "uuid", "type": [ "string", "null" ] }, "name": { "description": "Sandbox name (caller-provided or the generated `sandbox-`).", "type": "string" }, "reservation_id": { "description": "macOS only: the external id of the Mac lease whose slot admitted the\nsandbox \u2014 one of the organization's leases, or the one this create\nbought. Omitted for every other class.", "type": [ "string", "null" ] }, "status": { "description": "Initial lifecycle status \u2014 `pending`, or the sandbox's current status on\nan idempotent replay.", "example": "pending", "type": "string" }, "toolbox_proxy_url": { "description": "The sandbox's own region's toolbox proxy base URL, the same value\n`GET /sandboxes/{id}` carries \u2014 exec/fs/preview traffic must target\nthis, not a global proxy.", "type": "string" }, "vm_id": { "description": "External sandbox id: base58-encoded UUID with a `-` suffix\n(e.g. `7fJk2mQpXv9dLc3RtY-use1`); a bare UUID in single-region mode.", "type": "string" }, "wait_cap": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "name", "status", "toolbox_proxy_url", "vm_id", "wait_cap" ], "type": "object" }, "CreateVolumeReq": { "properties": { "bucket": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BucketOptionsReq", "description": "Bring-your-own bucket. Present => the volume points at a bucket you\nalready own (origin `external`); absent on a `bucket` volume => rlp\ncreates and owns the bucket (origin `platform`)." } ] }, "name": { "example": "training-data", "type": "string" }, "size_gb": { "description": "Per-volume scratch size (GiB); absent => 100. Disk volumes only \u2014\nsupplying it on a bucket volume is a 400.", "format": "int32", "type": [ "integer", "null" ] }, "type": { "description": "`disk` (the default) or `bucket`. `blockmount` is accepted as the\npre-rename spelling of `disk`.", "type": [ "string", "null" ] } }, "required": [ "name" ], "type": "object" }, "CreateWindowsSandboxReq": { "additionalProperties": false, "properties": { "cpu": { "format": "double", "type": [ "number", "null" ] }, "create_ttl": { "format": "int64", "type": [ "integer", "null" ] }, "env": { "additionalProperties": { "type": "string" }, "description": "Sandbox-specific environment variables defined at create time. Names\nmust satisfy the shared guest-env rules: POSIX-ish identifiers, and\nnames in the platform's reserved namespaces (the daemon's own `RLP`\nprefix followed by an underscore, and `DAYTONA_` other than\n`DAYTONA_SANDBOX_TOKEN`, `DAYTONA_API_URL`, `DAYTONA_OTEL_ENDPOINT` and\n`DAYTONA_DOCKER_START`) fail the create with 400 naming the key.", "propertyNames": { "type": "string" }, "type": "object" }, "idempotency_key": { "type": [ "string", "null" ] }, "image": { "type": "string" }, "labels": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "lifecycle": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleReq" } ] }, "mem_max_mib": { "description": "Per-sandbox memory limit in MiB; same semantics as `vcpus_max`.", "format": "int32", "type": [ "integer", "null" ] }, "mem_mib": { "format": "int32", "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "persistent": { "type": "boolean" }, "ports": { "items": { "$ref": "#/components/schemas/PortRequest" }, "type": "array" }, "region": { "type": [ "string", "null" ] }, "scratch_max_mib": { "description": "Per-sandbox disk limit in MiB: the writable layer's size. Same semantics\nas `vcpus_max`; a disk-snapshot restore requires it equal to the\ncaptured disk, or absent.", "format": "int32", "type": [ "integer", "null" ] }, "scratch_mib": { "format": "int32", "type": [ "integer", "null" ] }, "secrets": { "items": { "type": "string" }, "type": "array" }, "spot": { "type": "boolean" }, "vcpus": { "format": "int32", "type": [ "integer", "null" ] }, "vcpus_max": { "description": "Per-sandbox vCPU limit in whole vCPUs (PLAN-BURSTABLE-ONLY.md): the boot\nshape and the CPU ceiling. Absent => the system cap. Set equal to the\nrequest for a fixed shape.", "format": "int32", "type": [ "integer", "null" ] }, "wait": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "image" ], "type": "object" }, "CreatedOrgApiKeyResponse": { "properties": { "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "key_prefix": { "type": "string" }, "name": { "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "org_permissions": { "items": { "type": "string" }, "type": "array" }, "token": { "type": "string" } }, "required": [ "id", "name", "org_id", "key_prefix", "token", "org_permissions" ], "type": "object" }, "CreatedOrganizationResponse": { "properties": { "assignable_project_permissions": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "org_permissions": { "items": { "type": "string" }, "type": "array" }, "personal": { "type": "boolean" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "personal", "role", "roles", "org_permissions", "assignable_project_permissions" ], "type": "object" }, "CreatedProjectApiKeyResponse": { "properties": { "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "key_prefix": { "type": "string" }, "key_suffix": { "type": "string" }, "name": { "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_permissions": { "items": { "type": "string" }, "type": "array" }, "service_account_id": { "format": "uuid", "type": [ "string", "null" ] }, "sync_to_v1": { "description": "Whether the v1 \u2194 v2 key sync keeps a copy of this key on Daytona v1;\nsame meaning as on `ProjectApiKeyResponse`.", "type": "boolean" }, "token": { "type": "string" } }, "required": [ "id", "name", "project_id", "key_prefix", "key_suffix", "token", "project_permissions", "sync_to_v1" ], "type": "object" }, "CredentialListResp": { "description": "`GET \u2026/nats-credentials` body: the runner's credentials, live and revoked.", "properties": { "credentials": { "items": { "$ref": "#/components/schemas/CredentialRow" }, "type": "array" } }, "required": [ "credentials" ], "type": "object" }, "CredentialRevokedResp": { "description": "`DELETE \u2026/nats-credentials/{cred_id}` body.", "properties": { "id": { "format": "uuid", "type": "string" }, "ok": { "type": "boolean" }, "revoked": { "type": "boolean" } }, "required": [ "ok", "id", "revoked" ], "type": "object" }, "CredentialRow": { "description": "A credential as listed: no hash, no token.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "last_used_at": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "revoked_at": { "format": "date-time", "type": [ "string", "null" ] }, "runner_id": { "type": "string" } }, "required": [ "id", "runner_id", "created_at" ], "type": "object" }, "CredentialsRevokedResp": { "description": "`DELETE \u2026/nats-credentials` body: how many live credentials were revoked\n(zero is still a 200 \u2014 the end state holds either way).", "properties": { "ok": { "type": "boolean" }, "revoked": { "minimum": 0, "type": "integer" }, "runner_id": { "type": "string" } }, "required": [ "ok", "runner_id", "revoked" ], "type": "object" }, "CurrentApiKey": { "description": "What an API-key caller learns about the credential it presented.", "properties": { "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "expires_at": { "description": "RFC 3339 expiry; null = never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "key_prefix": { "description": "Leading characters of the plaintext token, for recognizable display.", "type": [ "string", "null" ] }, "key_suffix": { "description": "Trailing characters of the plaintext token; null for keys minted\nbefore the suffix was recorded.", "type": [ "string", "null" ] }, "last_used_at": { "description": "Best-effort, flushed periodically \u2014 may lag the request that reads it.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "org_name": { "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "project_permissions": { "description": "The key's explicit project permissions, canonical order.", "items": { "type": "string" }, "type": "array" }, "service_account_id": { "description": "The owning service account, when the key was minted for one. Only the\nid: `service_accounts` is management-plane state that workload cells\ndo not replicate, so a name would be null there and set on home.", "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "name", "project_id", "project_name", "org_id", "org_name", "project_permissions" ], "type": "object" }, "DeclinedInvitationResponse": { "properties": { "declined": { "format": "uuid", "type": "string" } }, "required": [ "declined" ], "type": "object" }, "DeepHealth": { "description": "GET /health/deep readiness body: JetStream probe result plus the wedge/shed\nobservability counters (PLAN-NATS-HYGIENE, PLAN-OVERLOAD-SHEDDING,\nPLAN-SELF-CORDON-DEADLOCK, PLAN-JETSTREAM-CRITICAL-ONLY).", "properties": { "consecutive_publish_timeouts": { "format": "int64", "minimum": 0, "type": "integer" }, "consecutive_slow_publishes": { "format": "int64", "minimum": 0, "type": "integer" }, "create_stuck_pending_failures": { "description": "Total creates the create-expiry reaper (events::maintenance) has ever\ndeleted before they reached `running`. Historical field name kept so the\nhealth surface stays stable; a nonzero rate means creates are timing out\nbefore becoming live right now.", "format": "int64", "minimum": 0, "type": "integer" }, "db": { "description": "`ok` | `unhealthy` (migration ledger missing or empty) \u2014 the same\nDB/migration probe `/health` runs, now also covered here (found by\nreview, 2026-08-25: previously absent). Draining is reported only in\nthe outer `status` field, never here \u2014 this field reflects the DB\nprobe alone, so it stays `ok` even while draining if the DB itself is\nfine (cubic review, 2026-08-27: the field never actually emits a\n\"degraded\" value). Probed concurrently with `nats`\n(PLAN-HEALTH-LIVENESS.md) \u2014 neither should wait on the other, and a\nwedged one must not delay reporting the other's real state.", "type": "string" }, "jobs_consumer_ack_pending": { "description": "Fleet-wide JetStream consumer health, summed across every consumer on\nthe JOBS stream (2026-08-27): distinguishes \"queue is deep because\nload is high\" from \"queue is deep because runners have stopped\nacking\" \u2014 no other signal here made that distinction before.", "format": "int64", "minimum": 0, "type": "integer" }, "jobs_consumer_pending": { "format": "int64", "minimum": 0, "type": "integer" }, "jobs_consumer_redelivered": { "format": "int64", "minimum": 0, "type": "integer" }, "jobs_consumer_waiting": { "format": "int64", "minimum": 0, "type": "integer" }, "last_publish_ms": { "format": "int64", "minimum": 0, "type": "integer" }, "max_queued_creates": { "format": "int64", "minimum": 0, "type": "integer" }, "nats": { "description": "`ok` when JetStream answered the bounded `$JS.API.INFO` probe.", "type": "string" }, "otel": { "description": "OTel pipeline state.", "type": "string" }, "publish_timeouts": { "format": "int64", "minimum": 0, "type": "integer" }, "queued_creates": { "format": "int64", "minimum": 0, "type": "integer" }, "reaper_herd_guard_trips": { "description": "Reaper ticks (cumulative, this process) on which the herd guard\nrefused to mark runners `lost` because EVERY online runner was stale\nat once \u2014 an observer/transport outage signature, not fleet death\n(issue #1205). Nonzero and climbing means the api can hear NATS but no\nrunner heartbeat is arriving: check the bus, the runners' NATS\nconnectivity, and the runner herd-guard threshold configuration.", "format": "int64", "minimum": 0, "type": "integer" }, "reaper_lost_mark_gate": { "description": "Whether the reaper is currently allowed to mark runners `lost` from\n`last_seen_at` staleness (issue #1205): `unbound` (the heartbeat lane\nis not consuming \u2014 nothing refreshes `last_seen_at`), `settling` (it\n(re)bound less than one stale window ago; lost-marking is suppressed\nuntil the runners have heartbeated through the new subscription) or\n`armed`. A process that stays `unbound`/`settling` for minutes has a\nwedged or flapping runner-event lane.", "example": "armed", "type": "string" }, "redis": { "description": "Rate-limit Redis state (PLAN-AUTH-RATE-LIMITS.md \u00a72.6):\n`ok` | `degraded` (PING failed/timed out \u2014 brute-force protection is\nsilently off, fail-open) | `unconfigured` (rate-limit storage disabled\non this deployment).\nNever flips the overall status \u2014 the limiter fails open by design.", "example": "unconfigured", "type": "string" }, "retention_alarms": { "description": "Managed streams whose retention config drifted from desired. Non-empty\nis the alarm that was missing during both retention-drift incidents.", "items": { "type": "string" }, "type": "array" }, "self_cordoned_runners": { "format": "int64", "type": "integer" }, "shedding": { "type": "boolean" }, "slow_publishes": { "format": "int64", "minimum": 0, "type": "integer" }, "status": { "description": "`draining` (publish-watchdog trip) | `unhealthy` (DB/migration-ledger\nprobe failed) | `degraded` (NATS probe failed) | `warn` (retention\nalarms present) | `ok` \u2014 checked in that priority order, draining and\nunhealthy first since those matter most for a deploy decision.", "example": "ok", "type": "string" }, "trace_id": { "description": "Present only on a 503 (draining / bad DB / degraded NATS), same as\nevery `ApiError` body \u2014 this endpoint's success/error bodies share\none documented shape (`DeepHealth`) that `ApiError`'s generic\n`{\"error\": \"...\"}` envelope can't carry without dropping the rest of\nthese fields (api/AGENTS.md's ApiError section documents this as the\none narrow exception), so the trace ID is attached here directly via\nthe same helper `error::envelope` uses rather than through `ApiError`.", "type": [ "string", "null" ] } }, "required": [ "status", "nats", "db", "otel", "redis", "publish_timeouts", "consecutive_publish_timeouts", "slow_publishes", "consecutive_slow_publishes", "last_publish_ms", "queued_creates", "max_queued_creates", "shedding", "self_cordoned_runners", "reaper_lost_mark_gate", "reaper_herd_guard_trips", "create_stuck_pending_failures", "jobs_consumer_ack_pending", "jobs_consumer_redelivered", "jobs_consumer_waiting", "jobs_consumer_pending", "retention_alarms" ], "type": "object" }, "DeleteImageResp": { "description": "DELETE /images/:id response.", "properties": { "image_id": { "example": "img_7fJk2mQpXv9dLc3RtY", "type": "string" }, "status": { "description": "Always `deleted`.", "type": "string" } }, "required": [ "image_id", "status" ], "type": "object" }, "DeleteSnapshotResp": { "description": "DELETE /snapshots/:id response.", "properties": { "snapshot_id": { "example": "snap_7fJk2mQpXv9dLc3RtY", "type": "string" }, "status": { "description": "Always `deleted`.", "type": "string" } }, "required": [ "snapshot_id", "status" ], "type": "object" }, "DeleteVolumeResp": { "description": "Response for `DELETE /volumes/{id}`.", "properties": { "id": { "format": "uuid", "type": "string" }, "state": { "description": "`deleting` while accepted work is pending; `deleted` once complete.", "example": "deleting", "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "DeletedOrganizationResponse": { "properties": { "deleted": { "format": "uuid", "type": "string" } }, "required": [ "deleted" ], "type": "object" }, "DeletedProjectResponse": { "properties": { "deleted": { "format": "uuid", "type": "string" } }, "required": [ "deleted" ], "type": "object" }, "DryRunNarrowingResponse": { "properties": { "dry_run": { "type": "boolean" }, "revoked_keys": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "dry_run", "revoked_keys" ], "type": "object" }, "EffectiveGpuPolicyDto": { "properties": { "ephemeral": { "$ref": "#/components/schemas/EffectiveLifecycleDto" } }, "required": [ "ephemeral" ], "type": "object" }, "EffectiveLifecycleDto": { "properties": { "idle_timeout_secs": { "format": "int32", "type": [ "integer", "null" ] }, "on_idle_timeout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction" } ] }, "on_timeout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction" } ] }, "timeout_capped": { "type": "boolean" }, "timeout_secs": { "format": "int32", "type": [ "integer", "null" ] }, "timeout_source": { "$ref": "#/components/schemas/TimeoutSource" }, "wake_on_request": { "type": "boolean" } }, "required": [ "timeout_secs", "on_timeout", "timeout_source", "timeout_capped", "idle_timeout_secs", "on_idle_timeout", "wake_on_request" ], "type": "object" }, "EffectiveLimit": { "properties": { "effective": { "description": "The value enforced; `null` means unlimited. Always present.", "format": "int64", "type": [ "integer", "null" ] }, "source": { "$ref": "#/components/schemas/LimitSource", "description": "Where the value comes from: assigned on the org, the platform default, or no limit at all." } }, "required": [ "effective", "source" ], "type": "object" }, "EffectiveLinuxPolicyDto": { "properties": { "ephemeral": { "$ref": "#/components/schemas/EffectiveLifecycleDto" }, "persistent": { "$ref": "#/components/schemas/EffectiveLifecycleDto" } }, "required": [ "ephemeral", "persistent" ], "type": "object" }, "EffectiveMacosPolicyDto": { "properties": { "ephemeral": { "$ref": "#/components/schemas/EffectiveLifecycleDto" }, "persistent": { "$ref": "#/components/schemas/EffectiveLifecycleDto" } }, "required": [ "ephemeral", "persistent" ], "type": "object" }, "EffectivePolicyDto": { "properties": { "gpu": { "$ref": "#/components/schemas/EffectiveGpuPolicyDto" }, "linux": { "$ref": "#/components/schemas/EffectiveLinuxPolicyDto" }, "macos": { "$ref": "#/components/schemas/EffectiveMacosPolicyDto", "description": "A macOS create does not take the project's lifecycle defaults, so this\nblock always shows the platform defaults." }, "windows": { "$ref": "#/components/schemas/EffectiveWindowsPolicyDto" } }, "required": [ "linux", "windows", "gpu", "macos" ], "type": "object" }, "EffectiveWindowsPolicyDto": { "properties": { "ephemeral": { "$ref": "#/components/schemas/EffectiveLifecycleDto" }, "persistent": { "$ref": "#/components/schemas/EffectiveLifecycleDto" } }, "required": [ "ephemeral", "persistent" ], "type": "object" }, "EndpointListResp": { "description": "Response envelope for the endpoint list.", "properties": { "endpoints": { "items": { "$ref": "#/components/schemas/PreviewEndpoint" }, "type": "array" } }, "required": [ "endpoints" ], "type": "object" }, "EntitlementsResponse": { "description": "`GET /orgs/{id}/entitlements` \u2014 the handler returns this struct, so the\nserved JSON and the documented schema cannot drift apart.", "properties": { "enforced": { "description": "Whether entitlements are enforced at admission; while off, every\nkey reads as entitled for gating purposes.", "type": "boolean" }, "entitlements": { "additionalProperties": { "type": "boolean" }, "description": "Every catalog key, `true` when the organization holds it.", "propertyNames": { "type": "string" }, "type": "object" } }, "required": [ "enforced", "entitlements" ], "type": "object" }, "EphemeralPolicyReq": { "additionalProperties": false, "properties": { "idle_timeout_secs": { "default": null, "format": "int64", "type": [ "integer", "null" ] }, "timeout_secs": { "default": null, "format": "int64", "type": [ "integer", "null" ] } }, "type": "object" }, "ErrorBody": { "description": "The JSON error envelope every non-2xx response carries.", "properties": { "central_api_url": { "type": [ "string", "null" ] }, "code": { "$ref": "#/components/schemas/ApiErrorCode" }, "current": { "format": "int64", "type": [ "integer", "null" ] }, "flag": { "type": [ "string", "null" ] }, "invocation_id": { "type": [ "string", "null" ] }, "limit": { "type": [ "string", "null" ] }, "max": { "format": "int64", "type": [ "integer", "null" ] }, "message": { "example": "bad request: cpu>0, mem_mib>=1 and scratch_mib>=1 required", "type": "string" }, "replacement": { "type": [ "string", "null" ] }, "retry_after_secs": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "source": { "example": "DAYTONA_API", "type": "string" }, "trace_id": { "example": "0af7651916cd43dd8448eb211c80319c", "type": [ "string", "null" ] }, "workload_api_url": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "source" ], "type": "object" }, "EventsTicket": { "description": "`POST /events/{edge}/ticket` response.", "properties": { "expires_in_ms": { "description": "Milliseconds until the ticket expires unused.", "format": "int64", "minimum": 0, "type": "integer" }, "subprotocol": { "description": "The subprotocol to negotiate alongside the ticket.", "type": "string" }, "ticket": { "description": "Opaque, single-use; present it as the `rlp.ticket.`\nsubprotocol on the upgrade.", "type": "string" } }, "required": [ "ticket", "expires_in_ms", "subprotocol" ], "type": "object" }, "FeatureFlagsPublicConfig": { "description": "The `featureFlags` block of [`Config`] \u2014 camelCase like `posthog`\n(the Daytona dashboard's config dialect; daytona serves the same idea as\n`forcedFeatureFlags`).", "properties": { "forced": { "description": "Catalog keys forced on for this deployment (`*` already expanded), in\ncatalog order.", "items": { "type": "string" }, "type": "array" } }, "required": [ "forced" ], "type": "object" }, "ForkReq": { "properties": { "memory": { "description": "Fork the memory too (default `true`): the fork continues the source's\nrunning processes. `false` clones only the disk (an instant RBD\ncopy-on-write clone; a running source's filesystem is frozen briefly, the\nVM is never paused) and the fork boots fresh. A `stopped` source is\nalways forked disk-only (PLAN-FORK-DISK.md).", "type": [ "boolean", "null" ] }, "name": { "description": "Optional name for the fork (defaults to \"-fork\").", "type": [ "string", "null" ] } }, "type": "object" }, "ForkResp": { "description": "Response for `POST /sandboxes/{id}/fork`. Field order is alphabetical to keep the\nwire bytes identical to the former `serde_json::json!` construction.", "properties": { "forked_from": { "description": "External id of the source sandbox.", "type": "string" }, "status": { "description": "Always `pending`. A memory fork lands `paused`, a disk-only fork lands\n`stopped`; a fork of a RUNNING source is then brought up automatically.", "example": "pending", "type": "string" }, "toolbox_proxy_url": { "description": "The fork's own region's toolbox proxy base URL (a fork lands in its\nsource's region), the same value `GET /sandboxes/{id}` carries.", "type": "string" }, "vm_id": { "description": "External id of the NEW fork.", "type": "string" } }, "required": [ "forked_from", "status", "toolbox_proxy_url", "vm_id" ], "type": "object" }, "GlobalRefDeleteResp": { "properties": { "ref": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "ref", "removed" ], "type": "object" }, "GlobalRefEntry": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "note": { "type": [ "string", "null" ] }, "ref": { "type": "string" } }, "required": [ "ref", "created_at" ], "type": "object" }, "GlobalRegionInfo": { "description": "A cached Geo group or the Global root (Earth, ID `earth`): a broad placement\nselector expanded to one Edge descendant at create time. Geo groups are\narbitrary abstract groups of Macros, not geographic constraints. The\n`global_regions` catalog and this DTO retain their technical names. `id` is the\nslug (shares the create-time `region` selector namespace with regions.id; a\nDB trigger forbids collisions).", "properties": { "id": { "type": "string" }, "member_count": { "description": "Number of eligible Edge descendants (for discovery via GET /global-regions).\n\n**Fleet discovery eligibility** (issue #1867): tenant-visible descendants\nthat are active, routable and opted into broad placement, INDEPENDENT of\nwhether the process answering happens to serve them itself. It is\ninventory, not capacity, and not a promise that a create will be\naccepted. [`Self::selectable`] describes the answering API's local\nexecution scope, not the capabilities of a separately configured router.\n\n`None` means \"this process cannot count them\", not \"zero\". A `central`\ndeployment owns the groups but no concrete region rows, so membership\nlives in the cells and is not locally computable; reporting `0` there\ntold the operator every group was empty.", "minimum": 0, "type": [ "integer", "null" ] }, "name": { "type": "string" }, "selectable": { "description": "Whether this API cell serves an eligible member of the group.\n\nDeliberately distinct from [`Self::member_count`]: the count is a\nfleet-wide inventory fact, this is an execution fact about the API\nanswering the request. A control plane serving no regions reports positive\ncounts with `selectable: false`. That does not forbid a client from using\na separately configured shared workload router: that path requires a\npositive fleet count and its own supported routing configuration.\n\nGlobal/Geo creates must use the shared router's binding/receipt protocol\neven when this flag is true. Capacity, class compatibility, artifact\nlocality and admission still apply; this flag is not an execution grant.", "type": "boolean" } }, "required": [ "id", "name" ], "type": "object" }, "GlobalRegistryMeta": { "description": "One global credential's metadata. Never the password.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "host": { "description": "Normalized registry host (Docker Hub aliases collapse to\n`index.docker.io`).", "example": "ghcr.io", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "import_only": { "description": "Import-only (v1 migration): the credential serves only pulls of images\nthe platform imported from Daytona v1, never a tenant's own pull of\nthe same ref.", "type": "boolean" }, "kind": { "description": "Auth kind: `basic`, `ghcr`, `gcr` or `ecr`.", "type": "string" }, "repository_prefix": { "description": "Repository prefix the credential is scoped to; empty covers every\nrepository on the host.", "example": "daytonaio/sandbox", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "host", "repository_prefix", "kind", "username", "import_only", "created_at", "updated_at" ], "type": "object" }, "GroupView": { "properties": { "best_free_mem_mib": { "description": "Best SINGLE-member free memory, from the cached routing snapshot. This\nis the pre-flight's actual capacity gate: a shape must fit on one\nmember, so the max \u2014 not the sum \u2014 decides.", "format": "int64", "type": "integer" }, "breaker_open": { "type": "boolean" }, "breaker_reason": { "type": [ "string", "null" ] }, "cpu_arch": { "type": "string" }, "cpu_type": { "type": [ "string", "null" ] }, "disk_class": { "type": "string" }, "group_id": { "type": "string" }, "healthy_members": { "description": "Members that are online, uncordoned and gate-open. Below the configured\nhealthy-member floor the pre-flight spills every create to the standard\nqueue.", "format": "int64", "type": "integer" }, "members": { "description": "Runners assigned to the group.", "format": "int64", "type": "integer" }, "network_class": { "type": "string" }, "oldest_pending_ms": { "description": "Age of the oldest create still queued on this group's subject, in ms.\nThis is the breaker's primary signal.", "format": "int64", "type": [ "integer", "null" ] }, "pending": { "format": "int64", "type": "integer" }, "recruits": { "description": "Runners borrowed into this group by Tier-2 spillover. They are released\nonly by a runner restart (no runtime unbind exists).", "items": { "type": "string" }, "type": "array" }, "region_id": { "type": "string" }, "seq": { "format": "int32", "type": "integer" }, "total_free_mem_mib": { "description": "Summed free memory across healthy members: the group's total headroom.\nOperator signal for \"is this group about to start spilling\".", "format": "int64", "type": "integer" }, "vslots": { "description": "How many of the 16384 virtual slots map here \u2014 the group's share of the\nimage population.", "format": "int64", "type": "integer" } }, "required": [ "group_id", "region_id", "seq", "cpu_arch", "network_class", "disk_class", "members", "healthy_members", "vslots", "best_free_mem_mib", "total_free_mem_mib", "pending", "breaker_open", "recruits" ], "type": "object" }, "GroupsResponse": { "properties": { "enabled_regions": { "description": "Per-region routing flag (`regions.affinity_enabled`).", "items": { "type": "string" }, "type": "array" }, "groups": { "items": { "$ref": "#/components/schemas/GroupView" }, "type": "array" } }, "required": [ "enabled_regions", "groups" ], "type": "object" }, "Health": { "description": "GET /health liveness body. Beside the probe result it carries the build\nidentity of the answering process (PLAN-BUILD-IDENTITY.md): the same three\nvalues `GET /config` publishes, so a stack's version can be read from the\nunauthenticated probe alone.", "properties": { "build_sha": { "description": "Full commit SHA this binary was built from; `unknown` when unstamped.", "example": "0123456789abcdef0123456789abcdef01234567", "type": "string" }, "build_time": { "description": "RFC 3339 UTC instant the build ran; `unknown` when unstamped.", "example": "2026-10-02T14:03:11Z", "type": "string" }, "status": { "example": "ok", "type": "string" }, "version": { "description": "Platform version this binary was built as (the latest published\nrelease); `0.0.0-dev` for an unstamped build.", "example": "2.0.0-alpha.1", "type": "string" } }, "required": [ "status", "version", "build_sha", "build_time" ], "type": "object" }, "ImageConversion": { "description": "`POST /images/{id}/convert` (#3032): the result.", "properties": { "converted": { "description": "`true` when this call started or joined a conversion; `false` when the\nimage was already at the current format and nothing was enqueued.", "type": "boolean" }, "from_format": { "description": "The image's format before the call (`ImageListItem.format_version`).", "example": 1, "format": "int32", "type": "integer" }, "image_id": { "example": "img_7fJk2mQpXv9dLc3RtY", "type": "string" }, "status": { "description": "The image's status after the call: `pending`/`building` while it\nconverts, or its own status when it was already at the current format.", "example": "pending", "type": "string" }, "to_format": { "description": "The format the conversion targets: the current one.", "example": 2, "format": "int32", "type": "integer" } }, "required": [ "image_id", "from_format", "to_format", "status", "converted" ], "type": "object" }, "ImageLayersResp": { "properties": { "exclusive_bytes": { "format": "int64", "type": "integer" }, "image_id": { "type": "string" }, "layer_count": { "minimum": 0, "type": [ "integer", "null" ] }, "layers": { "items": { "$ref": "#/components/schemas/LayerEntry" }, "type": "array" }, "manifest_name": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "total_bytes": { "format": "int64", "type": "integer" } }, "required": [ "image_id", "name", "status", "layers", "total_bytes", "exclusive_bytes" ], "type": "object" }, "ImageListItem": { "properties": { "anonymous": { "type": "boolean" }, "available_in": { "description": "Every region that holds a copy of this image's current manifest right\nnow (PLAN-ARTIFACT-RESIDENCY.md \"The copy record\"); the home region is\nlisted only while its own copy is there. Empty until the build\nfinishes, and after every copy has been evicted. A create in a region\nnot listed here waits while that region fetches the image from the\nglobal artifact store. A registry import whose export is not yet\ndurable, or a create of one that carries volumes, is pulled from the\nregistry again instead; any other create that carries volumes is\nrefused there.\n\nNot a column: filled in by one batched query per page.", "items": { "type": "string" }, "type": "array" }, "bytes": { "description": "Captured erofs layer size in bytes; null until the build completes.", "format": "int64", "type": [ "integer", "null" ] }, "class": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "default": { "description": "The platform default image: what `POST /sandboxes` without `image`\nboots. Only ever true on a platform image.", "type": "boolean" }, "deprecated": { "description": "A deprecated platform image: no new creates by name, not listed by\n`GET /images?platform=\u2026`; its `img_\u2026` id still resolves.", "type": "boolean" }, "error": { "description": "Build failure reason; null unless `status` is `failed`.", "type": [ "string", "null" ] }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "format_outdated": { "description": "`format_version` is below the current format. Such an image converts\non its first Linux sandbox create (which waits `queued` meanwhile) or\nahead of time with `POST /images/{id}/convert`; every other door\n(GPU, Windows, functions, a `POST /images` named source) refuses it\nwith `409 IMAGE_FORMAT_OUTDATED` until then. Derived, never stored.", "type": "boolean" }, "format_version": { "description": "The image's format generation \u2014 how its artifact is stored\n(`images::format`): `1` = stored by Daytona v1 (the v1 \u2192 v2\nmigration registers these; nothing pulled yet), `2` = the platform's\ncurrent artifact. `status` is the pipeline state of the artifact at\nthis format.", "example": 2, "format": "int32", "type": "integer" }, "id": { "example": "img_7fJk2mQpXv9dLc3RtY", "type": "string" }, "imported_from": { "$ref": "#/components/schemas/ImportedFrom", "description": "Where the image was imported from (an archived Daytona v1 sandbox's\nbackup, #3035): `{platform: \"v1\", id: }`. Absent (never `null`) when\nthe image was not imported, so the item and the page row share one\noptional, non-nullable shape." }, "layer_count": { "format": "int32", "type": [ "integer", "null" ] }, "manifest_name": { "description": "Resolved erofs manifest name; null until the build completes.", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "origin": { "type": "string" }, "platform": { "description": "A platform image: published by the platform operator, owned by no\nproject, and bootable by every project (PLAN-PLATFORM-IMAGES.md). A\nproject's own image of the same name takes precedence for that\nproject. Platform images cannot be renamed, converted or deleted\nthrough this API.", "type": "boolean" }, "region": { "description": "Home region the image was built in (PLAN-REGIONS.md).", "type": "string" }, "retention": { "example": "permanent", "type": "string" }, "source": { "description": "The build source as stored (`ImageSource` JSON)." }, "status": { "example": "ready", "type": "string" } }, "required": [ "anonymous", "class", "created_at", "id", "origin", "region", "retention", "status", "format_version", "format_outdated", "available_in", "platform", "default", "deprecated" ], "type": "object" }, "ImagePageRow": { "allOf": [ { "$ref": "#/components/schemas/ImageListItem" }, { "properties": { "created_at": { "format": "date-time", "type": "string" }, "cursor": { "description": "This row's opaque keyset token \u2014 pass it as `?cursor=` to resume the list\nimmediately after this row. Not a column: the handler fills it via the\nsame encoder that builds `next_cursor`.", "type": "string" } }, "required": [ "created_at", "cursor" ], "type": "object" } ], "description": "An `ImageListItem` plus the keyset fields, mirroring `VmPageRow` /\n`SnapshotPageRow`. `created_at` + `cursor` on the wire let a client merge the\nimage streams of several regional cells and resume ONE of them mid-page\n(PLAN-DASHBOARD-REGIONS.md \u00a75.1). They live on the page row, not on\n`ImageListItem`, because `GET /images/{id}` returns a bare item and has\nnothing to page." }, "ImageSource": { "oneOf": [ { "description": "Pull from a registry, e.g. {\"type\":\"registry\",\"ref\":\"node:20\"}", "properties": { "ref": { "type": "string" }, "type": { "enum": [ "registry" ], "type": "string", "x-daytona-exact-enum": "discriminator" } }, "required": [ "ref", "type" ], "type": "object" }, { "description": "Build from a Dockerfile context stored in the `contexts` object store.", "properties": { "context_object": { "description": "NATS object-store key for the context tar", "type": "string" }, "dockerfile": { "description": "path to Dockerfile within the context (default \"Dockerfile\")", "type": "string" }, "type": { "enum": [ "dockerfile" ], "type": "string", "x-daytona-exact-enum": "discriminator" } }, "required": [ "context_object", "type" ], "type": "object" }, { "description": "Reference an already-built named image by its project-local name.\n\nThe runner resolves it as `manifests/prj-/.json` \u2014\nthe alias a registry import writes for its image name \u2014 and refuses a\nname that is not a single path component or a job with no\n`project_id` (PLAN-IMAGE-NAMESPACE-OWNERSHIP.md). The API itself no\nlonger sends this variant for a ready image: every create route and\n`POST /images` resolves a caller's name against the owning project's\nrow and publishes `Manifest { name: }` instead, so\nthe variant reaches a runner only from the functions dispatcher's\nbare-ref fallback for an `image_ref` with no image row (#1727).", "properties": { "name": { "type": "string" }, "type": { "enum": [ "named" ], "type": "string", "x-daytona-exact-enum": "discriminator" } }, "required": [ "name", "type" ], "type": "object" }, { "description": "Boot directly from an existing NFS manifest name. The API resolves a\nsnapshot to this variant so the runner boot path never learns snapshots\nexist (PLAN-SNAPSHOT-API.md \u00a73).\n\nAPI-INTERNAL ONLY, and enforced as such (issue #1501): the manifest\nnamespace is shared across projects (`refs//prj-/`) and\nthe runner resolves the name with no tenancy check, so the API's own\n`project_id`-scoped snapshot lookup IS the authorization. Every wire\nsurface that deserializes an `ImageSource` from caller input therefore\nrefuses this variant (`vms::reject_internal_image_source`); it is\nreached only by the API constructing it after that lookup.", "properties": { "name": { "type": "string" }, "type": { "enum": [ "manifest" ], "type": "string", "x-daytona-exact-enum": "discriminator" } }, "required": [ "name", "type" ], "type": "object" } ] }, "ImagesPage": { "description": "Page of images (`GET /images`).", "properties": { "images": { "items": { "$ref": "#/components/schemas/ImagePageRow" }, "type": "array" }, "next_cursor": { "description": "Opaque keyset token for the next page; null on the last page.", "type": [ "string", "null" ] } }, "required": [ "images" ], "type": "object" }, "ImportV1SandboxReq": { "additionalProperties": false, "description": "`POST /migration/v1/sandboxes/{v1_id}/import` body. Optional: an empty\nbody imports with the defaults.", "properties": { "force": { "description": "Import again even when a live import of this v1 sandbox exists: a\nsecond, independent rlp sandbox is created. Default `false`, which\nreturns the existing import.", "type": "boolean" } }, "type": "object" }, "ImportV1SandboxResp": { "description": "`POST /migration/v1/sandboxes/{v1_id}/import` response.", "properties": { "existing": { "description": "True when this call returned an earlier import instead of creating a\nsandbox.", "type": "boolean" }, "image_id": { "description": "The image it boots from (`img_\u2026`): an anonymous format-version-1\nimage registered from the v1 backup; the import starts its conversion\nto the current format and the sandbox's create joins it.", "example": "img_7fJk2mQpXv9dLc3RtY", "type": "string" }, "sandbox_id": { "description": "The persistent rlp sandbox (external id).", "type": "string" }, "secret_env_vars": { "description": "Env variable names whose value on v1 is a sandbox secret. v1 never\nhands the value over, so the imported sandbox starts without them:\nset them on it. Empty when the call returned an existing import.", "items": { "type": "string" }, "type": "array" }, "status": { "description": "The sandbox's status. A fresh import is `queued` while its image is\nimported from the v1 backup registry.", "example": "queued", "type": "string" }, "v1_labeled": { "description": "Whether v1 confirmed the `daytona.io/migrated-to` label on the v1\nsandbox. False means the label could not be set now; the import itself\nsucceeded, and repeating the call retries the label.", "type": "boolean" }, "warnings": { "description": "What the import could not carry over: env vars and labels rlp refuses,\nenv vars v1 keeps as sandbox secrets, and v1 settings with no rlp\nequivalent (auto-archive, auto-delete).", "items": { "type": "string" }, "type": "array" } }, "required": [ "sandbox_id", "image_id", "status", "existing", "v1_labeled", "warnings", "secret_env_vars" ], "type": "object" }, "ImportedFrom": { "description": "Where an imported sandbox or image came from (`vms.imported_from` +\n`vms.v1_ref`, the same pair on `images`).", "properties": { "id": { "description": "The resource's id on the source platform.", "example": "0b6c5c43-7a52-4c1f-9a42-3f0c3d7f2a11", "type": "string" }, "platform": { "description": "The source platform. `v1` is the only value.", "example": "v1", "type": "string" } }, "required": [ "platform", "id" ], "type": "object" }, "InvitationLookupResponse": { "description": "What `POST /invitations/lookup` shows the token holder before they decide.", "properties": { "email": { "description": "The invited address \u2014 the one the email went to.", "type": "string" }, "expires_at": { "description": "When the invitation stops being acceptable (RFC 3339).", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "invited_by": { "description": "The inviter's display name, else their email; `null` when the\ninviting account no longer exists.", "type": [ "string", "null" ] }, "org_id": { "format": "uuid", "type": "string" }, "org_name": { "type": "string" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "org_id", "org_name", "role", "roles", "email", "expires_at" ], "type": "object" }, "InvitationResponse": { "properties": { "declined_at": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "expires_at": { "description": "When the invitation stops being acceptable. The list deliberately keeps\nexpired rows visible so the org can revoke them; this is what lets a\nconsumer tell such a row from a live pending one (issue #1398, the\nexpiry twin of `declined_at` \u2014\nPLAN-INVITATION-DECLINED-VISIBILITY.md D6).", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "email", "role", "roles", "expires_at" ], "type": "object" }, "InvitationTokenReq": { "description": "The body of the three invitee routes (PLAN-INVITATION-EMAIL.md D4): the\n`dtni_` token from the invitation email's link. In the body, never a path\nor query parameter, so it lands in no access log, span, or audit row.", "properties": { "token": { "description": "`dtni_` plus 43 base64url characters, exactly as the link carries it.", "type": "string" } }, "required": [ "token" ], "type": "object" }, "InvitationsResponse": { "properties": { "invitations": { "items": { "$ref": "#/components/schemas/InvitationResponse" }, "type": "array" } }, "required": [ "invitations" ], "type": "object" }, "InvoiceListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/InvoiceResponse" }, "type": "array" }, "total_items": { "format": "int64", "type": "integer" }, "total_pages": { "format": "int64", "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "items", "total_items", "total_pages", "truncated" ], "type": "object" }, "InvoicePdfBody": { "description": "PDF document bytes", "format": "binary", "type": "string" }, "InvoiceResponse": { "properties": { "currency": { "type": "string" }, "file_url": { "type": "string" }, "has_pdf": { "type": "boolean" }, "id": { "type": "string" }, "issuing_date": { "type": "string" }, "number": { "type": "string" }, "payment_due_date": { "type": "string" }, "payment_overdue": { "type": "boolean" }, "payment_status": { "type": "string" }, "status": { "type": "string" }, "subtotal_amount_cents": { "format": "int64", "type": "integer" }, "taxes_amount_cents": { "format": "int64", "type": "integer" }, "total_amount_cents": { "format": "int64", "type": "integer" }, "total_due_amount_cents": { "format": "int64", "type": "integer" }, "type": { "type": "string" } }, "required": [ "id", "number", "issuing_date", "payment_due_date", "payment_overdue", "type", "status", "payment_status", "currency", "subtotal_amount_cents", "total_amount_cents", "total_due_amount_cents", "taxes_amount_cents", "file_url", "has_pdf" ], "type": "object" }, "JobResp": { "description": "One async job's status.", "properties": { "attempts": { "description": "Delivery attempts so far.", "format": "int32", "type": "integer" }, "error": { "description": "Failure detail, if the job errored.", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "description": "Job kind (e.g. `vm.create`, `build`, `snapshot.create`).", "type": "string" }, "runner_id": { "description": "Runner the job was dispatched to, once assigned.", "type": [ "string", "null" ] }, "status": { "description": "Lifecycle status: `queued`, `running`, `done`, or `failed`.", "type": "string" } }, "required": [ "id", "kind", "status", "attempts" ], "type": "object" }, "LayerDependentFunctionVersion": { "properties": { "id": { "format": "uuid", "type": "string" }, "manifest_name": { "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "LayerDependentImage": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "status" ], "type": "object" }, "LayerDependentSnapshot": { "properties": { "id": { "format": "uuid", "type": "string" }, "manifest_name": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "status" ], "type": "object" }, "LayerDependentVm": { "properties": { "id": { "type": "string" }, "manifest_name": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "LayerDependentsResp": { "properties": { "bytes": { "format": "int64", "type": "integer" }, "dependent_count": { "minimum": 0, "type": "integer" }, "diff_id": { "type": "string" }, "function_versions": { "items": { "$ref": "#/components/schemas/LayerDependentFunctionVersion" }, "type": "array" }, "images": { "items": { "$ref": "#/components/schemas/LayerDependentImage" }, "type": "array" }, "manifest_count": { "minimum": 0, "type": "integer" }, "manifests": { "items": { "type": "string" }, "type": "array" }, "reclaimable": { "type": "boolean" }, "snapshots": { "items": { "$ref": "#/components/schemas/LayerDependentSnapshot" }, "type": "array" }, "vms": { "items": { "$ref": "#/components/schemas/LayerDependentVm" }, "type": "array" } }, "required": [ "diff_id", "bytes", "manifests", "manifest_count", "dependent_count", "reclaimable", "images", "snapshots", "function_versions", "vms" ], "type": "object" }, "LayerEntry": { "properties": { "bytes": { "format": "int64", "type": "integer" }, "diff_id": { "type": "string" }, "erofs_path": { "type": "string" }, "exclusive": { "type": "boolean" }, "position": { "format": "int32", "type": "integer" }, "shared_with": { "format": "int64", "type": "integer" } }, "required": [ "diff_id", "erofs_path", "bytes", "position", "shared_with", "exclusive" ], "type": "object" }, "LifecycleAction": { "description": "The action a lifecycle trigger fires (PLAN-LIFECYCLE-TIMEOUTS.md \u00a7 The\ndesign in one block): one shared enum for both pairs, serialized lowercase\non the wire and stored lowercase in the TEXT columns (the migration's\nCHECK pins the same three values).", "enum": [ "stop", "pause", "delete" ], "type": "string", "x-daytona-open-enum": true }, "LifecycleDto": { "description": "The lifecycle object on the read side: the stored pairs plus the derived\ndeadline and the activity clock. `timeout_secs` IS echoed \u2014 it is a stored\nre-arm budget, not a write-only anchor like the old `delete_in_secs`, and\nthe re-arm rule makes it meaningful after every restart.", "properties": { "idle_timeout_at": { "description": "When `on_idle_timeout` becomes eligible to fire (RFC 3339):\n`last_activity_at + idle_timeout_secs`, derived at read time, never\nstored. Null when the idle pair is not armed or the sandbox has never\nbeen active. A floor, not a promise: any activity \u2014 traffic, SSH, or\n`POST .../reset-idle-timer` \u2014 advances `last_activity_at` and pushes\nit, and the reaper adds its own flush-interval slack.", "type": [ "string", "null" ] }, "idle_timeout_secs": { "format": "int32", "type": [ "integer", "null" ] }, "last_activity_at": { "description": "When the idle clock last moved (RFC 3339), or null on a row that has\nnever been active \u2014 which the reaper reads as \"no evidence, never\nreclaim\". This timestamp is what anchors `idle_timeout_at`.", "type": [ "string", "null" ] }, "last_activity_source": { "description": "Which bump moved the clock last: `lifecycle`, `api` (the explicit\n`POST .../reset-idle-timer`), `proxy.toolbox`, `proxy.preview`,\n`proxy.rdp`, `proxy.vnc`, `ssh`, or `daemon.process` (a command\nstarted through the sandbox's process API was still running) \u2014 plus\n`proxy.other`, which stands in for proxy traffic whose label this API\nversion does not recognize (the observation still counts). The set is\nopen-ended: treat an unknown value as \"some activity occurred\".", "example": "proxy.toolbox", "type": [ "string", "null" ] }, "on_idle_timeout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction", "description": "`stop` | `pause` | `delete`, or null when idle is not armed." } ] }, "on_timeout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction", "description": "`stop` | `pause` | `delete`, or null when no timeout is armed." } ] }, "timeout_at": { "description": "Absolute wall-clock deadline (RFC 3339), or null. Re-arms to\n`now + timeout_secs` on every accepted transition to `running`, and\nre-anchors when a PATCH supplies `timeout_secs` \u2014 so it tracks neither\n`created_at` nor `started_at` reliably; this field is the deadline.", "type": [ "string", "null" ] }, "timeout_secs": { "format": "int32", "type": [ "integer", "null" ] }, "wake_on_request": { "type": "boolean" } }, "required": [ "wake_on_request" ], "type": "object" }, "LifecycleReq": { "additionalProperties": false, "description": "The lifecycle object as it arrives on the wire \u2014 at create (nested under\n`lifecycle`) and as the whole body of the per-class lifecycle PATCH.\n\n`deny_unknown_fields` matches the create bodies' posture: a misspelled knob\n\u2014 or an old SDK's `stop_after_idle_secs` \u2014 is a loud 400 naming the field,\nnever a silently ignored safety policy.", "properties": { "idle_timeout_secs": { "default": null, "description": "Idle seconds after which `on_idle_timeout` fires. Opt-in: omitted =\ndisabled at create, unchanged at PATCH; `-1` clears the stored pair.\nA value below 60 is raised to 60 and stored raised; `0` is rejected.", "example": 900, "format": "int64", "maximum": 2147483647, "minimum": -1, "type": [ "integer", "null" ] }, "on_idle_timeout": { "default": null, "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction", "description": "Action fired when the idle timeout elapses: `stop` | `pause` |\n`delete`. No default \u2014 required when arming `idle_timeout_secs` from\nnothing. Same `delete:sandboxes` PATCH rule as `on_timeout`." } ] }, "on_timeout": { "default": null, "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction", "description": "Action fired when the timeout elapses: `stop` | `pause` | `delete`.\nOmitted while a timeout arms: the class default (`pause` linux\npersistent, `stop` windows and macOS persistent, `delete`\nephemeral/GPU).\nRequires `delete:sandboxes` on PATCH when set to `delete` \u2014 or when\ntouching a pair whose stored or resulting action is `delete`." } ] }, "timeout_secs": { "default": null, "description": "Wall-clock seconds after which `on_timeout` fires. Re-arms with the\nfull budget on every accepted transition to `running` (start, resume,\nwake); a PATCH that supplies it re-anchors the deadline from now.\n`1..=` the effective max (org `max_timeout_secs`, else the global\n86400 default); `-1`/`0` are rejected \u2014 the timeout cannot be\ndisabled. Omitted at create: the platform default (300 s) when the\ndefault gate is on, no timeout otherwise.", "example": 300, "format": "int64", "maximum": 2147483647, "minimum": 1, "type": [ "integer", "null" ] }, "wake_on_request": { "default": null, "description": "Resume a parked sandbox on inbound authenticated traffic. Linux\npersistent only.", "type": [ "boolean", "null" ] } }, "type": "object" }, "LimitSource": { "enum": [ "org", "default", "unlimited" ], "type": "string", "x-daytona-open-enum": true }, "LimitsResponse": { "properties": { "enforced": { "description": "Whether the platform enforces limits at admission; when false, the\nvalues are informational only.", "type": "boolean" }, "members": { "$ref": "#/components/schemas/MembersLimits" }, "soft": { "$ref": "#/components/schemas/SoftLimits" }, "strict": { "$ref": "#/components/schemas/StrictLimits" }, "timeouts": { "$ref": "#/components/schemas/TimeoutLimits" }, "usage": { "$ref": "#/components/schemas/LimitsUsage" } }, "required": [ "enforced", "soft", "strict", "usage", "members", "timeouts" ], "type": "object" }, "LimitsUsage": { "properties": { "gpu_vms": { "format": "int64", "type": "integer" }, "totals": { "$ref": "#/components/schemas/UsageTotals" }, "windows_vms": { "format": "int64", "type": "integer" } }, "required": [ "totals", "gpu_vms", "windows_vms" ], "type": "object" }, "ListGlobalRefsResp": { "properties": { "refs": { "items": { "$ref": "#/components/schemas/GlobalRefEntry" }, "type": "array" } }, "required": [ "refs" ], "type": "object" }, "ListGlobalRegistriesResp": { "description": "`GET /manage/registries/global` body.", "properties": { "registries": { "items": { "$ref": "#/components/schemas/GlobalRegistryMeta" }, "type": "array" } }, "required": [ "registries" ], "type": "object" }, "ListImagesResp": { "properties": { "images": { "items": { "$ref": "#/components/schemas/AdminImageSummary" }, "type": "array" } }, "required": [ "images" ], "type": "object" }, "ListPlatformImagesResp": { "description": "`GET /manage/platform-images` body.", "properties": { "default": { "$ref": "#/components/schemas/PlatformImageDefaults" }, "images": { "items": { "$ref": "#/components/schemas/PlatformImage" }, "type": "array" } }, "required": [ "images", "default" ], "type": "object" }, "ListRegistriesResp": { "description": "Response for `GET /registries`: metadata only, never passwords.", "properties": { "registries": { "items": { "$ref": "#/components/schemas/RegistryMeta" }, "type": "array" } }, "required": [ "registries" ], "type": "object" }, "ListReservationsResp": { "description": "GET /reservations response.", "properties": { "reservations": { "items": { "$ref": "#/components/schemas/MacReservation" }, "type": "array" } }, "required": [ "reservations" ], "type": "object" }, "ListSecretsResp": { "description": "GET /secrets response envelope.", "properties": { "secrets": { "items": { "$ref": "#/components/schemas/SecretListItem" }, "type": "array" } }, "required": [ "secrets" ], "type": "object" }, "ListSnapshotsResp": { "description": "GET /snapshots response: one page of snapshots. (`next_cursor` precedes\n`snapshots` to match the former `json!` response's alphabetical key order.)", "properties": { "next_cursor": { "description": "Opaque continuation token; `null` on the last page.", "type": [ "string", "null" ] }, "snapshots": { "items": { "$ref": "#/components/schemas/SnapshotPageRow" }, "type": "array" } }, "required": [ "snapshots" ], "type": "object" }, "ListVmsResp": { "description": "Response shape for `GET /sandboxes`. Schema-only (the handler assembles the JSON):\nin list mode `vms` is the keyset page (each item a sandbox row plus its\n`created_at` + per-row resume `cursor`) and `next_cursor` the whole-page\ncontinuation (null on the last page). In batch-wait mode (`?ids=`) `vms` is\na snapshot of every requested id the caller owns (plain sandbox rows, no\n`created_at`/`cursor`) and `next_cursor` is absent.", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "vms": { "items": { "$ref": "#/components/schemas/VmPageRow" }, "type": "array" } }, "required": [ "vms" ], "type": "object" }, "ListVolumesResp": { "description": "Response envelope for `GET /volumes`.", "properties": { "volumes": { "items": { "$ref": "#/components/schemas/VolumeDto" }, "type": "array" } }, "required": [ "volumes" ], "type": "object" }, "MacReservation": { "description": "A Mac lease.", "properties": { "activated_at": { "format": "date-time", "type": [ "string", "null" ] }, "auto_renew": { "description": "The lease renews itself shortly before `period_end` (an hour by\ndefault) while a macOS sandbox is active on it; an idle lease lapses\ninstead.", "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "end_reason": { "description": "`expired` | `released` | `charge_failed` | `not_accepted` | `reissued` | `operator`.", "type": [ "string", "null" ] }, "ended_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "External reservation id (region-tagged).", "type": "string" }, "lease_generation": { "format": "int64", "type": "integer" }, "leasing_since": { "format": "date-time", "type": [ "string", "null" ] }, "org_id": { "format": "uuid", "type": "string" }, "origin": { "description": "`explicit` (bought by `POST /reservations` or a create with\n`reservation: \"new\"`) | `auto` (bought by a macOS create under the\norganization's auto-reserve setting).", "example": "explicit", "type": "string" }, "period_end": { "description": "When the lease ends unless renewed. Absent until a Mac first claims it\n(period 1 starts at the claim, so waiting for a Mac is not paid time).", "format": "date-time", "type": [ "string", "null" ] }, "period_hours": { "description": "The period length in hours.", "format": "int32", "type": "integer" }, "period_n": { "description": "The current paid period (1-based).", "format": "int32", "type": "integer" }, "period_start": { "format": "date-time", "type": [ "string", "null" ] }, "project_id": { "description": "The project whose key bought the lease. The lease serves every\nproject of the org; this project's monthly budget gates its renewals,\nmanual and automatic (`project_budget_exceeded` while the project is\nheld).", "format": "uuid", "type": "string" }, "region": { "type": "string" }, "reissued_at": { "description": "Set when the lease moved to another Mac after its Mac was lost.", "format": "date-time", "type": [ "string", "null" ] }, "renewal_error": { "description": "Why the renewal of the next period failed (billing refused it, or the\nbalance was too low); the lease ends at `period_end` unless renewed by\nhand. Null when no renewal has failed.", "type": [ "string", "null" ] }, "renewal_pending": { "description": "A renewal charge is still waiting for billing's answer.", "type": "boolean" }, "runner_id": { "description": "The Mac holding the lease; absent until a Mac claims it.", "type": [ "string", "null" ] }, "slots_used": { "description": "macOS VMs currently occupying this lease's Mac.", "format": "int64", "type": "integer" }, "status": { "description": "`pending_charge` | `leasing` | `active` | `ending` | `released` | `failed`.", "example": "active", "type": "string" }, "vms_per_mac": { "format": "int32", "type": "integer" } }, "required": [ "id", "org_id", "project_id", "region", "status", "origin", "auto_renew", "lease_generation", "vms_per_mac", "slots_used", "period_n", "period_hours", "renewal_pending", "created_at" ], "type": "object" }, "MacosSettings": { "description": "`organizations`' macOS columns, as the `GET/PATCH` body renders them.", "properties": { "macos_auto_reserve": { "description": "Auto-reserve is on: a macOS create with no free slot on the org's\nleases buys a 24-hour lease (auto-renewing while a sandbox runs on it).", "type": "boolean" }, "macos_auto_reserve_enabled_at": { "description": "When auto-reserve was last turned on; null while it is off.", "format": "date-time", "type": [ "string", "null" ] }, "macos_auto_reserve_enabled_by": { "description": "The admin who last turned it on; null while it is off.", "format": "uuid", "type": [ "string", "null" ] }, "macos_auto_reserve_max_leases": { "description": "The most live auto-created leases the org may hold at once.", "format": "int32", "type": "integer" } }, "required": [ "macos_auto_reserve", "macos_auto_reserve_max_leases" ], "type": "object" }, "MacosSettingsPatch": { "additionalProperties": false, "description": "`PATCH /orgs/:id/macos-settings` body: any non-empty subset.", "properties": { "macos_auto_reserve": { "type": [ "boolean", "null" ] }, "macos_auto_reserve_max_leases": { "format": "int32", "type": [ "integer", "null" ] } }, "type": "object" }, "MacroRegionInfo": { "description": "A cached macro-region row (PLAN-REGION-HIERARCHY.md): the public selector\nfor exactly ONE workload cell, sitting between a Geo group and the Edge\nregions that cell serves.\n\n`cell_id` is the deployment's stable cell identity \u2014 the key the request\nrouter's directory is indexed by \u2014 not a URL and not the serving process's\ndeployment role. Both it and `id` are immutable: re-pointing either would\nmove future placement to a different database.", "properties": { "cell_id": { "type": "string" }, "eligible_local_region_count": { "description": "Edge regions beneath this Macro that a broad selector may place in:\nactive, routable and opted in \u2014 **fleet discovery eligibility**, not\nscoped to what the answering process serves (issue #1867). `None` means\nthis process cannot count them \u2014 a `central` deployment owns the topology\nbut no local rows, so reporting `0` would claim every cell is empty.\n\nComputed from the local rows loaded in the same snapshot, never selected\n\u2014 which is why the DTO is separate from `MacroRegionRow`.", "minimum": 0, "type": [ "integer", "null" ] }, "global_region_id": { "description": "The Geo group this Macro hangs off. Groups are arbitrary/abstract; names\nsuch as US or EU do not impose a geographic constraint. Never `earth`:\nthat ID names the Global root. The field retains its stored name.", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "selectable": { "description": "Whether this API cell serves an eligible member of this Macro \u2014\nthe same local execution fact as [`GlobalRegionInfo::selectable`],\nand deliberately distinct from the inventory count above (issue #1867).\n\nFilled per read rather than cached with the row: it depends on this\nprocess's own served set, which is not a property of the catalog.", "type": "boolean" } }, "required": [ "id", "name", "cell_id", "global_region_id" ], "type": "object" }, "ManifestLayersResp": { "properties": { "layer_count": { "minimum": 0, "type": "integer" }, "layers": { "items": { "$ref": "#/components/schemas/LayerEntry" }, "type": "array" }, "manifest_name": { "type": "string" }, "total_bytes": { "format": "int64", "type": "integer" } }, "required": [ "manifest_name", "layer_count", "layers", "total_bytes" ], "type": "object" }, "MeResponse": { "properties": { "email": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "email" ], "type": "object" }, "MemberResponse": { "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "email", "role", "roles" ], "type": "object" }, "MemberUpdateResponse": { "oneOf": [ { "$ref": "#/components/schemas/DryRunNarrowingResponse" }, { "$ref": "#/components/schemas/UpdatedMemberResponse" } ] }, "MembersLimits": { "description": "The seat cap group (PLAN-PRICING-PLANS.md \"Seat cap (api)\"): the effective\n`max_members` with its source, the seated members, and the undecided\ninvitations that also count at invitation time.", "properties": { "current": { "format": "int64", "type": "integer" }, "max_members": { "$ref": "#/components/schemas/EffectiveLimit" }, "pending_invitations": { "format": "int64", "type": "integer" } }, "required": [ "max_members", "current", "pending_invitations" ], "type": "object" }, "MembersResponse": { "properties": { "members": { "items": { "$ref": "#/components/schemas/MemberResponse" }, "type": "array" } }, "required": [ "members" ], "type": "object" }, "MintAccessTokenReq": { "additionalProperties": false, "description": "`POST \u2026/access-token` request. All fields optional; an absent (or empty)\nbody is the full default mint.", "properties": { "operations": { "description": "Requested operation subset (the sandbox-operation vocabulary:\n`toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`,\n`desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, `sandbox:delete`).\nOmitted = the minter's full grantable set. An empty list is a valid\nports-only grant. Unknown strings, and operations outside the\nminter's grantable set, are a 400 \u2014 never a silent narrowing.", "example": [ "toolbox:fs", "ssh" ], "items": { "type": "string" }, "type": [ "array", "null" ] }, "ports": { "description": "Private-preview ports the token may reach (1..=65535, at most 128,\nduplicates collapsed). Omitted = all ports; `[]` = none.", "example": [ 3000 ], "items": { "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "type": [ "array", "null" ] }, "ttl_secs": { "description": "Token lifetime in seconds. Omitted = the deployment default\n(3600 unless the deployment overrides it); values above the\ndeployment cap (86400 by default) are a 400. On a workload cell a\nplatform-token mint is additionally bounded by the minting token's\nown remaining life \u2014 `expires_at` in the response is authoritative.", "example": 900, "format": "int64", "minimum": 1, "type": [ "integer", "null" ] } }, "type": "object" }, "MintBody": { "additionalProperties": false, "description": "`deny_unknown_fields`: a mistyped option (`expire_at`, `expires`) must\nfail loudly instead of minting a credential without the bound the\noperator asked for.", "properties": { "expires_at": { "description": "Absolute expiry; must be in the future. Absent/`null` is the\nconfigured default lifetime (30 days unless the operator changed it),\nnot \"never\".", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Operator-facing label for the credential (free text).", "type": [ "string", "null" ] }, "no_expiry": { "description": "Explicitly unbounded. `expires_at: null` (or absent) is NOT \"never\":\nit is the configured default lifetime.", "type": "boolean" } }, "type": "object" }, "Minted": { "description": "A freshly minted credential. The token appears here and nowhere else \u2014\nincluding `Debug`, which redacts it (a formatted mint result in a log or\na panic message must not be a reusable credential).", "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "description": "`null` for an explicitly unbounded credential (`no_expiry`).", "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "runner_id": { "type": "string" }, "token": { "description": "The credential itself (`rlpr_\u2026`), shown ONCE: only its hash is stored.", "type": "string" } }, "required": [ "id", "runner_id", "token", "created_at" ], "type": "object" }, "NetworkPolicy": { "properties": { "allow_cidrs": { "items": { "type": "string" }, "type": "array" }, "allow_domains": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "block_all": { "type": "boolean" }, "version": { "format": "int32", "type": "integer" } }, "required": [ "version", "block_all", "allow_cidrs" ], "type": "object" }, "NetworkPolicyInput": { "additionalProperties": false, "properties": { "allow_cidrs": { "items": { "type": "string" }, "type": "array" }, "allow_domains": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "block_all": { "description": "Default-deny toggle. With a non-null `allow_domains`, omitted or null\nnormalizes to `true`; explicit `false` is rejected with\n`400 network_policy_domains_require_block_all`. With `allow_domains`\nnull, omitted or null normalizes to `false`.", "type": [ "boolean", "null" ] } }, "type": "object" }, "NetworkPolicyResponse": { "properties": { "applied": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkPolicy" } ] }, "applied_incarnation": { "type": [ "string", "null" ] }, "applied_revision": { "format": "int64", "type": [ "integer", "null" ] }, "desired": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkPolicy" } ] }, "desired_revision": { "format": "int64", "type": "integer" }, "failure_reason": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] } }, "required": [ "desired_revision" ], "type": "object" }, "OidcProvider": { "description": "The login bridge the SPA mounts. `Oidc` is the standards-shaped flow\n(oidc-client-ts, Auth0 dev stacks, `audience` binding); `Workos` is the\nserver-side WorkOS login hosted by rlp-api under `/auth/session/*`\n(`client_id` binding, `dashboard_session`).", "enum": [ "oidc", "workos" ], "type": "string", "x-daytona-open-enum": true }, "OidcPublicConfig": { "description": "The `oidc` block of [`Config`].", "properties": { "audience": { "description": "The API identifier the SPA requests tokens for. Present under the\n`oidc` provider; `null` under `workos`, whose tokens are bound on\n`client_id` and carry no `aud`.", "type": [ "string", "null" ] }, "cli_client_id": { "description": "Public OAuth client id of the *native* application the `daytona` CLI logs\nin through (authorization-code + PKCE on a loopback redirect, or the\ndevice-authorization grant on a headless host \u2014 PLAN-CLI.md D8/\u00a74.3). A\nbrowser SPA client cannot be reused for either flow, so the CLI reads its\nown id from here and the binary stays deployment-agnostic. `null` when\nthe deployment does not publish a native-client id.", "type": [ "string", "null" ] }, "client_id": { "description": "The SPA's public OAuth client id.", "type": "string" }, "issuer": { "description": "The issuer the API validates user tokens against.", "type": "string" }, "provider": { "$ref": "#/components/schemas/OidcProvider", "description": "Which login bridge the SPA mounts: `oidc` is the standards-shaped\nflow (oidc-client-ts), `workos` the server-side WorkOS login behind\n`/auth/session/*` (PLAN-DAYTONA-USER-MIGRATION.md)." }, "scope": { "description": "Default OIDC scope the SPA requests.", "type": "string" } }, "required": [ "provider", "issuer", "client_id", "scope" ], "type": "object" }, "OrgApiKeyResponse": { "properties": { "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_by": { "description": "The human who minted the key \u2014 an id for a `read:members` holder,\n`null` for everyone else (the projects rule, #942).", "format": "uuid", "type": [ "string", "null" ] }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "key_prefix": { "type": [ "string", "null" ] }, "last_used_at": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "org_permissions": { "items": { "type": "string" }, "type": "array" }, "revoked_at": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "name", "org_permissions" ], "type": "object" }, "OrgApiKeysResponse": { "properties": { "org_api_keys": { "items": { "$ref": "#/components/schemas/OrgApiKeyResponse" }, "type": "array" } }, "required": [ "org_api_keys" ], "type": "object" }, "OrgFeatureFlagsResponse": { "properties": { "flags": { "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" }, "type": "object" } }, "required": [ "flags" ], "type": "object" }, "OrganizationResponse": { "properties": { "assignable_project_permissions": { "items": { "type": "string" }, "type": "array" }, "budget_stop_grace_hours": { "description": "The organization's effective project budget grace period, in hours\n(PLAN-PROJECT-BUDGETS.md D5): how long after a project's budget hold\nstarts its running persistent sandboxes are stopped and its running\nephemeral sandboxes deleted (macOS sandboxes, which run on a prepaid\nMac lease, keep running). The organization's own value when an\noperator set one, otherwise the deployment default.", "format": "int32", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "org_permissions": { "items": { "type": "string" }, "type": "array" }, "personal": { "type": "boolean" }, "preview_warning_disabled": { "description": "Whether the organization has turned off the proxy's preview warning\npage for its sandbox previews (PLAN-PREVIEW-WARNING-PAGE.md). `false`\nby default: the page is shown. Set through\n`PATCH /orgs/{id}/preview-warning`.", "type": "boolean" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" }, "suspended": { "type": "boolean" }, "suspended_reason": { "type": [ "string", "null" ] }, "workos_linked": { "description": "Whether the organization is linked to a WorkOS organization \u2014 the one\nit shares with Daytona v1, and the one the Single sign-on page's Admin\nPortal configures (`/orgs/{id}/identity-providers/*`). Independent of\n`workos_sync_enabled`: an organization whose sync an operator switched\noff stays linked. Never `true` for a personal organization.", "type": "boolean" }, "workos_org_id": { "description": "The id of the WorkOS organization the organization is linked to, set\nexactly when `workos_linked`. The dashboard sends it as the\n`organization_id` of `GET /auth/session/login` so the hosted login\nlands in the organization the member last worked in instead of\nshowing WorkOS's organization picker.", "type": [ "string", "null" ] }, "workos_sync_enabled": { "description": "Whether the organization's memberships sync through WorkOS with the\nDaytona v1 organization of the same id (PLAN-DAYTONA-USER-MIGRATION.md\nD12, PLAN-IDENTITY-RECONCILER.md D17). When `true`, removing a member\nalso removes them from the Daytona v1 organization, and the `admin`\nrole reaches WorkOS as `owner`. Never `true` for a personal\norganization, nor on a deployment that mirrors nothing to WorkOS.", "type": "boolean" } }, "required": [ "id", "name", "personal", "suspended", "preview_warning_disabled", "budget_stop_grace_hours", "workos_sync_enabled", "workos_linked", "role", "roles", "org_permissions", "assignable_project_permissions" ], "type": "object" }, "OrganizationUsageResponse": { "properties": { "amount_cents": { "format": "int64", "type": "integer" }, "charges": { "items": { "$ref": "#/components/schemas/UsageChargeResponse" }, "type": "array" }, "from": { "type": "string" }, "issuing_date": { "type": "string" }, "taxes_amount_cents": { "format": "int64", "type": "integer" }, "to": { "type": "string" }, "total_amount_cents": { "format": "int64", "type": "integer" } }, "required": [ "from", "to", "issuing_date", "amount_cents", "total_amount_cents", "taxes_amount_cents", "charges" ], "type": "object" }, "OrganizationsResponse": { "properties": { "organizations": { "items": { "$ref": "#/components/schemas/OrganizationResponse" }, "type": "array" } }, "required": [ "organizations" ], "type": "object" }, "OtelConfigView": { "description": "The config body every management success returns: the endpoint and the\nheader **names**. No plane returns a header value.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "endpoint": { "description": "The tenant's OTLP/HTTP endpoint.", "type": "string" }, "header_names": { "description": "Names of the request headers configured; values are write-only and never returned.", "items": { "type": "string" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "endpoint", "header_names", "created_at", "updated_at" ], "type": "object" }, "PatchImageReq": { "properties": { "global": { "type": [ "boolean", "null" ] } }, "type": "object" }, "PatchImageResp": { "properties": { "global": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "status", "global" ], "type": "object" }, "PatchPlatformImageReq": { "additionalProperties": false, "description": "`PATCH /manage/platform-images/{id}` body. Absent fields are unchanged.", "properties": { "deprecated": { "description": "`true` hides the image from new creates by name and from tenant\nlistings; `false` restores it. The current default cannot be\ndeprecated.", "type": [ "boolean", "null" ] }, "description": { "description": "The new description (at most 256 characters); `null` clears it.", "type": [ "string", "null" ] } }, "type": "object" }, "PaymentMethodResponse": { "properties": { "brand": { "type": "string" }, "exp_month": { "format": "int32", "type": "integer" }, "exp_year": { "format": "int32", "type": "integer" }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "last4": { "type": "string" } }, "required": [ "id", "brand", "last4", "exp_month", "exp_year", "is_default" ], "type": "object" }, "PermissionMetadataResponse": { "properties": { "category": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "reserved": { "type": "boolean" } }, "required": [ "id", "name", "category", "reserved" ], "type": "object" }, "PersistentPolicyReq": { "additionalProperties": false, "properties": { "idle_timeout_secs": { "default": null, "format": "int64", "type": [ "integer", "null" ] }, "on_idle_timeout": { "default": null, "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction" } ] }, "on_timeout": { "default": null, "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction" } ] }, "timeout_secs": { "default": null, "format": "int64", "type": [ "integer", "null" ] }, "wake_on_request": { "default": null, "type": [ "boolean", "null" ] } }, "type": "object" }, "PlatformDefaultResp": { "description": "`PUT /manage/platform-images/default` response.", "properties": { "class": { "example": "linux", "type": "string" }, "image": { "$ref": "#/components/schemas/PlatformImage" } }, "required": [ "class", "image" ], "type": "object" }, "PlatformImage": { "description": "One operator-published platform image, as `/manage/platform-images`\nreturns it.", "properties": { "available_in": { "description": "Regions holding a copy of the image's manifest now. A create in\nanother region of the cell pulls the ref again.", "items": { "type": "string" }, "type": "array" }, "class": { "example": "linux", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "default": { "description": "The cell's platform default image (`POST /sandboxes` without `image`).", "type": "boolean" }, "deprecated": { "description": "Deprecated rows take no new creates by name and are not listed to\ntenants; existing sandboxes keep booting, and the `img_\u2026` id still\nresolves.", "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "error": { "description": "Import failure reason; null unless `status` is `failed`.", "type": [ "string", "null" ] }, "id": { "description": "External image id.", "example": "img_7fJk2mQpXv9dLc3RtY", "type": "string" }, "name": { "example": "daytona-base", "type": "string" }, "ref": { "description": "The digest-pinned registry ref the image was imported from.", "example": "docker.io/library/python@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "type": "string" }, "region": { "description": "The region the image was imported in (the cell's default region).", "type": "string" }, "status": { "description": "`pending`, `building`, `ready` or `failed`.", "example": "ready", "type": "string" } }, "required": [ "id", "name", "ref", "class", "status", "region", "available_in", "deprecated", "default", "created_at" ], "type": "object" }, "PlatformImageDefaults": { "description": "The cell's platform default per class: the image's `img_\u2026` id, or null.", "properties": { "linux": { "type": [ "string", "null" ] } }, "type": "object" }, "PlatformImageResp": { "description": "`{image}` \u2014 the platform image after a write.", "properties": { "image": { "$ref": "#/components/schemas/PlatformImage" } }, "required": [ "image" ], "type": "object" }, "PortRequest": { "properties": { "proto": { "example": "tcp", "type": "string" }, "vm_port": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "vm_port" ], "type": "object" }, "PortalIntent": { "description": "What the Admin Portal session configures: an SSO connection or a\ndirectory (SCIM) sync. The wire values are WorkOS's own.", "enum": [ "sso", "dsync" ], "type": "string", "x-daytona-open-enum": true }, "PosthogPublicConfig": { "description": "The `posthog` block of [`Config`]. Field names are camelCase to match the\nDaytona dashboard's config shape (`configuration.dto.ts`), unlike the rest\nof this document.", "properties": { "apiKey": { "description": "PostHog project (browser) key.", "type": "string" }, "environment": { "description": "Environment tag the browser stamps on its events.", "type": "string" }, "host": { "description": "Ingestion host the browser talks to.", "type": "string" } }, "required": [ "apiKey", "host", "environment" ], "type": "object" }, "PreviewEndpoint": { "description": "One preview endpoint on the wire (with the computed URL).", "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "port": { "description": "In-VM TCP port the endpoint exposes.", "format": "int32", "type": "integer" }, "public": { "description": "Access mode: `true` = the proxy skips auth, `false` = a credential is\nrequired (per-VM token or owning project API key).", "type": "boolean" }, "url": { "description": "Host-based preview URL, `://-./`.", "type": "string" } }, "required": [ "id", "port", "public", "url", "created_at" ], "type": "object" }, "PreviewUrlResp": { "description": "A preview URL + its access token (`GET /sandboxes/{id}/ports/{port}/preview-url`).", "properties": { "token": { "description": "Per-sandbox preview access token \u2014 send as `x-daytona-preview-token`\n(the header the proxy validates). During the data-plane compat window\nthis is the stable HMAC token; once the deployment flips compat off\nit is a short-lived sandbox JWT\nscoped to exactly this port (PLAN-SANDBOX-TOKEN-JWT.md D9) \u2014 re-fetch\nthis route (or mint via `POST /sandboxes/{id}/access-token`) when it\nexpires.", "type": "string" }, "url": { "description": "Host-based preview URL, `://-./`.", "type": "string" } }, "required": [ "url", "token" ], "type": "object" }, "PreviewWarningReq": { "additionalProperties": false, "description": "`PATCH /orgs/:id/preview-warning` body. `deny_unknown_fields`: a typo'd\nfield from a client must be a 400, never a silent no-op.", "properties": { "disabled": { "description": "`true` turns the preview warning page off for every sandbox preview of\nthe organization (needs the `preview_warning_opt_out` entitlement where\nenforcement is on); `false` turns it back on.", "type": "boolean" } }, "required": [ "disabled" ], "type": "object" }, "PreviewWarningResponse": { "description": "`PATCH /orgs/{id}/preview-warning` response (PLAN-PREVIEW-WARNING-PAGE.md):\nthe stored value of `organizations.preview_warning_disabled` after the\nwrite.", "properties": { "disabled": { "description": "`true` when the organization has turned the preview warning page off.", "type": "boolean" } }, "required": [ "disabled" ], "type": "object" }, "PrincipalResponse": { "description": "The caller's resolved org principal (`GET /orgs/{id}/principal`).", "properties": { "key_id": { "description": "Present when `kind` is `org_key`.", "format": "uuid", "type": [ "string", "null" ] }, "kind": { "description": "`user` (OIDC JWT) or `org_key` (`dtno_` organization API key).", "example": "org_key", "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "permissions": { "description": "Canonical-order org permission strings the caller holds in this organization.", "items": { "type": "string" }, "type": "array" }, "user_id": { "description": "Present when `kind` is `user`.", "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "kind", "org_id", "permissions" ], "type": "object" }, "PrivacyPolicyStatus": { "description": "The signed-in user's standing against the required privacy policy.", "properties": { "accepted": { "description": "Whether the user has accepted the required version. A client should\nprompt for consent only on an explicit `false`.", "type": "boolean" }, "accepted_at": { "format": "date-time", "type": [ "string", "null" ] }, "accepted_version": { "description": "Version the user last accepted, whichever version is required now.", "type": [ "string", "null" ] }, "url": { "description": "Where the current policy text is published; `null` when no consent is\nrequired.", "type": [ "string", "null" ] }, "version": { "description": "Version the platform currently requires; `null` when it requires no\nconsent, in which case `accepted` is always `true`.", "type": [ "string", "null" ] } }, "required": [ "accepted" ], "type": "object" }, "ProjectApiKeyResponse": { "properties": { "created_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_by": { "description": "The human who minted the key \u2014 an id for a `read:members` holder,\n`null` for everyone else (the projects rule, #942); also `null` for a\nservice-account or CLI-minted key.", "format": "uuid", "type": [ "string", "null" ] }, "expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "imported_from": { "description": "`\"v1\"` when the key was created on Daytona v1 and imported by the\nv1 \u2194 v2 key sync; `null` for a key created on this platform.", "type": [ "string", "null" ] }, "key_prefix": { "type": [ "string", "null" ] }, "key_suffix": { "description": "Last characters of the plaintext token, for a recognizable masked\ndisplay; `null` for keys minted before the suffix was recorded.", "type": [ "string", "null" ] }, "last_used_at": { "format": "date-time", "type": [ "string", "null" ] }, "mine": { "type": "boolean" }, "name": { "type": "string" }, "project_permissions": { "items": { "type": "string" }, "type": "array" }, "revoked_at": { "format": "date-time", "type": [ "string", "null" ] }, "service_account_id": { "format": "uuid", "type": [ "string", "null" ] }, "service_account_name": { "type": [ "string", "null" ] }, "sync_to_v1": { "description": "Whether the v1 \u2194 v2 key sync copies this key to Daytona v1 (for an\norganization that is kept in sync with v1). `true` for a live key a person minted in the organization's\n`default` project unless it was opted out (`PATCH /api-keys/{id}`),\nand always for a live key imported from v1. `false` for every key\nthe sync never copies: keys in other projects, service-account keys,\nthe dashboard's own key named `default`, and revoked or expired keys.\nA v1 copy can read every sandbox, snapshot and registry of the\norganization on v1, which has no read permissions.", "type": "boolean" } }, "required": [ "id", "name", "project_permissions", "mine", "sync_to_v1" ], "type": "object" }, "ProjectApiKeysResponse": { "properties": { "project_api_keys": { "items": { "$ref": "#/components/schemas/ProjectApiKeyResponse" }, "type": "array" } }, "required": [ "project_api_keys" ], "type": "object" }, "ProjectBudget": { "description": "A project's monthly spend budget and its current state.", "properties": { "evaluated_at": { "description": "When spend was last evaluated in the current period. `null` until the\nfirst evaluation in the period.", "format": "date-time", "type": [ "string", "null" ] }, "exceeded_at": { "description": "When the project reached its budget this period. `null` while the\nproject is under its budget.", "format": "date-time", "type": [ "string", "null" ] }, "monthly_limit_cents": { "description": "The monthly budget, in US cents.", "format": "int64", "type": "integer" }, "period_start": { "description": "The first day of the current budget period (the calendar month in\nUTC), as `YYYY-MM-DD`.", "example": "2026-10-01", "format": "date", "type": "string" }, "project_id": { "description": "The project the budget caps.", "format": "uuid", "type": "string" }, "spent_cents": { "description": "Month-to-date spend at list price, in US cents, from the last\nevaluation in the current period. `null` until the first evaluation in\nthe period.", "format": "int64", "type": [ "integer", "null" ] }, "stop_at": { "description": "When running sandboxes are ended: `exceeded_at` plus the grace period.\nOn the first sweep after this time, running persistent sandboxes are\nstopped and running ephemeral sandboxes are deleted; macOS sandboxes,\nwhich run on a prepaid Mac lease, keep running. `null` when\n`exceeded_at` is `null`, and `null` when this time falls on or after\nthe start of the next UTC month: the hold expires at the month\nboundary, so no sandbox is ended this period.", "format": "date-time", "type": [ "string", "null" ] }, "stop_grace_hours": { "description": "The organization's effective grace period, in hours.", "format": "int32", "type": "integer" } }, "required": [ "project_id", "monthly_limit_cents", "period_start", "stop_grace_hours" ], "type": "object" }, "ProjectDto": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "description": "An id, not an identity \u2014 and only for a caller who may see identities:\n`null` unless the caller holds `read:members` (D5), the same rule the\nkey lists apply to their `created_by` (#942). A `read:projects` holder\nwho cannot list the org's members must not learn who created a project\nfrom this DTO instead.", "format": "uuid", "type": [ "string", "null" ] }, "default": { "description": "True for the org's undeletable `default` project.", "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "org_id", "name", "default", "created_at", "updated_at" ], "type": "object" }, "ProjectLifecyclePolicyDto": { "properties": { "effective": { "$ref": "#/components/schemas/EffectivePolicyDto" }, "max_timeout_secs": { "format": "int64", "type": "integer" }, "policy": { "$ref": "#/components/schemas/StoredPolicyDto" } }, "required": [ "policy", "max_timeout_secs", "effective" ], "type": "object" }, "ProjectMemberResponse": { "properties": { "added_at": { "format": "date-time", "type": [ "string", "null" ] }, "email": { "type": "string" }, "implicit": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "email", "implicit" ], "type": "object" }, "ProjectMembersResponse": { "properties": { "members": { "items": { "$ref": "#/components/schemas/ProjectMemberResponse" }, "type": "array" } }, "required": [ "members" ], "type": "object" }, "ProjectServiceAccountResponse": { "properties": { "added_at": { "format": "date-time", "type": [ "string", "null" ] }, "archived_at": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "implicit": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name", "implicit" ], "type": "object" }, "ProjectServiceAccountsResponse": { "properties": { "service_accounts": { "items": { "$ref": "#/components/schemas/ProjectServiceAccountResponse" }, "type": "array" } }, "required": [ "service_accounts" ], "type": "object" }, "ProjectsResponse": { "properties": { "projects": { "items": { "$ref": "#/components/schemas/ProjectDto" }, "type": "array" } }, "required": [ "projects" ], "type": "object" }, "PromoteImageReq": { "properties": { "name": { "example": "keep-this", "type": "string" } }, "required": [ "name" ], "type": "object" }, "PublishPlatformImageReq": { "additionalProperties": false, "description": "`POST /manage/platform-images` body.", "properties": { "description": { "description": "At most 256 characters.", "type": [ "string", "null" ] }, "name": { "description": "Image name tenants create from. A label (`[A-Za-z0-9._-]`, no\nreserved prefix) that does not start with `img_`.", "example": "daytona-base", "type": "string" }, "ref": { "description": "Registry ref pinned by digest: `[host[:port]/]path[:tag]@sha256:<64 hex>`.\nPublic registries only.", "example": "docker.io/library/python@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "type": "string" } }, "required": [ "name", "ref" ], "type": "object" }, "PublishPlatformImageResp": { "description": "`202` body of a publish that enqueued an import.", "properties": { "image": { "$ref": "#/components/schemas/PlatformImage" }, "job_id": { "description": "The import job.", "format": "uuid", "type": "string" } }, "required": [ "image", "job_id" ], "type": "object" }, "PutGlobalRegistryReq": { "additionalProperties": false, "description": "`PUT /manage/registries/global` body: create or replace the credential\nfor `(host, repository_prefix)`. The password is write-only.", "properties": { "description": { "type": [ "string", "null" ] }, "host": { "description": "Registry host (`host[:port]`, no scheme/path).", "example": "ghcr.io", "type": "string" }, "import_only": { "description": "Import-only (v1 migration): use the credential only for pulls of\nimages the platform imported from Daytona v1 (archived-sandbox\nimports), never for an organization's own pull of the same ref. Set\nit for a Daytona v1 registry, which holds every organization's\nbackups. Absent on a create = `false`; absent on a replace KEEPS the\nstored value, so a client that predates the field (a script, a stale\nsuperadmin bundle) can never silently turn an import-only row into an\nordinary global credential every organization pulls with.", "type": "boolean" }, "kind": { "default": "basic", "description": "Auth kind: one of `basic`, `ghcr`, `gcr`, `ecr`.", "example": "basic", "type": "string" }, "password": { "description": "Password, token, service-account JSON or AWS secret access key (max\n64 KiB). Write-only. Empty keeps the stored password, allowed only when\nthe row exists and its kind and username are unchanged.", "type": "string" }, "repository_prefix": { "description": "Repository prefix (`/`-separated lowercase segments); empty or absent\ncovers every repository on the host.", "example": "daytonaio/sandbox", "type": "string" }, "username": { "type": "string" } }, "required": [ "host", "username" ], "type": "object" }, "PutOtelConfigReq": { "additionalProperties": false, "description": "`PUT /orgs/:id/otel-config` request body. `headers` defaults to empty;\nan unknown field is a `400` (a misspelt `header` would otherwise replace\nthe config with one that has no headers and answer `200`).", "properties": { "endpoint": { "description": "OTLP/HTTP endpoint (`https://\u2026`; plaintext `http` only where the deployment allows insecure endpoints).", "type": "string" }, "headers": { "additionalProperties": { "type": "string", "writeOnly": true }, "description": "Request headers sent to the endpoint, name \u2192 value. Values are write-only: no read returns them.", "propertyNames": { "type": "string", "writeOnly": true }, "type": "object" } }, "required": [ "endpoint" ], "type": "object" }, "PutProjectBudgetReq": { "additionalProperties": false, "description": "`PUT /projects/{id}/budget` body.", "properties": { "monthly_limit_cents": { "description": "The monthly budget, in US cents: an integer from `100` ($1.00) to\n`100000000000` ($1 billion).", "format": "int64", "maximum": 100000000000, "minimum": 100, "type": "integer" } }, "required": [ "monthly_limit_cents" ], "type": "object" }, "PutRegistryBodyReq": { "description": "Body form for `PUT /registries` (host in the body instead of the path).\nThe password is **write-only**: encrypted at rest, never returned.", "properties": { "description": { "type": [ "string", "null" ] }, "host": { "description": "Registry host (`host[:port]`, no scheme/path). Docker Hub aliases\nnormalize to `index.docker.io`.", "example": "ghcr.io", "type": "string" }, "kind": { "default": "basic", "description": "Auth kind: one of `basic`, `ghcr`, `gcr`, `ecr`, `ecr_role`. For\n`ecr_role` the username is the IAM role ARN the platform assumes\n(ExternalId = the organization id) and the password is ignored.", "example": "basic", "type": "string" }, "password": { "description": "Registry password/token (max 64 KiB). Write-only \u2014 never echoed back\nby any public read endpoint. Required for every kind but `ecr_role`,\nwhich ignores it.", "type": "string" }, "username": { "type": "string" } }, "required": [ "host", "username" ], "type": "object" }, "PutRegistryReq": { "description": "Credential payload for `PUT /registries/{host}`. The password is\n**write-only**: it is encrypted at rest and no public endpoint returns it.", "properties": { "description": { "type": [ "string", "null" ] }, "kind": { "default": "basic", "description": "Auth kind: one of `basic`, `ghcr`, `gcr`, `ecr`, `ecr_role`. For\n`ecr_role` the username is the IAM role ARN the platform assumes\n(ExternalId = the organization id) and the password is ignored.", "example": "basic", "type": "string" }, "password": { "description": "Registry password/token (max 64 KiB). Write-only \u2014 never echoed back\nby any public read endpoint. Required for every kind but `ecr_role`,\nwhich ignores it.", "type": "string" }, "username": { "type": "string" } }, "required": [ "username" ], "type": "object" }, "PutSecretBodyReq": { "properties": { "allowed_domains": { "items": { "type": "string" }, "type": "array" }, "description": { "type": [ "string", "null" ] }, "if_not_exists": { "description": "Create-only mode: 409 if the name already exists (see PutSecretReq).", "type": "boolean" }, "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "PutSecretReq": { "description": "PUT /secrets/{name} body. The secret `value` is **write-only**: it is\naccepted here, AES-256-GCM encrypted at rest, and NEVER returned by any\nendpoint \u2014 response DTOs carry metadata only.", "properties": { "allowed_domains": { "description": "Required per-secret egress scope: hostnames or `*.` wildcards, or\n`[\"*\"]` for any verified host. Empty or omitted is rejected.", "items": { "type": "string" }, "type": "array" }, "description": { "type": [ "string", "null" ] }, "if_not_exists": { "description": "When true the write is create-only: 409 if a secret with this name\nalready exists, instead of updating it. The existence check runs inside\nthe same row-locked transaction as the write, so clients get an atomic\n\"create unless taken\" (a separate list/get pre-check cannot exclude a\nconcurrent create).", "type": "boolean" }, "value": { "description": "The secret value (max 64 KiB). Write-only \u2014 never echoed back.", "type": "string" } }, "required": [ "value" ], "type": "object" }, "RedeemCouponResponse": { "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "RegionCatalogResp": { "description": "The platform's region catalog: the Macro regions a caller may target,\ngrouped by Geo group under the Global root (PLAN-REGION-CATALOG.md).", "properties": { "global": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "The Global root. Keys are Geo group IDs (`us`, `eu`, \u2026); each value\nlists that group's Macro region IDs, sorted. A Macro region is one\nworkload cell, and its ID is a valid create-time `region` selector. Geo\ngroups with no Macro region the caller may target are omitted.", "example": { "eu": [ "eu-central" ], "us": [ "us-east", "us-west" ] }, "propertyNames": { "type": "string" }, "type": "object" } }, "required": [ "global" ], "type": "object" }, "RegionHierarchy": { "description": "The region hierarchy as flat, typed nodes (PLAN-REGION-HIERARCHY.md).\n\nOne response carries every level \u2014 Global (Earth), Geo groups, Macro regions\n(one cell each) and Edge regions \u2014 with each node naming its parent, so a client\nrebuilds the tree without the payload repeating an Edge region under each of\nits ancestors.", "properties": { "nodes": { "items": { "$ref": "#/components/schemas/RegionNode" }, "type": "array" }, "schema_version": { "description": "Response shape version. Bumped when the node contract changes, so a\nclient can refuse a shape it does not understand instead of guessing.", "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "schema_version", "nodes" ], "type": "object" }, "RegionInfo": { "description": "A cached region row. `id` is the slug (also the Daytona `target` and the\nrunner's region identifier).", "properties": { "api_base_url": { "description": "The public base URL of the API that serves this region directly\n(`https://api..`), when the operator publishes one.\nClients that address cells individually send this region's requests\nthere, and a cell that refuses a request for this region names it in the\n409. Absent => no regional URL is published; use the API you are\nalready talking to (the SDKs always do, so the shared router routes for\nthem). A routing hint only: it does not say which cell owns the region.", "type": [ "string", "null" ] }, "auto_placement_enabled": { "description": "May a broad selector (Global / Geo / Macro) place a sandbox here\nautomatically? An exact create naming this slug is unaffected.\n\nThis is the successor to \"NULL membership means excluded\": topological\nmembership is mandatory under the hierarchy, so deliberately excluding a\nfleet (an arch-specific test cell, a private cell) needs a field of its\nown rather than the absence of a parent.", "type": "boolean" }, "gpu_runners_allow_linux": { "description": "May a GPU runner in this region also serve ordinary non-GPU (Linux)\nsandboxes? (PLAN-GPU-BACKENDS.md.) DEFAULT false => GPU hosts are\nreserved for GPU work (a GPU runner skips binding the ordinary\n`jobs.vm.create.linux.` + persistent consumers). Non-GPU runners\nignore this. The runner reads it on startup over\n`internal.region.config.` (NATS request/reply).", "type": "boolean" }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "macro_region_id": { "description": "Mandatory Macro (one cell) parent. Global ancestry comes from the Macro.", "type": "string" }, "name": { "type": "string" }, "preview_domain": { "description": "Per-region HTTP preview base domain (PROXY.md \u00a73.05). NULL => the\ndeployment fallback. Preview URLs are `://-./`.", "type": [ "string", "null" ] }, "status": { "type": "string" }, "toolbox_proxy_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "status", "is_default", "gpu_runners_allow_linux", "macro_region_id", "auto_placement_enabled" ], "type": "object" }, "RegionLevel": { "description": "Public hierarchy categories: Global (Earth) -> Geo -> Macro -> Edge.\nThese are category names, not selector IDs or durable placement kind tags.", "enum": [ "global", "geo", "macro", "edge" ], "type": "string", "x-daytona-open-enum": true }, "RegionNode": { "description": "One node of the region hierarchy, flat and typed so a client can rebuild the\ntree without the response repeating an Edge region under each ancestor\n(PLAN-REGION-HIERARCHY.md).\n\nThe counts are INVENTORY, not capacity: they say what the catalog contains\nand what a broad selector is allowed to choose, never whether a runner is\nonline. `None` means the serving process cannot count local regions (a\n`central` deployment owns the topology but no local rows) \u2014 distinct from\n`Some(0)`, which means the topology really is empty there.", "properties": { "auto_placement_enabled": { "description": "Edge nodes only: whether broad placement may select this region.", "type": [ "boolean", "null" ] }, "cell_id": { "description": "Macro nodes only: the workload cell this macro region represents.", "type": [ "string", "null" ] }, "child_count": { "description": "Immediate structural children in this response.", "minimum": 0, "type": "integer" }, "eligible_local_region_count": { "description": "Edge descendants a broad selector may actually place in.", "minimum": 0, "type": [ "integer", "null" ] }, "id": { "type": "string" }, "level": { "$ref": "#/components/schemas/RegionLevel" }, "local_region_count": { "description": "Structural Edge descendants, INCLUDING ones excluded from broad\nplacement. Always 1 on an Edge node. The field retains its wire name.", "minimum": 0, "type": [ "integer", "null" ] }, "macro_region_id": { "description": "Edge nodes only: the mandatory Macro parent.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "parent_id": { "description": "The immediate parent, or `None` for the Global root (Earth).", "type": [ "string", "null" ] }, "selectable": { "description": "Local execution eligibility for a broad node, or direct routability for\nan Edge node. This is distinct from fleet-wide discovery counts.\nRouter-aware clients evaluate their separate request path rather than\ntreating the discovery API's local scope as a fleet-wide prohibition.\n\n * **Broad node** (Global/Geo/Macro): at least one descendant this API\n may itself place in \u2014 active, routable, opted in, and among the\n regions this API is configured to serve. An API serving no members\n reports positive counts with `selectable: false`; a separate shared\n router can still place there. Global/Geo requires that router's\n binding/receipt protocol regardless of this flag.\n * **Edge node**: active and routable \u2014 i.e. the catalog publishes an\n address a client can send the create to, and the Edge stays\n selectable by its exact slug even when excluded from broad\n placement. Reaching it requires a client that actually routes to\n that address (the dashboard does); one that posts every create to a\n single configured API still gets the owning-cell refusal from an API\n that does not serve the Edge.\n\nNecessary, not sufficient \u2014 class-aware narrowing, artifact locality and\nadmission all still apply after selection. A process that cannot count\nlocal regions reports every broad node as not selectable, because it\ngenuinely cannot tell.", "type": "boolean" }, "status": { "description": "Edge nodes only: the configured catalog status (`active`/`disabled`).", "type": [ "string", "null" ] } }, "required": [ "id", "name", "level", "child_count", "selectable" ], "type": "object" }, "RegistryMeta": { "description": "Registry credential **metadata** as returned by every read endpoint (list\nand get, on both planes). Passwords are write-only: they never appear here\nor on any other response.", "properties": { "description": { "type": [ "string", "null" ] }, "host": { "description": "Normalized registry host (Docker Hub aliases collapse to\n`index.docker.io`).", "example": "ghcr.io", "type": "string" }, "kind": { "description": "Auth kind (`basic`, `ghcr`, `gcr`, `ecr`, `ecr_role`). For `ecr_role`\nthe username is the IAM role ARN the platform assumes.", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "username": { "type": "string" } }, "required": [ "host", "kind", "username", "updated_at" ], "type": "object" }, "RemovalPreviewResponse": { "properties": { "revoked_keys": { "format": "int64", "type": "integer" }, "revoked_preview_grants": { "description": "Signed preview grants the member minted that removal would delete\n(issue #1297, Leg B). `null` \u2014 not 0 \u2014 when Redis is unconfigured or\nunreachable: an unknown must not read as an all-clear.", "format": "int64", "type": [ "integer", "null" ] }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "revoked_keys" ], "type": "object" }, "RemovedMemberResponse": { "properties": { "removed": { "format": "uuid", "type": "string" }, "revoked_keys": { "format": "int64", "minimum": 0, "type": "integer" }, "revoked_preview_grants": { "description": "Signed preview grants the member minted that the removal deleted\n(issue #1297, Leg B; PLAN-MEMBER-REMOVAL-KEY-REVOCATION.md D12).", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "removed", "revoked_keys", "revoked_preview_grants" ], "type": "object" }, "RemovedProjectMemberResponse": { "properties": { "removed": { "format": "uuid", "type": "string" }, "revoked_keys": { "minimum": 0, "type": "integer" } }, "required": [ "removed", "revoked_keys" ], "type": "object" }, "RemovedProjectServiceAccountResponse": { "properties": { "removed": { "format": "uuid", "type": "string" }, "revoked_keys": { "minimum": 0, "type": "integer" } }, "required": [ "removed", "revoked_keys" ], "type": "object" }, "RenamedOrganizationResponse": { "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "RevokedInvitationResponse": { "properties": { "revoked": { "format": "uuid", "type": "string" } }, "required": [ "revoked" ], "type": "object" }, "RevokedOrgApiKeyResponse": { "properties": { "revoked": { "format": "uuid", "type": "string" } }, "required": [ "revoked" ], "type": "object" }, "RevokedProjectApiKeyResponse": { "properties": { "revoked": { "format": "uuid", "type": "string" } }, "required": [ "revoked" ], "type": "object" }, "RoleResponse": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "permissions": { "items": { "type": "string" }, "type": "array" }, "system": { "type": "boolean" } }, "required": [ "id", "name", "description", "system", "permissions" ], "type": "object" }, "RolesCatalogResponse": { "properties": { "permissions": { "items": { "$ref": "#/components/schemas/PermissionMetadataResponse" }, "type": "array" }, "roles": { "items": { "$ref": "#/components/schemas/RoleResponse" }, "type": "array" } }, "required": [ "permissions", "roles" ], "type": "object" }, "RunnerAdminStateResp": { "properties": { "admin_state": { "type": "string" }, "id": { "type": "string" }, "runner_reached": { "type": "boolean" } }, "required": [ "id", "admin_state", "runner_reached" ], "type": "object" }, "RunnerCapacityResp": { "description": "One runner's capacity report.", "properties": { "capacity": { "description": "Capacity document as produced by the runner (free-form JSON)." }, "id": { "description": "Runner id.", "type": "string" }, "source": { "description": "`live` \u2014 fresh NATS probe of the runner; `heartbeat` \u2014 the runner was\nunreachable, so this is its last stored heartbeat capacity.", "example": "live", "type": "string" } }, "required": [ "id", "source", "capacity" ], "type": "object" }, "RunnerDetailResp": { "properties": { "admin_state": { "type": "string" }, "build_sha": { "description": "Full 40-hex commit the runner was built from (`unknown` unstamped). Null\nuntil the runner reports it.", "type": [ "string", "null" ] }, "build_time": { "description": "When the runner was built. Null until reported, or when the reported\nvalue is not RFC 3339 (an unstamped build reports `unknown`).", "format": "date-time", "type": [ "string", "null" ] }, "cpu_arch": { "type": "string" }, "cpu_serves": { "description": "Registry slugs the runner serves as tier fallback, as reported on its\nlast register/heartbeat (PLAN-CPU-CATALOG-FROM-RUNNERS.md). Empty on a\nflag-off or old runner. The API always emits it; it is not required in\nthe schema so generated clients decode a pre-upgrade cell's response,\nwhere the key is absent, as unset (`None`/`undefined`) rather than\nfailing.", "items": { "type": "string" }, "type": "array" }, "cpu_type": { "type": [ "string", "null" ] }, "disk_class": { "type": [ "string", "null" ] }, "disk_serves": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_seen_at": { "format": "date-time", "type": "string" }, "network_class": { "type": [ "string", "null" ] }, "network_serves": { "items": { "type": "string" }, "type": "array" }, "not_consuming": { "type": "boolean" }, "public_ip": { "type": [ "string", "null" ] }, "runner_proxy_ip": { "type": [ "string", "null" ] }, "runner_proxy_port": { "format": "int32", "type": [ "integer", "null" ] }, "sandbox_count": { "minimum": 0, "type": "integer" }, "sandbox_network_mode": { "type": "string" }, "sandboxes": { "items": { "$ref": "#/components/schemas/RunnerSandbox" }, "type": "array" }, "self_cordoned": { "type": "boolean" }, "status": { "type": "string" }, "usage": { "description": "Runner-reported capacity/usage document. The runner owns this JSON shape.", "type": "object" }, "usage_source": { "type": "string" }, "version": { "description": "Platform version the runner binary was stamped with (PLAN-BUILD-IDENTITY.md\nD9; `0.0.0-dev` on an unstamped build). Null until the runner reports it.", "type": [ "string", "null" ] } }, "required": [ "id", "status", "admin_state", "cpu_arch", "network_serves", "disk_serves", "last_seen_at", "usage", "usage_source", "self_cordoned", "not_consuming", "sandbox_count", "sandboxes" ], "type": "object" }, "RunnerListResp": { "properties": { "runners": { "items": { "$ref": "#/components/schemas/RunnerOverview" }, "type": "array" } }, "required": [ "runners" ], "type": "object" }, "RunnerOverview": { "properties": { "admin_state": { "type": "string" }, "build_sha": { "description": "Full 40-hex commit the runner was built from (`unknown` unstamped). Null\nuntil the runner reports it.", "type": [ "string", "null" ] }, "build_time": { "description": "When the runner was built. Null until reported, or when the reported\nvalue is not RFC 3339 (an unstamped build reports `unknown`).", "format": "date-time", "type": [ "string", "null" ] }, "capacity_stale": { "type": "boolean" }, "cpu_arch": { "type": "string" }, "cpu_serves": { "description": "Registry slugs the runner serves as tier fallback, as reported on its\nlast register/heartbeat (PLAN-CPU-CATALOG-FROM-RUNNERS.md). Empty on a\nflag-off or old runner. The API always emits it; it is not required in\nthe schema so generated clients decode a pre-upgrade cell's response,\nwhere the key is absent, as unset (`None`/`undefined`) rather than\nfailing.", "items": { "type": "string" }, "type": "array" }, "cpu_type": { "type": [ "string", "null" ] }, "disk_class": { "type": [ "string", "null" ] }, "disk_serves": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "last_seen_at": { "format": "date-time", "type": "string" }, "network_class": { "type": [ "string", "null" ] }, "network_serves": { "items": { "type": "string" }, "type": "array" }, "not_consuming": { "type": "boolean" }, "orphans": { "format": "int64", "type": "integer" }, "public_ip": { "type": [ "string", "null" ] }, "region": { "type": "string" }, "runner_proxy_ip": { "type": [ "string", "null" ] }, "runner_proxy_port": { "format": "int32", "type": [ "integer", "null" ] }, "sandbox_network_mode": { "type": "string" }, "sandboxes": { "format": "int64", "type": "integer" }, "self_cordoned": { "type": "boolean" }, "status": { "type": "string" }, "usage": { "description": "Runner-reported capacity/usage document. The runner owns this JSON shape.", "type": "object" }, "usage_source": { "type": "string" }, "version": { "description": "Platform version the runner binary was stamped with (PLAN-BUILD-IDENTITY.md\nD9; `0.0.0-dev` on an unstamped build). Null until the runner reports it.", "type": [ "string", "null" ] } }, "required": [ "id", "status", "admin_state", "region", "cpu_arch", "network_serves", "disk_serves", "sandboxes", "orphans", "usage", "usage_source", "capacity_stale", "self_cordoned", "not_consuming", "last_seen_at" ], "type": "object" }, "RunnerSandbox": { "properties": { "cpu": { "format": "double", "type": [ "number", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "ephemeral": { "type": "boolean" }, "forked": { "type": "boolean" }, "id": { "type": "string" }, "image": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VmArtifactRef", "description": "The image the sandbox booted (`img_\u2026` id + name), or null when it\nresumed a memory snapshot (PLAN-CREATION-SHAPE \u00a71)." } ] }, "image_ref": { "description": "Function instances (and deleted rows) only; null for sandboxes.", "type": [ "string", "null" ] }, "mem_max_mib": { "format": "int32", "type": [ "integer", "null" ] }, "mem_mib": { "format": "int32", "type": "integer" }, "name": { "type": "string" }, "persistent": { "type": "boolean" }, "scratch_max_mib": { "format": "int32", "type": [ "integer", "null" ] }, "scratch_mib": { "format": "int32", "type": "integer" }, "snapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VmArtifactRef", "description": "The memory snapshot the sandbox resumed (`snap_\u2026` id + name), or null." } ] }, "spot": { "type": "boolean" }, "status": { "type": "string" }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunnerSandboxUsage" } ] }, "vcpus": { "format": "int32", "type": "integer" }, "vcpus_max": { "format": "int32", "type": [ "integer", "null" ] }, "vm_ip": { "type": [ "string", "null" ] }, "volumes": { "items": { "$ref": "#/components/schemas/RunnerSandboxVolume" }, "type": "array" } }, "required": [ "id", "name", "status", "vcpus", "mem_mib", "scratch_mib", "volumes", "ephemeral", "persistent", "spot", "forked", "created_at" ], "type": "object" }, "RunnerSandboxUsage": { "properties": { "cpu_cores": { "format": "double", "type": "number" }, "mem_mib": { "format": "double", "type": "number" }, "mem_peak_mib": { "format": "double", "type": "number" } }, "required": [ "cpu_cores", "mem_mib", "mem_peak_mib" ], "type": "object" }, "RunnerSandboxVolume": { "properties": { "mount_path": { "type": "string" }, "subpath": { "type": [ "string", "null" ] }, "volume_id": { "format": "uuid", "type": "string" } }, "required": [ "volume_id", "mount_path" ], "type": "object" }, "SearchPage": { "description": "Response of `GET /sandboxes/search` (\u00a74.2).", "properties": { "next_cursor": { "description": "Continuation token for the next page; null on the last page.", "type": [ "string", "null" ] }, "partial_regions": { "description": "Regions whose cell has not yet reported the index the read alias\npoints to as backfilled, or has never heartbeated: results for them\nmay be incomplete. Empty in steady state. Filled in by the route\n(\u00a76); the query itself does not know it.", "items": { "type": "string" }, "type": "array" }, "total": { "description": "Matching sandboxes. Exact while `total_relation` is `eq`; a lower\nbound (the 10 000 tracking floor) when it is `gte`.", "format": "int64", "minimum": 0, "type": "integer" }, "total_relation": { "description": "`eq` or `gte`.", "example": "eq", "type": "string" }, "vms": { "items": { "$ref": "#/components/schemas/SearchVm" }, "type": "array" } }, "required": [ "vms", "total", "total_relation", "partial_regions" ], "type": "object" }, "SearchVm": { "allOf": [ { "$ref": "#/components/schemas/VmRow" }, { "properties": { "created_at": { "format": "date-time", "type": "string" }, "cursor": { "description": "This item's opaque resume token \u2014 pass it as `?cursor=` (with the same\nfilter and sort) to resume immediately after this item.", "type": "string" }, "forked_from": { "description": "External id of the sandbox this one was forked from, or null.", "type": [ "string", "null" ] }, "gpu_host_count": { "format": "int32", "type": "integer" }, "labels": { "description": "`{ \"k\": \"v\" }`; `{}` when the sandbox has none." }, "last_activity_at": { "format": "date-time", "type": [ "string", "null" ] }, "lifecycle": { "$ref": "#/components/schemas/LifecycleDto", "description": "Assembled at read time from the indexed timeout/idle-timeout pairs and\nactivity clock; byte-equal to the list item's `lifecycle` for the same\nsandbox." }, "os_family": { "type": [ "string", "null" ] }, "persistent": { "type": "boolean" }, "spot": { "type": "boolean" }, "spot_evicted_at": { "format": "date-time", "type": [ "string", "null" ] }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "stopped_at": { "format": "date-time", "type": [ "string", "null" ] }, "toolbox_proxy_url": { "description": "The sandbox's own region's toolbox proxy base URL, the same value\n`GET /sandboxes/{id}` carries \u2014 exec/fs/preview traffic must target\nthis, not a global proxy. Resolved from the answering cell's catalog\nor, for another cell's region, from that cell's search heartbeat.\nAbsent when no cell has published one for the region yet, or the\nheartbeats could not be read and none were cached: read it from\n`GET /sandboxes/{id}` for those (the SDKs do this when building the\nhandle).", "type": "string" }, "updated_at": { "description": "When the row last changed \u2014 how stale this hit can be (the index is\neventually consistent).", "format": "date-time", "type": [ "string", "null" ] }, "windows_image": { "type": [ "string", "null" ] } }, "required": [ "created_at", "cursor", "spot", "persistent", "gpu_host_count", "labels", "lifecycle" ], "type": "object" } ], "description": "One search hit: every field of the `GET /sandboxes` list item (`VmPageRow`) \u2014\nthe flattened `VmRow` wire shape plus `created_at`, `cursor`, `spot`,\n`spot_evicted_at`, `persistent`, `gpu_host_count`, `os_family`,\n`windows_image`, `labels`, `lifecycle` \u2014 plus the lifecycle timestamps and\nlineage \u00a74.2 adds. `id` and `forked_from` are always the region-tagged\nexternal id of the sandbox's own region, so they route to its cell." }, "SecretListItem": { "description": "One row of the GET /secrets list: metadata only \u2014 the secret **value is\nwrite-only** and never appears here.", "properties": { "allowed_domains": { "description": "Per-secret egress scope. `[\"*\"]` means any verified host; a legacy empty\nlist means this secret is sent nowhere.", "items": { "type": "string" }, "type": "array" }, "description": { "type": [ "string", "null" ] }, "name": { "example": "OPENAI_API_KEY", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "allowed_domains", "name", "updated_at" ], "type": "object" }, "SecretMeta": { "description": "One secret's metadata (GET /secrets/{name}). The secret **value is\nwrite-only** and never present on this or any other response. Fields are\ndeclared alphabetically: the response is serialized through\n`serde_json::Value`, which orders keys alphabetically.", "properties": { "allowed_domains": { "description": "Per-secret egress scope. `[\"*\"]` means any verified host; a legacy empty\nlist means this secret is sent nowhere.", "items": { "type": "string" }, "type": "array" }, "description": { "type": [ "string", "null" ] }, "name": { "example": "OPENAI_API_KEY", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "allowed_domains", "name", "updated_at" ], "type": "object" }, "SelfServeLimitsRequest": { "additionalProperties": false, "description": "Body of the member-facing `PATCH /orgs/:id/limits`\n(PLAN-LIFECYCLE-TIMEOUTS.md Decision 7): the ONE self-service field. The\nsame double-Option tri-state as the internal assignment, so an absent\nfield (an empty `{}` body) is a loud 400 rather than a silent clear.", "properties": { "max_timeout_secs": { "format": "int64", "type": [ "integer", "null" ] } }, "type": "object" }, "SelfServeLimitsResponse": { "description": "The refreshed `timeouts` group after the write, so the Limits page can\nre-render from the response.", "properties": { "timeouts": { "$ref": "#/components/schemas/TimeoutLimits" } }, "required": [ "timeouts" ], "type": "object" }, "ServiceAccountResponse": { "properties": { "archived_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "format": "uuid", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "live_key_count": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "permissions": { "items": { "type": "string" }, "type": "array" }, "roles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "org_id", "name", "roles", "permissions", "created_at", "live_key_count" ], "type": "object" }, "ServiceAccountUpdateResponse": { "oneOf": [ { "$ref": "#/components/schemas/DryRunNarrowingResponse" }, { "$ref": "#/components/schemas/UpdatedServiceAccountResponse" } ] }, "ServiceAccountsResponse": { "properties": { "service_accounts": { "items": { "$ref": "#/components/schemas/ServiceAccountResponse" }, "type": "array" } }, "required": [ "service_accounts" ], "type": "object" }, "SetPlatformDefaultReq": { "additionalProperties": false, "description": "`PUT /manage/platform-images/default` body.", "properties": { "class": { "description": "The sandbox class the default serves. Only `linux`.", "example": "linux", "type": "string" }, "image": { "description": "The platform image's name or `img_\u2026` id.", "example": "daytona-base", "type": "string" } }, "required": [ "class", "image" ], "type": "object" }, "SetVmLabelsReq": { "description": "Request body for `PUT /sandboxes/{id}/labels`: the full replacement label set.", "properties": { "labels": { "additionalProperties": { "type": "string" }, "default": {}, "description": "The new label set (REPLACES the current one; `{}` clears all labels).", "propertyNames": { "type": "string" }, "type": "object" } }, "type": "object" }, "SignFileUrlReq": { "additionalProperties": false, "description": "`POST /vms/{id}/files/sign` body (PLAN-SIGNED-FILE-URLS.md \u00a71).", "properties": { "expires": { "description": "Absolute expiry, Unix seconds. Must lie in the future and at most the\ndeployment's signed-URL ceiling ahead (7 days by default); `0`\n(never) is refused \u2014 a pre-signed link always expires.", "format": "int64", "type": "integer" }, "method": { "description": "`GET` signs a download link (`/files/download`), `POST` an upload link\n(`/files/upload`) \u2014 the two operations the proxy accepts a signature\nfor.", "type": "string" }, "path": { "description": "Guest path the link addresses, verbatim (the canonical and the URL's\n`path` query parameter carry the same string).", "type": "string" } }, "required": [ "method", "path", "expires" ], "type": "object" }, "SignedFileUrlResp": { "description": "`POST /vms/{id}/files/sign` response: the link, plus its parts so a client\nwith its own toolbox base (a direct `toolbox_url`) can recompose it.", "properties": { "expires": { "description": "The expiry that was signed (Unix seconds).", "format": "int64", "type": "integer" }, "method": { "description": "`GET` or `POST`, as signed.", "type": "string" }, "path": { "description": "The guest path, as signed.", "type": "string" }, "signature": { "description": "`v1_` + base64url(HMAC-SHA256(signing key, canonical)), no padding.", "type": "string" }, "url": { "description": "The full pre-signed URL against the sandbox region's toolbox proxy.", "type": "string" } }, "required": [ "url", "method", "path", "expires", "signature" ], "type": "object" }, "SignedPreviewUrlResp": { "description": "A signed preview link (`GET /sandboxes/{id}/ports/{port}/signed-preview-url`).", "properties": { "expires_at": { "description": "When the link stops resolving (natural expiry).", "format": "date-time", "type": "string" }, "token": { "description": "The plaintext signed token (`s` + 32 hex). Returned exactly once, here;\nonly its hash is stored. Needed separately from `url` for the expire\nroute.", "type": "string" }, "url": { "description": "Host-based preview URL, `://-./` \u2014 the\ntoken replaces the sandbox id in the hostname, so the link reveals no\nsandbox identity.", "type": "string" } }, "required": [ "url", "token", "expires_at" ], "type": "object" }, "SigningKeyRotatedResp": { "description": "`POST /vms/{id}/signing-key/rotate` answer: the rotation happened. The new\nkey is never returned (PLAN-SIGNED-FILE-URLS.md \u00a73) \u2014 the next\n`POST \u2026/files/sign` signs with it.", "properties": { "rotated": { "description": "Always `true` on success; the request fails otherwise.", "type": "boolean" } }, "required": [ "rotated" ], "type": "object" }, "SnapshotPageRow": { "allOf": [ { "$ref": "#/components/schemas/SnapshotRow" }, { "properties": { "created_at": { "format": "date-time", "type": "string" }, "cursor": { "description": "This row's opaque keyset token \u2014 pass it as `?cursor=` to resume the list\nimmediately after this row. Not a column: the handler fills it via the\nsame encoder that builds `next_cursor`, so the token stays opaque and\nserver-owned. `#[sqlx(default)]` keeps `FromRow` happy for the SELECT\nthat has no such column.", "type": "string" } }, "required": [ "created_at", "cursor" ], "type": "object" } ], "description": "A `SnapshotRow` plus the keyset fields, mirroring `VmPageRow`.\n\n`created_at` and `cursor` are BOTH on the wire (PLAN-DASHBOARD-REGIONS.md\n\u00a75.1): a client merging the snapshot streams of several regional cells needs\nthe sort key to order them and a per-row cursor to resume ONE cell mid-page\n\u2014 whole-page `next_cursor` cannot express \"shown up to here in region A but\nonly to there in region B\". Both are additive." }, "SnapshotRow": { "properties": { "artifact_ref": { "type": [ "string", "null" ] }, "available_in": { "items": { "type": "string" }, "type": "array" }, "bytes": { "format": "int64", "type": [ "integer", "null" ] }, "class": { "example": "linux", "type": "string" }, "cpu_marker": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "fc_version": { "type": [ "string", "null" ] }, "id": { "example": "snap_7fJk2mQpXv9dLc3RtY", "type": "string" }, "kind": { "example": "full", "type": "string" }, "mem_bytes": { "format": "int64", "type": [ "integer", "null" ] }, "name": { "type": "string" }, "parent_manifest": { "type": [ "string", "null" ] }, "region": { "type": "string" }, "runner_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "vm_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "id", "name", "class", "kind", "status", "region", "available_in" ], "type": "object" }, "SoftLimits": { "properties": { "max_concurrent_builds": { "$ref": "#/components/schemas/EffectiveLimit" }, "max_concurrent_vms": { "$ref": "#/components/schemas/EffectiveLimit" }, "max_total_vms": { "$ref": "#/components/schemas/EffectiveLimit" } }, "required": [ "max_concurrent_vms", "max_total_vms", "max_concurrent_builds" ], "type": "object" }, "SshGatewayConfig": { "description": "The `ssh_gateway` block of [`Config`].", "properties": { "host": { "type": "string" }, "port": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "host", "port" ], "type": "object" }, "SsoConnection": { "description": "One SSO connection of an organization, as configured in the WorkOS Admin\nPortal.", "properties": { "connection_type": { "description": "WorkOS's connection type, e.g. `OktaSAML`, `GenericOIDC`.", "type": "string" }, "created_at": { "description": "RFC 3339 timestamps, as WorkOS reports them.", "type": "string" }, "domains": { "description": "The email domains the connection signs in.", "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "name": { "type": "string" }, "state": { "description": "WorkOS's `ConnectionState`: `active` accepts logins; `draft` and\n`requires_type` mean the Admin Portal setup is unfinished; `validating`\nis being checked; `inactive` is switched off; `deleting` is being\nremoved. Passed through as WorkOS spells it.", "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "connection_type", "state", "domains", "created_at", "updated_at" ], "type": "object" }, "SsoConnectionsResponse": { "properties": { "connections": { "items": { "$ref": "#/components/schemas/SsoConnection" }, "type": "array" } }, "required": [ "connections" ], "type": "object" }, "StoredEphemeralPolicyDto": { "properties": { "idle_timeout_secs": { "format": "int64", "type": [ "integer", "null" ] }, "timeout_secs": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "timeout_secs", "idle_timeout_secs" ], "type": "object" }, "StoredPersistentPolicyDto": { "properties": { "idle_timeout_secs": { "format": "int64", "type": [ "integer", "null" ] }, "on_idle_timeout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction" } ] }, "on_timeout": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LifecycleAction" } ] }, "timeout_secs": { "format": "int64", "type": [ "integer", "null" ] }, "wake_on_request": { "type": "boolean" } }, "required": [ "timeout_secs", "on_timeout", "idle_timeout_secs", "on_idle_timeout", "wake_on_request" ], "type": "object" }, "StoredPolicyDto": { "properties": { "ephemeral": { "$ref": "#/components/schemas/StoredEphemeralPolicyDto" }, "persistent": { "$ref": "#/components/schemas/StoredPersistentPolicyDto" } }, "required": [ "ephemeral", "persistent" ], "type": "object" }, "StrictLimits": { "properties": { "max_concurrent_gpu_vms": { "$ref": "#/components/schemas/EffectiveLimit" }, "max_concurrent_windows_vms": { "$ref": "#/components/schemas/EffectiveLimit" } }, "required": [ "max_concurrent_gpu_vms", "max_concurrent_windows_vms" ], "type": "object" }, "TimeoutLimits": { "description": "The lifecycle-timeout pair (PLAN-LIFECYCLE-TIMEOUTS.md Decision 7), as two\nplain numbers rather than the count limits' `{effective, source}` shape:\nneither has a usage half, an `unlimited` state, or a per-value source a\nclient acts on, so the objects carried nothing (Decision 7 as amended,\n2026-10-01).", "properties": { "default_timeout_secs": { "description": "What a bare create actually receives: the platform default capped at\nthe effective max \u2014 or `null` while the platform's default-timeout\nrollout gate (PLAN-LIFECYCLE-TIMEOUTS.md Decision 3) is off and the\ndefault is inert. Reporting a number the gate makes inert would claim\na guarantee that does not exist yet.", "format": "int64", "type": [ "integer", "null" ] }, "max_timeout_secs": { "description": "The effective cap every explicit `timeout_secs` is validated against:\nthe stored org cap when one is assigned, the platform max otherwise.", "format": "int64", "type": "integer" } }, "required": [ "default_timeout_secs", "max_timeout_secs" ], "type": "object" }, "TimeoutSource": { "enum": [ "project", "platform", "none" ], "type": "string", "x-daytona-open-enum": true }, "TokenExchangeRequest": { "description": "RFC 8693 \u00a72.1 token-exchange request. Accepted as JSON or as\n`application/x-www-form-urlencoded` (the RFC's native encoding).\n\nThe `audience` parameter selects the token kind\n(PLAN-ANALYTICS-PLATFORM-TOKENS.md D1): absent or `daytona:api` mints the\nproject-scoped workload token and needs `project_id`; `daytona:analytics`\nmints the org-scoped rlp-analytics token and needs `org_id`. Exactly one\nof `project_id`/`org_id` is accepted, the one the audience calls for.\n\n`audience`, `org_id`, and `project_id` may not be repeated (RFC 8693 lets\na client repeat `audience`; this exchange does not): a repeated parameter\nis a `400` in either encoding.", "properties": { "audience": { "description": "RFC 8693 target audience \u2014 selects the token kind. Omit it, or send\n`daytona:api`, for the project-scoped workload token; send\n`daytona:analytics` for the org-scoped rlp-analytics token. Any other\nvalue is refused; the parameter may not be repeated.", "example": "daytona:analytics", "type": [ "string", "null" ] }, "grant_type": { "description": "Must be `urn:ietf:params:oauth:grant-type:token-exchange`.", "example": "urn:ietf:params:oauth:grant-type:token-exchange", "type": "string" }, "org_id": { "description": "The organization the analytics token is scoped to. Required when\n`audience` is `daytona:analytics`; omitted (or `null`) otherwise.", "format": "uuid", "type": [ "string", "null" ] }, "project_id": { "description": "The project the workload token is scoped to (one exchange per\n(user, project)). Required when `audience` is absent or `daytona:api`;\nomitted (or `null`) when `audience` is `daytona:analytics`.", "format": "uuid", "type": [ "string", "null" ] }, "resource": { "description": "RFC 8693 target resource. Explicit down-scoping is not supported; omit\nthis parameter.", "type": [ "string", "null" ] }, "scope": { "description": "RFC 8693 scope request. Explicit down-scoping is not supported; omit\nthis parameter.", "type": [ "string", "null" ] }, "subject_token": { "description": "The caller's OIDC JWT. MUST be byte-identical to the Authorization\nbearer this request authenticated with \u2014 the minted identity comes\nonly from the verified bearer, never from an unverified body field.", "type": "string" }, "subject_token_type": { "description": "`urn:ietf:params:oauth:token-type:access_token` or\n`urn:ietf:params:oauth:token-type:jwt`.", "example": "urn:ietf:params:oauth:token-type:access_token", "type": "string" } }, "required": [ "grant_type", "subject_token", "subject_token_type" ], "type": "object" }, "TokenExchangeResponse": { "description": "RFC 8693 \u00a72.2.1 success response.", "properties": { "access_token": { "description": "The platform token (RFC 9068 `at+jwt`, ES256): project-scoped with\n`aud: daytona:api`, or org-scoped with `aud: daytona:analytics`.", "type": "string" }, "expires_in": { "description": "Token lifetime in seconds (default 300).", "format": "int64", "minimum": 0, "type": "integer" }, "issued_token_type": { "description": "Always `urn:ietf:params:oauth:token-type:access_token`.", "example": "urn:ietf:params:oauth:token-type:access_token", "type": "string" }, "token_type": { "description": "Always `Bearer`.", "example": "Bearer", "type": "string" } }, "required": [ "access_token", "issued_token_type", "token_type", "expires_in" ], "type": "object" }, "TopUpRequest": { "properties": { "amount_cents": { "example": 1000, "format": "int64", "maximum": 99999999, "minimum": 1000, "type": "integer" } }, "required": [ "amount_cents" ], "type": "object" }, "UnpaidInvoiceResponse": { "properties": { "amount_due_cents": { "format": "int64", "type": "integer" }, "currency": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "finalized_at": { "type": "string" }, "hosted_invoice_url": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "number": { "type": [ "string", "null" ] }, "suspends_at": { "type": [ "string", "null" ] } }, "required": [ "id", "amount_due_cents", "finalized_at" ], "type": "object" }, "UpdateEndpointReq": { "properties": { "public": { "type": "boolean" } }, "required": [ "public" ], "type": "object" }, "UpdateGlobalRegionReq": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "UpdateMacroRegionReq": { "additionalProperties": false, "description": "A Macro region's editable topology: its display name and its Geo parent\n(PLAN-REGION-HIERARCHY.md). `id` and `cell_id` are deployment-owned and\nimmutable, so they are absent here by design.\n\nAt least one field must be present \u2014 an empty body is a no-op an operator\nwould read as a successful edit.\n\nBoth fields are `Option>` so ABSENT and EXPLICIT NULL stay\ndistinguishable. Neither column is nullable: `macro_regions.name` and\n`macro_regions.global_region_id` are `NOT NULL`, and a Macro with no Geo\nparent would strand every one of its Edge regions. A plain `Option`\ncollapsed `{\"name\": null, \"global_region_id\": \"eu\"}` into \"name omitted\" and\nsilently applied half the request, which reads to the caller as a rejected\nfield that was actually accepted-and-ignored.", "properties": { "global_region_id": { "description": "New Geo parent id. Omit to keep the current value. An explicit `null`\nis rejected so the API can name the bad field instead of silently\ntreating it as absent.", "type": [ "string", "null" ] }, "name": { "description": "New Macro display name. Omit to keep the current value. An explicit\n`null` is rejected so the API can name the bad field instead of silently\ntreating it as absent.", "type": [ "string", "null" ] } }, "type": "object" }, "UpdateMemberReq": { "properties": { "dry_run": { "description": "Rehearse: run the full path and the cascade, then roll back\n(PLAN-NARROWING-REVOCATION-WARNING.md). Absent means false.", "type": [ "boolean", "null" ] }, "roles": { "description": "The member's complete new role set (slugs). Required and non-empty:\nthe handler answers 400 otherwise \u2014 `Option` only so the error names\nthe field instead of failing at deserialization.", "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "roles" ], "type": "object" }, "UpdateProjectApiKeyReq": { "properties": { "sync_to_v1": { "description": "Whether the v1 \u2194 v2 key sync keeps a copy of this key on Daytona v1.\n`false` deletes the v1 copy (the key keeps working here); `true`\ncopies the key to v1 again. A v1 copy can read every sandbox,\nsnapshot and registry of the organization on v1, which has no read\npermissions. Only a key a person minted in the organization's\n`default` project is ever copied; a key imported from v1 always is.\nRequired: it is the only field.", "type": "boolean" } }, "required": [ "sync_to_v1" ], "type": "object" }, "UpdateProjectLifecyclePolicyReq": { "additionalProperties": false, "description": "A `PATCH` at block granularity: an absent block is kept, `null` clears it,\nand an object replaces the whole block (a field missing inside it is\nunset). Blocks never merge field by field, so each one is validated on its\nown and a pair is never split between the request and the stored row.", "properties": { "ephemeral": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EphemeralPolicyReq" } ] }, "persistent": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PersistentPolicyReq" } ] } }, "type": "object" }, "UpdateReservationReq": { "additionalProperties": false, "description": "PATCH /reservations/{id} body.", "properties": { "auto_renew": { "description": "Renew the lease near each period end while a macOS sandbox is active\non it; off lets it lapse at `period_end`.", "type": "boolean" } }, "required": [ "auto_renew" ], "type": "object" }, "UpdateServiceAccountReq": { "properties": { "description": { "type": [ "string", "null" ] }, "dry_run": { "description": "Rehearse: run the full path and the cascade, then roll back\n(PLAN-NARROWING-REVOCATION-WARNING.md). Absent means false. Not a\nchange by itself: it does not count toward the at-least-one-field rule.", "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "roles": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdatedMemberResponse": { "properties": { "assignable_project_permissions": { "items": { "type": "string" }, "type": "array" }, "org_permissions": { "items": { "type": "string" }, "type": "array" }, "revoked_keys": { "format": "int64", "minimum": 0, "type": "integer" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" }, "user_id": { "format": "uuid", "type": "string" } }, "required": [ "user_id", "role", "roles", "org_permissions", "assignable_project_permissions", "revoked_keys" ], "type": "object" }, "UpdatedServiceAccountResponse": { "allOf": [ { "$ref": "#/components/schemas/ServiceAccountResponse" }, { "properties": { "revoked_keys": { "minimum": 0, "type": "integer" } }, "required": [ "revoked_keys" ], "type": "object" } ] }, "UrlResponse": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "UsageChargeResponse": { "properties": { "billable_metric": { "type": "string" }, "events_count": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "quantity": { "format": "double", "type": "number" }, "total_cents": { "format": "int64", "type": "integer" }, "units": { "type": "string" } }, "required": [ "name", "quantity", "total_cents", "units", "events_count", "billable_metric" ], "type": "object" }, "UsageHistoryResp": { "description": "Response for `GET /sandboxes/{id}/usage/history`. Field order is alphabetical to\nkeep the wire bytes identical to the former `serde_json::json!` construction.", "properties": { "available": { "description": "False when the usage collector DB is not configured (graceful empty\nstate) \u2014 `periods` is then empty and `resolution` absent.", "type": "boolean" }, "periods": { "items": { "$ref": "#/components/schemas/UsagePeriod" }, "type": "array" }, "resolution": { "description": "Effective resolution: \"m\" | \"h\". Absent when `available` is false.", "type": [ "string", "null" ] }, "sandbox_id": { "description": "The requested external sandbox id, echoed back.", "type": "string" } }, "required": [ "available", "periods", "sandbox_id" ], "type": "object" }, "UsagePeriod": { "description": "One usage bucket in `GET /sandboxes/{id}/usage/history`. Integrals (`cpu_core_s`,\n`mem_byte_s`) normalize to rates via `duration_ms`, e.g. avg cores =\n`cpu_core_s / (duration_ms / 1000)`. Field order is alphabetical to keep the\nwire bytes identical to the former `serde_json::json!` construction.", "properties": { "cpu_core_s": { "description": "CPU time consumed in the bucket, core-seconds.", "format": "double", "type": "number" }, "disk_used": { "description": "Disk used (bytes): last sample of the bucket (minute rows) or the max\nacross the hour (hourly rollups).", "format": "int64", "type": "integer" }, "duration_ms": { "description": "Wall-clock span the bucket actually covered, ms.", "format": "int64", "type": "integer" }, "io_r_bytes": { "format": "int64", "type": "integer" }, "io_w_bytes": { "format": "int64", "type": "integer" }, "mem_byte_s": { "description": "Memory integral over the bucket, byte-seconds.", "format": "double", "type": "number" }, "mem_rss_peak": { "description": "Peak RSS in the bucket, bytes.", "format": "int64", "type": "integer" }, "net_rx_bytes": { "format": "int64", "type": "integer" }, "net_tx_bytes": { "format": "int64", "type": "integer" }, "start": { "description": "Bucket start, RFC3339.", "type": "string" } }, "required": [ "cpu_core_s", "disk_used", "duration_ms", "io_r_bytes", "io_w_bytes", "mem_byte_s", "mem_rss_peak", "net_rx_bytes", "net_tx_bytes", "start" ], "type": "object" }, "UsageReport": { "description": "GET /usage/report body. `available: false` (usage DB not configured) omits\nthe interval fields entirely.", "properties": { "available": { "type": "boolean" }, "end": { "description": "RFC3339 interval upper bound (exclusive).", "type": [ "string", "null" ] }, "items": { "items": { "$ref": "#/components/schemas/UsageReportItem" }, "type": "array" }, "resolution": { "description": "`h` (hourly) | `d` (daily).", "type": [ "string", "null" ] }, "start": { "description": "RFC3339 interval lower bound (inclusive).", "type": [ "string", "null" ] } }, "required": [ "available", "items" ], "type": "object" }, "UsageReportItem": { "description": "One (sandbox, interval) usage aggregate.", "properties": { "interval_start": { "description": "RFC3339 start of the aggregation interval.", "type": "string" }, "resources": { "$ref": "#/components/schemas/UsageResources" }, "sandbox_id": { "type": "string" } }, "required": [ "sandbox_id", "interval_start", "resources" ], "type": "object" }, "UsageResources": { "description": "Aggregated resource consumption within one interval.", "properties": { "cpu_core_seconds": { "format": "double", "type": "number" }, "disk_bytes_max": { "format": "int64", "type": "integer" }, "io_r_bytes": { "format": "int64", "type": "integer" }, "io_w_bytes": { "format": "int64", "type": "integer" }, "mem_gib_hours": { "format": "double", "type": "number" }, "net_rx_bytes": { "format": "int64", "type": "integer" }, "net_tx_bytes": { "format": "int64", "type": "integer" } }, "required": [ "cpu_core_seconds", "mem_gib_hours", "disk_bytes_max", "io_r_bytes", "io_w_bytes", "net_rx_bytes", "net_tx_bytes" ], "type": "object" }, "UsageTotals": { "properties": { "active_builds": { "format": "int64", "type": "integer" }, "concurrent_vms": { "format": "int64", "type": "integer" }, "total_vms": { "format": "int64", "type": "integer" } }, "required": [ "concurrent_vms", "total_vms", "active_builds" ], "type": "object" }, "V1MigrationSummary": { "description": "Response of `GET /migration/v1/summary`.", "properties": { "api_keys": { "description": "Live API keys of the organization's `default` project. Keys synced from\nv1 work on both platforms unchanged.", "format": "int64", "type": "integer" }, "from_v1": { "description": "The organization was imported from Daytona v1 (it carries the v1\norganization id it came from). Personal organizations included.", "type": "boolean" }, "images_converted": { "description": "Named images registered from v1 snapshots that are at the current\nimage format.", "format": "int64", "type": "integer" }, "images_to_convert": { "description": "Named images registered from v1 snapshots that are still below the\ncurrent image format (`format_outdated`): not converted yet,\nconverting, or a failed conversion (retried on the next use). Each\nconverts on its first Linux sandbox create, or ahead of time with\n`POST /images/{id}/convert`.", "format": "int64", "type": "integer" }, "personal": { "description": "The organization is a personal organization.", "type": "boolean" }, "registries": { "description": "Container registries of the `default` project.", "format": "int64", "type": "integer" }, "sandboxes_imported": { "description": "Archived v1 sandboxes imported into the `default` project.", "format": "int64", "type": "integer" } }, "required": [ "from_v1", "api_keys", "registries", "images_to_convert", "images_converted", "sandboxes_imported", "personal" ], "type": "object" }, "V1SandboxItem": { "description": "One v1 sandbox in `GET /migration/v1/sandboxes`.", "properties": { "class": { "description": "v1 sandbox class (`container`, `linux-vm`, `windows`).", "example": "container", "type": "string" }, "cpu": { "description": "vCPUs on v1.", "format": "int64", "type": "integer" }, "disk_gib": { "format": "int64", "type": "integer" }, "importable": { "description": "Whether `POST /migration/v1/sandboxes/{v1_id}/import` can import it\nnow.", "type": "boolean" }, "imported_sandbox_id": { "description": "The rlp sandbox it was imported into, when a live import exists in the\n`default` project.", "type": [ "string", "null" ] }, "labels": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "last_backup_at": { "description": "When v1 last completed a backup of the sandbox.", "format": "date-time", "type": [ "string", "null" ] }, "memory_gib": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "reason": { "description": "Why it cannot be imported, when `importable` is false:\n`not_container`, `not_archived`, `backup_not_completed`,\n`backup_registry_unavailable` (v1's reasons) or `gpu_not_supported`.\nAny other reason v1 sends is passed through.", "example": "not_archived", "type": [ "string", "null" ] }, "state": { "description": "v1 state (`archived`, `started`, `stopped`, \u2026).", "example": "archived", "type": "string" }, "v1_id": { "description": "The sandbox's id on v1.", "type": "string" } }, "required": [ "v1_id", "name", "state", "class", "importable", "labels", "cpu", "memory_gib", "disk_gib" ], "type": "object" }, "V1SandboxList": { "description": "`GET /migration/v1/sandboxes` response: one page.", "properties": { "items": { "items": { "$ref": "#/components/schemas/V1SandboxItem" }, "type": "array" }, "next_cursor": { "description": "Opaque token for the next page \u2014 pass it as `?cursor=`; `null` on the\nlast page. A page can be shorter than `limit` without being the last:\nonly a `null` ends the walk.", "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "VmActionResp": { "description": "Response for the fire-and-forget lifecycle actions (delete/stop/pause): the\nacted-on sandbox and the transitional status it was moved to. Field order is\nalphabetical to keep the wire bytes identical to the former\n`serde_json::json!` construction.", "properties": { "status": { "description": "The transitional status: `deleting` | `stopping` | `pausing`.", "example": "deleting", "type": "string" }, "vm_id": { "description": "External sandbox id.", "type": "string" } }, "required": [ "status", "vm_id" ], "type": "object" }, "VmArtifactRef": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "VmDetail": { "allOf": [ { "$ref": "#/components/schemas/VmRow" }, { "properties": { "forked_from": { "description": "External id of the fork source (PLAN-FORK.md), or null.", "type": [ "string", "null" ] }, "gpu_host_count": { "description": "Abstract gpu_host GPU count (PLAN-GPU-BACKENDS.md \u00a74a); >0 => GPU sandbox.", "format": "int32", "type": "integer" }, "image_build_id": { "description": "The content-keyed image build this sandbox booted from\n(PLAN-BUILD-DEDUPE.md), or null for any other image source. Two\nsandboxes created from the SAME Dockerfile report the SAME id \u2014 that\nis what says the second adopted the first's build instead of\nrebuilding it. The regional proxy serves that build's log via\n`GET /sandboxes/{id}/build-logs-url` discovery.", "format": "uuid", "type": [ "string", "null" ] }, "imported_from": { "$ref": "#/components/schemas/ImportedFrom", "description": "Where the sandbox was imported from (`POST\n/migration/v1/sandboxes/{v1_id}/import`, #3035): `{platform: \"v1\",\nid: }`; absent for a sandbox created on this platform." }, "labels": { "description": "Sandbox labels (migration 0053): control-plane-only `{ \"k\": \"v\" }`\nmetadata; `{}` when the sandbox has none." }, "lifecycle": { "$ref": "#/components/schemas/LifecycleDto", "description": "Lifecycle policy + derived clock (PLAN-LIFECYCLE-TIMEOUTS.md): the\nstored timeout/idle pairs plus `timeout_at`, `last_activity_at` and\n`last_activity_source`. Declared here so the generated clients and the\npublished spec match what the handler actually returns." }, "mac_boot_mode": { "description": "macOS only: how the running guest came back from its last resume,\n`restored` (from the saved memory) or `cold_after_restore_failure` (the\nsaved memory could not be restored and the Mac booted the disk). Null\nwhen this incarnation was never resumed.", "type": [ "string", "null" ] }, "mac_checkpoint_state": { "description": "macOS only (PLAN-MACOS-LIFECYCLE.md): the sandbox's checkpoint state,\n`none` | `pending` | `committed` | `failed`; null for every other class.\n`pending` from the stop request until the checkpoint commits or fails:\nstart answers `409 checkpoint_pending` meanwhile.", "type": [ "string", "null" ] }, "os_family": { "description": "Guest OS family (PLAN-CH-BACKEND.md phase 4): \"windows\" or null/\"linux\".", "type": [ "string", "null" ] }, "persistent": { "description": "Persistent write layer flag (PLAN-PERSISTENT-SANDBOXES.md) \u2014 gates the\nwarm lifecycle actions (stop/start/pause/resume/fork).", "type": "boolean" }, "spot": { "description": "Spot tier flag (PLAN-SPOT-INSTANCES.md).", "type": "boolean" }, "spot_evicted_at": { "description": "When the platform reclaimed this spot sandbox; null if never.", "format": "date-time", "type": [ "string", "null" ] }, "ssh_gateway_host": { "description": "SSH gateway host for this sandbox's region (absent if unresolvable).", "type": [ "string", "null" ] }, "ssh_gateway_port": { "description": "SSH gateway port (default 2222; absent if the host is unresolvable).", "format": "int32", "minimum": 0, "type": [ "integer", "null" ] }, "toolbox_proxy_url": { "description": "The sandbox's own region's toolbox proxy base URL \u2014 exec/fs/preview\ntraffic must target this, not a global proxy.", "type": "string" }, "windows_image": { "description": "Golden Windows base-image name; null for Linux sandboxes.", "type": [ "string", "null" ] } }, "required": [ "spot", "persistent", "gpu_host_count", "labels", "toolbox_proxy_url", "lifecycle" ], "type": "object" } ], "description": "Response shape for `GET /sandboxes/{id}`: the sandbox row plus the non-lifecycle\nextras and per-region endpoints the handler merges in. Schema-only (the\nhandler assembles the JSON itself)." }, "VmJobResp": { "description": "Response for the job-backed lifecycle actions (start/resume). Field order is\nalphabetical to keep the wire bytes identical to the former\n`serde_json::json!` construction.", "properties": { "job_id": { "description": "The enqueued start/resume job id.", "format": "uuid", "type": "string" }, "status": { "example": "assigned", "type": "string" }, "vm_id": { "description": "External sandbox id.", "type": "string" } }, "required": [ "job_id", "status", "vm_id" ], "type": "object" }, "VmLabelsResp": { "description": "Response for `PUT /sandboxes/{id}/labels`.", "properties": { "labels": { "description": "The stored label set." }, "vm_id": { "description": "External sandbox id.", "type": "string" } }, "required": [ "labels", "vm_id" ], "type": "object" }, "VmLifecycleResp": { "description": "Response for `PATCH /sandboxes/{id}/lifecycle` and\n`POST /sandboxes/{id}/reset-idle-timer` (class-blind: one route for every\nclass) \u2014 one echo shape for every lifecycle mutation.", "properties": { "lifecycle": { "$ref": "#/components/schemas/LifecycleDto", "description": "The stored policy after the update, plus the derived read-only facts." }, "vm_id": { "description": "External sandbox id.", "type": "string" } }, "required": [ "lifecycle", "vm_id" ], "type": "object" }, "VmPageRow": { "allOf": [ { "$ref": "#/components/schemas/VmRow" }, { "properties": { "created_at": { "description": "List mode only; absent from batch-wait (`?ids=`) snapshots.", "format": "date-time", "type": "string" }, "cursor": { "description": "This row's opaque keyset token \u2014 pass it as `?cursor=` to resume the list\nimmediately after this row. Not a column: the handler fills it from\n`(created_at, id)` via the same encoder that builds `next_cursor`, so the\ntoken stays opaque and server-owned. `#[sqlx(default)]` keeps `FromRow`\nhappy for the SELECT that has no such column. List mode only; absent\nfrom batch-wait (`?ids=`) snapshots.", "type": "string" }, "gpu_host_count": { "description": "gpu_host abstract GPU count (PLAN-GPU-BACKENDS.md \u00a74a). >0 => this sandbox\nruns on the gpu_host (gVisor) backend, i.e. it is a \"GPU sandbox\". Carried\nhere (not on VmRow) so the list surface can distinguish GPU sandboxes from\nordinary Linux ones (the dashboard filters on it) without touching the\nlifecycle queries. 0 for every non-GPU sandbox. List mode only; absent\nfrom batch-wait (`?ids=`) snapshots.", "format": "int32", "type": "integer" }, "labels": { "description": "Sandbox labels (migration 0053): control-plane-only `{ \"k\": \"v\" }`\nmetadata. `{}` when the sandbox has none. Carried here (not on VmRow) so\nthe list surface exposes labels without touching the lifecycle queries.\nList mode only; absent from batch-wait (`?ids=`) snapshots." }, "lifecycle": { "$ref": "#/components/schemas/LifecycleDto", "description": "Lifecycle policy + derived clock (PLAN-LIFECYCLE-TIMEOUTS.md), assembled\nby `policy::LIFECYCLE_JSON_SQL`. On the LIST as well as the detail\nsurface deliberately: the reaper's inputs must be inspectable, or a user\ncannot answer \"why did that sandbox stop?\" without a support ticket.\nList mode only; absent from batch-wait (`?ids=`) snapshots." }, "mac_boot_mode": { "description": "macOS only: how the running guest came back from its last resume,\n`restored` (from the saved memory) or `cold_after_restore_failure` (the\nsaved memory could not be restored and the Mac booted the disk). Null\nwhen this incarnation was never resumed. List mode only; absent from\nbatch-wait (`?ids=`) snapshots.", "type": [ "string", "null" ] }, "mac_checkpoint_state": { "description": "macOS only (PLAN-MACOS-LIFECYCLE.md): the sandbox's checkpoint state,\n`none` | `pending` | `committed` | `failed`; null for every other class.\n`pending` from the stop request until the checkpoint commits or fails:\nstart answers `409 checkpoint_pending` meanwhile. List mode only;\nabsent from batch-wait (`?ids=`) snapshots.", "type": [ "string", "null" ] }, "os_family": { "description": "Guest OS family (PLAN-CH-BACKEND.md phase 4). `\"windows\"` => this sandbox is\na Windows guest booted under Cloud Hypervisor (firmware + raw NTFS golden\nbase); anything else (NULL/\"linux\") is an ordinary Linux sandbox. Carried\nhere (not on VmRow) so the list surface can distinguish Windows sandboxes\n(the dashboard filters on it) without touching the lifecycle queries.", "type": [ "string", "null" ] }, "persistent": { "description": "Persistent write layer (PLAN-PERSISTENT-SANDBOXES.md). Carried here (not on\nVmRow) for the same reason as `spot`: it lets the list/detail surface gate\nwarm-lifecycle actions (pause/stop/start/resume/fork) \u2014 which are\npersistent-only \u2014 without threading the flag through the lifecycle queries.\nList mode only; absent from batch-wait (`?ids=`) snapshots.", "type": "boolean" }, "spot": { "description": "Spot tier + eviction marker (PLAN-SPOT-INSTANCES.md). Carried here (not on\nVmRow) so the list surface exposes them without touching the many\nlifecycle queries that build VmRow. List mode only; absent from\nbatch-wait (`?ids=`) snapshots.", "type": "boolean" }, "spot_evicted_at": { "format": "date-time", "type": [ "string", "null" ] }, "toolbox_proxy_url": { "description": "The sandbox's own region's toolbox proxy base URL, the same value\n`GET /sandboxes/{id}` carries \u2014 exec/fs/preview traffic must target\nthis, not a global proxy. List mode only; absent from batch-wait\n(`?ids=`) snapshots.", "type": "string" }, "windows_image": { "description": "Windows golden base image name (PLAN-CH-BACKEND.md phase 4). Set only for\n`os_family = \"windows\"` sandboxes; NULL otherwise.", "type": [ "string", "null" ] } }, "type": "object" } ], "description": "A `VmRow` plus the keyset fields. The flattened `VmRow` keeps its ext-id\nserialization.\n\n`created_at` and `cursor` are BOTH on the wire (PLAN-DASHBOARD-REGIONS.md\n\u00a75.1): a client merging the list streams of several regional cells needs the\nsort key to order them, and a per-row cursor to resume one region *mid-page*\n\u2014 whole-page `next_cursor` alone cannot express \"I displayed up to here in\nregion A but only to there in region B\". Both are additive; `limit` /\n`cursor` / `next_cursor` semantics are unchanged.\n\nSchema note: every field beyond the flattened `VmRow` is marked\n`required = false` \u2014 batch-wait mode (`GET /sandboxes?ids=`) returns plain\n`VmRow` snapshots WITHOUT the list-only fields, and generated clients must\nbe able to deserialize both shapes from this one schema." }, "VmRow": { "properties": { "class": { "description": "VM class (migration pre-deploy/20260820101429_vms_class, PLAN-VM-CLASS-SPLIT.md DP-2):\n`linux` | `windows` | `gpu` | `macos`. Immutable per VM, derived at create\n(`vm_class`), carried on the hot overlay, and serialized on the native\nDTOs (list/detail/batch-wait). Unlike `labels` it has\nNO `#[sqlx(default)]` \u2014 every VmRow SELECT must name it, so a missed\nlist fails loudly instead of silently reporting the wrong class.", "example": "linux", "type": "string" }, "cpu": { "format": "double", "type": "number" }, "create_ttl_expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "host_ip": { "type": [ "string", "null" ] }, "id": { "description": "Internal `Uuid`. Serialized as the region-tagged EXTERNAL id so all\nAPI/DTO responses carry the routable id, while the field type stays\n`Uuid` for the rest of the code (and back-compat: deployments without\nregion tagging still serialize the bare UUID string, byte-identical to\nbefore).", "example": "7fJk2mQpXv9dLc3RtY-use1", "type": "string" }, "image": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VmArtifactRef" } ] }, "manifest_name": { "type": [ "string", "null" ] }, "mem_max_mib": { "format": "int32", "type": [ "integer", "null" ] }, "mem_mib": { "format": "int32", "type": "integer" }, "name": { "type": "string" }, "port_map": {}, "region": { "description": "Home region slug (PLAN-REGIONS.md). Serialized as `region`.", "type": "string" }, "runner_id": { "type": [ "string", "null" ] }, "scratch_max_mib": { "format": "int32", "type": [ "integer", "null" ] }, "scratch_mib": { "format": "int32", "type": "integer" }, "snapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VmArtifactRef" } ] }, "status": { "type": "string" }, "user": { "description": "The sandbox's default OS user \u2014 the one its processes, entrypoint, SSH\nsessions and git operations run as unless a request names another:\nthe create's `user`, or \u2014 when the create named\nnone \u2014 the `USER` of the image's config, recorded once the sandbox is\nrunning. Omitted when the create named no user and none was recorded:\nthe sandbox then runs as root.", "example": "dev", "type": [ "string", "null" ] }, "vcpus": { "format": "int32", "type": "integer" }, "vcpus_max": { "description": "Effective per-axis limits (PLAN-BURSTABLE.md), resolved at create: the\nceilings the sandbox boots at, at or above what it reserves in `cpu` /\n`mem_mib` / `scratch_mib`. `Option` + `#[sqlx(default)]` so SELECTs that\nomit the columns (e.g. the VmLite list overlay) still map \u2014 `None` then\nsimply omits them from the DTO.", "format": "int32", "type": [ "integer", "null" ] } }, "required": [ "id", "name", "status", "cpu", "vcpus", "mem_mib", "scratch_mib", "port_map", "region", "class" ], "type": "object" }, "VmUsageResp": { "description": "Response for `GET /sandboxes/{id}/usage`. Field order is alphabetical to keep the\nwire bytes identical to the former `serde_json::json!` construction.", "properties": { "id": { "description": "The requested external sandbox id, echoed back.", "type": "string" }, "runner_id": { "description": "Runner currently hosting the sandbox.", "type": "string" }, "source": { "description": "Always `live` (the runner's current snapshot, not the collector).", "example": "live", "type": "string" }, "usage": { "description": "The runner's per-sandbox usage document (free-form; runner-defined)." } }, "required": [ "id", "runner_id", "source", "usage" ], "type": "object" }, "VolumeDto": { "description": "A volume as returned by the API. `last_manifest_id`/`conflicts` are read\nbest-effort from the CAS store on detail routes only (never on list).", "properties": { "conflicts": { "description": "Concurrent-write conflicts recorded on the latest manifest (audit trail)." }, "created_at": { "format": "date-time", "type": "string" }, "error_reason": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "last_manifest_id": { "description": "Blockmount CAS pointer, read-through on detail routes (best-effort).", "type": [ "string", "null" ] }, "last_used_at": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "options": { "description": "Per-type options, namespaced by type (PLAN-VOLUME-TYPES.md \u00a71): `{}` for\na disk volume, `{\"bucket\": {...}}` for a bucket one. Credentials appear\nas the project-secret NAMES that were supplied, never as values \u2014\nvalues are write-only across the whole API.", "type": "object" }, "size_gb": { "description": "Scratch capacity in GiB. Disk volumes only \u2014 a bucket volume has no\ncapacity of its own and reports `null`.", "format": "int32", "type": [ "integer", "null" ] }, "state": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "used_bytes": { "description": "Real (logical) usage in bytes: sum of committed file sizes, hardlink\ngroups counted once. Cached from runner `events.volume.*` reports; absent\nuntil the first report lands (never written / pre-feature volume).", "format": "int64", "type": [ "integer", "null" ] }, "used_bytes_at": { "description": "When the cached `used_bytes` was observed by the runner.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "name", "type", "state", "created_at", "updated_at" ], "type": "object" }, "VolumeMountReq": { "description": "A volume attachment as requested on `POST /sandboxes`.", "properties": { "mount_path": { "example": "/mnt/data", "type": "string" }, "read_only": { "description": "Mount without write access. Bucket volumes only \u2014 a disk volume has no\nread-only drive to give (D6), so `true` here is a 400.", "type": [ "boolean", "null" ] }, "subpath": { "description": "Mount only this subtree: a subdirectory for a disk volume, a key prefix\nunder the volume's own prefix for a bucket volume.", "type": [ "string", "null" ] }, "volume": { "description": "Volume id or name.", "type": "string" } }, "required": [ "volume", "mount_path" ], "type": "object" }, "WalletResponse": { "properties": { "automatic_top_up": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AutomaticTopUpResponse" } ] }, "balance_cents": { "format": "int64", "type": "integer" }, "billing_type": { "type": "string" }, "credit_card_connected_credits_granted": { "type": "boolean" }, "free_credits_balance_cents": { "format": "int64", "type": "integer" }, "has_failed_or_pending_invoice": { "type": "boolean" }, "name": { "type": "string" }, "paid_credits_balance_cents": { "format": "int64", "type": "integer" }, "total_amount_due_this_month_cents": { "format": "int64", "type": "integer" }, "total_spent_this_month_cents": { "format": "int64", "type": "integer" }, "verified_credits_granted": { "type": "boolean" } }, "required": [ "balance_cents", "free_credits_balance_cents", "paid_credits_balance_cents", "name", "billing_type", "credit_card_connected_credits_granted", "verified_credits_granted", "has_failed_or_pending_invoice", "total_spent_this_month_cents", "total_amount_due_this_month_cents" ], "type": "object" } }, "securitySchemes": { "api_key": { "description": "Project API key (`dtn_\u2026`) as a Bearer token. Mint via the management API (`POST /projects/:id/api-keys`) or this deployment's key-mint CLI. Every key carries an explicit set of `verb:resource` project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered `403 missing required project permission: `. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (`write:`/`delete:`/`invoke:`) implies the resource's `read:` permission. Operations whose `api_key` project-permission list is empty need no specific project permission \u2014 any live project key works (the global catalogs and the artifact-cache read).", "scheme": "bearer", "type": "http" }, "oidc_jwt": { "bearerFormat": "JWT", "description": "The signed-in user's OIDC access token \u2014 the management-plane credential. On this surface it is accepted only by `POST /auth/token`.", "scheme": "bearer", "type": "http" }, "operator": { "description": "Platform-operator credential for `/manage/*`: on the home/central cell this can be either an OIDC JWT of a configured platform admin or the shared internal token; workload cells admit the shared internal token only. This is distinct from organization roles, project API keys, and org API keys.", "scheme": "bearer", "type": "http" }, "org_key": { "description": "Organization API key (`dtno_\u2026`) as a Bearer token. Accepted ONLY on `GET /orgs/{id}/audit-logs` (the org audit-log query, `read:audit`) and `GET /orgs/{id}/principal` (the caller's own resolved permissions, no permission required); every other management route answers 401 to it. Each operation names the exact org permission the key must hold in its security requirement.", "scheme": "bearer", "type": "http" }, "platform_token": { "bearerFormat": "JWT", "description": "Short-lived platform access token (RFC 9068 `at+jwt`, ES256), minted by `POST /auth/token` from a signed-in user's OIDC session and scoped to one project. Accepted beside the project API key on every workload operation; its `scope` claim carries the same `verb:resource` project permissions a key holds, enforced identically (403 when absent). Expires after ~5 minutes \u2014 clients re-exchange rather than refresh.", "scheme": "bearer", "type": "http" }, "sandbox_token": { "bearerFormat": "JWT", "description": "Short-lived per-sandbox access token (RFC 9068 `at+jwt`, ES256, `aud: daytona:toolbox` \u2014 PLAN-SANDBOX-TOKEN-JWT.md), minted by `POST /sandboxes/{id}/access-token` (class-blind) or returned by the create response after the data-plane compat flip. Scoped to exactly one sandbox (`sub`), a set of sandbox operations (`scope`: `toolbox`, `toolbox:exec`, `toolbox:fs`, `toolbox:git`, `toolbox:lsp`, `desktop`, `ssh`, `sandbox:stop`, `sandbox:pause`, `sandbox:delete`), and optionally a set of preview ports (`ports`; absent = all). On this API it is accepted ONLY on the sandbox self-service routes (delete/stop/pause), gated by the matching `sandbox:*` operation in its scope; the data plane (toolbox proxy, SSH gateway, desktop, private previews) verifies it statelessly against the published JWKS. It can never mint new credentials.", "scheme": "bearer", "type": "http" }, "user_jwt": { "description": "OIDC access token of a signed-in user (the dashboard/CLI login) used on the management plane: `/me`, `/orgs*`, `/projects*`, `/invitations*`, `/roles`, billing, audit, API-key, and service-account routes. Every management operation documents the org/project permission the authenticated member must hold.", "scheme": "bearer", "type": "http" }, "vm_token": { "description": "Per-VM access token (`dtnv_\u2026`), scoped to exactly one sandbox. Accepted ONLY on the sandbox self-service routes (delete/stop/pause) \u2014 the credential the in-VM daemon holds. Carries the implicit `{write:sandboxes, delete:sandboxes}` project-permission set for its own box, so it never fails a permission check on those routes.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Sandbox control plane. Authenticate with a project API key (`dtn_\u2026`) as a Bearer token; the sandbox self-service routes (delete/stop/pause) additionally accept a per-VM token (`dtnv_\u2026`). Every operation that accepts a project API key equally accepts a short-lived project-scoped platform access token (ES256 JWT minted by `POST /auth/token` from a signed-in user's OIDC session), enforcing the same `verb:resource` permissions from its `scope` claim. API keys carry per-key `verb:resource` project permissions \u2014 each operation names its required project permission in its `api_key` security requirement and answers 403 when the key lacks it (some operations require an additional permission depending on the request body, stated in the operation's description). Errors use the `ErrorBody` `{code, message, source, trace_id?}` envelope (`trace_id` present when a trace is recording); overload sheds answer 429 with a `Retry-After` header. List endpoints use opaque-cursor keyset pagination (`limit` + `cursor`, echo `next_cursor`).", "license": { "name": "LicenseRef-Proprietary", "url": "https://github.com/daytona/rlp/blob/main/LICENSE" }, "title": "Daytona API", "version": "0.0.0-dev" }, "openapi": "3.1.0", "paths": { "/api-keys/current": { "get": { "operationId": "get_current_api_key", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentApiKey" } } }, "description": "The presented key's metadata (never the token)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated with a platform token, which has no key row to introspect" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] } ], "summary": "Introspect the API key used for this request: its name, display prefix and\nsuffix, project and organization, permissions, expiry and last use. Lets an\nSDK or CLI discover which tenant it is acting in. The token itself is never\nreturned.", "tags": [ "api-keys" ] } }, "/api-keys/{id}": { "delete": { "description": "Revoke one project API key. The caller must be able to enter the key's project and hold `delete:project_api_keys`, except that revoking a personal key the caller minted (`created_by` = caller) is also allowed with `write:project_api_keys`, and revoking a key owned by a service account requires `delete:service_accounts` instead. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_revoke_project_api_key", "parameters": [ { "description": "Project API key id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedProjectApiKeyResponse" } } }, "description": "Revoked project API key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks the permission required to revoke this key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Key not found, project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "api-keys" ] }, "get": { "description": "Read one project API key's metadata (the same shape as a list item, never the token). The caller must be able to enter the key's project and hold `read:project_api_keys`; an unknown id, or a key in a project the caller cannot enter, is a 404 so nothing is learned about other tenants' keys. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_project_api_key", "parameters": [ { "description": "Project API key id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKeyResponse" } } }, "description": "Project API key metadata" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:project_api_keys`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Key not found, project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /api-keys/:id (management plane): one key's metadata. Authorized like\nthe list \u2014 `read:project_api_keys` on the key's org \u2014 and 404 for an\nunknown id, so a caller outside the org learns nothing.", "tags": [ "api-keys" ] }, "patch": { "description": "Change whether the v1 \u2194 v2 key sync keeps a copy of one project API key on Daytona v1 (`sync_to_v1`). Turning it off deletes the v1 copy; the key keeps working on this platform. Only a live, unexpired key a person minted in the organization's `default` project, other than the dashboard's own key named `default`, is ever copied: turning it on for any other key is a 409 `KEY_SYNC_NOT_APPLICABLE`, and turning it off for one is a no-op. A live key imported from Daytona v1 is always synced: turning it off is a 409 `IMPORTED_KEY_ALWAYS_SYNCED` (delete the key to remove it from both platforms); a revoked or expired imported key is answered like any other key that is never copied. Authorized like revoking the key: the caller must be able to enter the key's project and hold `write:project_api_keys` for a personal key they minted, `delete:project_api_keys` for anyone else's, or `delete:service_accounts` for a service account's key. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_update_project_api_key", "parameters": [ { "description": "Project API key id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectApiKeyReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKeyResponse" } } }, "description": "The key's metadata after the change" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The body names no field to change" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks the permission required to manage this key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Key not found, project not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The key is live, was imported from Daytona v1, and is always synced (`IMPORTED_KEY_ALWAYS_SYNCED`), or it is never copied to v1 (`KEY_SYNC_NOT_APPLICABLE`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /api-keys/:id (management plane): change a key's `sync_to_v1`.\nAuthorized like revoking the key ([`key_manage_permission`]). The flag\nlives in `project_api_key_v1_sync_optout` (a row = off), never on the\nreplicated key row; writing the row fires `api_key.updated` (migration\n20261013093507), and the bridge then deletes or writes the v1 copy.", "tags": [ "api-keys" ] } }, "/audit/scenarios": { "get": { "operationId": "get_audit_scenarios", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditScenarios" } } }, "description": "Supported audit log scenarios grouped by target type. Derived from the audited-route table, so it always reflects what can actually appear in the audit log; targets sorted by type, actions alphabetically." } }, "summary": "GET /audit/scenarios \u2014 public and static.", "tags": [ "audit" ] } }, "/auth/token": { "post": { "description": "Management plane, central-only (needs the identity tables). The guard is\n`require_user_or_org_key`; this route is deliberately NOT in\n`orgs::ORG_KEY_ROUTES`, so an org-key caller never reaches it (no\n`UserCtx` \u21d2 401) \u2014 a machine credential has no user identity to mint.", "operationId": "exchange_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } } }, "description": "RFC 8693 token-exchange request, as JSON or the RFC's native form encoding. `audience` selects the token kind: omitted or `daytona:api` mints a project-scoped workload token (`project_id` required, `org_id` omitted); `daytona:analytics` mints an org-scoped rlp-analytics token (`org_id` required, `project_id` omitted). Any other audience is refused, and `audience`, `org_id`, and `project_id` may not be repeated. `scope` and `resource` must be omitted because down-scoping is not supported.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeResponse" } } }, "description": "Token minted for the caller's effective permissions in the project (workload audience) or the organization (analytics audience)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Unsupported grant/token type or audience, explicit down-scoping parameter, project_id/org_id that does not match the audience, a repeated parameter, or subject_token differs from the presented bearer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC session (org API keys are not accepted here)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Unknown project or organization, or the caller is not a member (existence is not revealed)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "oidc_jwt": [] } ], "summary": "Exchange a verified OIDC session for a short-lived platform token\n(RFC 8693): project-scoped for the workload plane\n(PLAN-WORKLOAD-PLANE-JWT-AUTH.md D9), or org-scoped for rlp-analytics when\n`audience` is `daytona:analytics` (PLAN-ANALYTICS-PLATFORM-TOKENS.md D1).", "tags": [ "auth" ] } }, "/cache/images": { "get": { "description": " - \"is precached?\" ?ref=ubuntu:22.04 \u2192 the image + per-layer hit/miss\n - \"what's cached?\" (no ref) \u2192 a paginated list of cached ref-manifests\n\nThe API has no NFS mount (control-plane / runner split), so the scan runs on\na runner over NATS request/reply (`runner..cache.images`). The cache is\nshared across all runners' NFS, so ANY live runner yields the same answer; we\ntry live runners in turn until one replies. This is deliberately NOT scoped\nto the caller's project: the CAS is global infrastructure keyed by layer\ndiff-id. Per-project image ownership lives in `GET /images`, a separate plane.", "operationId": "cache_images", "parameters": [ { "description": "When set, a single-ref precache lookup with per-layer detail\n(e.g. ?ref=ubuntu:22.04). Otherwise a paginated list.", "in": "query", "name": "ref", "required": false, "schema": { "type": "string" } }, { "description": "Page size for the list (clamped runner-side to [1, 500]); ignored for ref.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Opaque continuation token from a previous page's `next_cursor`.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Runner cache scan result (proxied runner reply, shape is runner-defined): with `ref`, the image + per-layer hit/miss; without, a paginated `{ images, next_cursor }` list" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Cache scan failed runner-side (e.g. malformed ref)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No runner available/answering to scan the cache" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /cache/images \u2014 read-only view of the shared, org-agnostic NFS artifact\ncache (erofs layer CAS + registry ref-manifests). Answers two questions:", "tags": [ "images" ] } }, "/config": { "get": { "description": "Unauthenticated bootstrap for every client that must discover the\ndeployment before it can log in: the dashboard (OIDC parameters, PostHog,\nforced feature flags) and the `daytona` CLI (`oidc.cli_client_id`, the\nSSH gateway, `api_url`). Documented so those clients decode it through the\ngenerated contract types (PLAN-CLI.md D19); the body is assembled once\nfrom the environment at process start and never changes.", "operationId": "get_config", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" } } }, "description": "Runtime configuration of this deployment" } }, "summary": "`GET /config` \u2014 this deployment's public runtime configuration.", "tags": [ "system" ] } }, "/cpu-catalog": { "get": { "operationId": "cpu_catalog", "parameters": [ { "description": "Comma-separated region slugs this cell hosts runners for\n(`?region=a,b`; tokens are trimmed, case-folded, and deduplicated).\nThe answer covers exactly the named regions. Absent, or present with\nno non-blank token (`?region=`, `?region=%20,,%20`): every region this\ncell hosts. A slug not in the catalog (or disabled) is a 400, as are\nmore than 64 distinct slugs; a catalog region another cell hosts is a\n409 carrying that cell's `api_base_url`.", "in": "query", "name": "region", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CpuCatalogResp" } } }, "description": "Registry slugs and architectures with their per-region availability; an empty fleet is a 200 with every `available` false" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`region` names a slug that is not in this cell's catalog, or a disabled one (`region is unavailable`); or `region` names more than 64 distinct slugs (`too many regions (max 64)`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`region` names a catalog region this cell does not host; the message carries the owning cell's `api_base_url`" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /cpu-catalog \u2014 the CPU type registry and both architectures, each\nmarked available or not per region from this cell's live linux-pool\nrunners (PLAN-CPU-CATALOG-FROM-RUNNERS.md). A catalog read any key may\nperform, like `GET /cpu-types`; the dashboard asks the selected region's\ncell and offers only what is servable there.", "tags": [ "catalog" ] } }, "/cpu-types": { "get": { "operationId": "list_cpu_types", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CpuTypeInfo" }, "type": "array" } } }, "description": "The CPU type registry" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /cpu-types \u2014 the CPU type registry. Clients (dashboard create form, SDK\nusers) use it to discover valid `cpu_type` values, their arch, and tier.", "tags": [ "catalog" ] } }, "/disk-classes": { "get": { "operationId": "list_disk_classes", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ClassInfo" }, "type": "array" } } }, "description": "The disk class registry" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /disk-classes \u2014 the disk (NVMe) class registry: the classes runners\nadvertise and regions default to, with their tier. Informational \u2014 a create\ncannot select a disk class.", "tags": [ "catalog" ] } }, "/events/{edge}": { "get": { "operationId": "upgrade", "parameters": [ { "description": "Region tag of the sandboxes the socket will carry, or `_`. Routing only.", "in": "path", "name": "edge", "required": true, "schema": { "type": "string" } } ], "responses": { "101": { "description": "Switching Protocols: the sandbox-events WebSocket (subprotocol `rlp.events.v1`). Authenticated by a single-use ticket from `POST /events/{edge}/ticket`, carried as `Sec-WebSocket-Protocol: rlp.events.v1, rlp.ticket.`; frames are JSON per clients/contract/sandbox-events-protocol.json." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Ticket missing, expired, already used, or its credential no longer valid" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed edge" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Per-credential live socket cap reached; `Retry-After` set" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workload plane elsewhere: this deployment serves no sandboxes" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox events are off, the instance is at its socket ceiling, or the ticket store is unreachable" } }, "tags": [ "sandboxes" ] } }, "/events/{edge}/ticket": { "post": { "operationId": "mint_ticket", "parameters": [ { "description": "Region tag of the sandboxes the socket will carry (the part after the dash in a sandbox id), or `_` when the ids carry no tag. Routing only: the cell accepts any sandbox it owns.", "in": "path", "name": "edge", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsTicket" } } }, "description": "A single-use ticket for one `GET /events/{edge}` upgrade" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid project API key or platform token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed edge" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Ticket mint rate (10/min per credential) or live-socket cap (16 per credential) reached; `Retry-After` set" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox events are off or the ticket store is unreachable" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/global-regions": { "get": { "operationId": "list_global_regions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/GlobalRegionInfo" }, "type": "array" } } }, "description": "Geo groups and the Global root with active member counts" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /global-regions \u2014 Geo groups and the Global root (Earth, ID `earth`)\nwith active member counts. Geo groups are arbitrary abstract groupings of\nMacros; names such as US or EU impose no geographic constraint. The route\nand `GlobalRegionInfo` retain their historical technical names.", "tags": [ "regions" ] } }, "/health": { "get": { "operationId": "health", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }, "description": "API, database, and schema are up" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Unhealthy: draining after a publish-watchdog trip, or the migration ledger is missing/empty" } }, "summary": "Liveness probe: the process is up, the DB answers, and the schema is\npresent.", "tags": [ "system" ] } }, "/health/deep": { "get": { "operationId": "health_deep", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepHealth" } } }, "description": "JetStream answered the probe (status may still be `warn` on retention-drift alarms)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepHealth" } } }, "description": "JetStream probe timed out (publishes degraded/wedged) or the Postgres liveness probe failed \u2014 check the `nats`/`db` fields to tell which" } }, "summary": "GET /health/deep \u2014 readiness probe that actually touches JetStream\n(PLAN-NATS-HYGIENE Item B step 3). Plain `/health` touches neither NATS nor\nthe DB's hot path, so during the incident it stayed green while every\n`POST /sandboxes` hung on a wedged publish client \u2014 monitoring had no signal. This\nendpoint does a timeout-bounded, read-only `$JS.API.INFO` round trip (never a\nstream write, so it cannot itself wedge on the in-flight-ack path being\ndiagnosed) and reports the recent publish-timeout count. Returns HTTP 200\nwith `{\"nats\":\"ok\"}` when JetStream answers promptly, HTTP 503 with\n`{\"nats\":\"degraded\"}` when it times out \u2014 a liveness (`/health`) vs\nreadiness (`/health/deep`) separation. The exit-on-wedge watchdog owns\nautonomous recovery; this gives operators the missing observability.", "tags": [ "system" ] } }, "/images": { "get": { "operationId": "list_images", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sandbox_id", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "anonymous", "required": false, "schema": { "type": "string" } }, { "description": "Which images to list: `false` (default) the project's own, `true`\nthe platform images (deprecated ones excluded), `any` both.", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesPage" } } }, "description": "Images in the project and, with `platform=true|any`, the platform images (keyset-paginated, newest first). The anonymous backup image a v1 sandbox import registers (`imported_from`, no name) is never listed \u2014 it only serves the sandbox it was imported for and stays reachable by id" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed cursor, or an invalid `anonymous`/`platform` filter" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:images`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:images" ] }, { "platform_token": [ "read:images" ] } ], "tags": [ "images" ] }, "post": { "operationId": "create_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageJson" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateImageMultipart" } } }, "description": "JSON build request (registry/named source). Alternatively send `multipart/form-data` with fields `name`, optional `dockerfile` (path within the context), `region`, `cpu_arch`, and the file field `context` (a build-context tar).", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageResp" } } }, "description": "Build enqueued" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid JSON/multipart body, an API-internal source type (`manifest`), or unknown/disabled region" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:images`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A `named` source names no image in the caller's project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The name is taken by a captured image in this project, or a `named` source names an image that is not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization concurrent-builds limit reached (`limit_exceeded`, PLAN-ORG-LIMITS; body carries `limit`/`current`/`max` and deliberately NO `Retry-After`) \u2014 or the org's admission queue is saturated (`overloaded`, with `Retry-After`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:images" ] }, { "platform_token": [ "write:images" ] } ], "summary": "POST /images\nTwo modes:\n - application/json: registry/named source (no context upload)\n - multipart/form-data: fields `name`, optional `dockerfile`, file `context`", "tags": [ "images" ] } }, "/images/{id}": { "delete": { "description": "New in PLAN-ARTIFACT-UNIFICATION.md phase 2. Before it, image deletion\nexisted ONLY inside the Daytona alias facade, running a shorter guard set\nthan the snapshot route \u2014 so which endpoint you happened to use decided\nwhether a paused sandbox kept its layers. Both routes are the same code now\n(`snapshots::delete_artifact`), and neither can reach across the\nimage/snapshot partition.", "operationId": "delete_image", "parameters": [ { "description": "image id (`img_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteImageResp" } } }, "description": "Image deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`delete:images`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found in the caller's project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Something still depends on this image: a function version, a descendant snapshot, or a live/paused sandbox or resumable artifact" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "delete:images" ] }, { "platform_token": [ "delete:images" ] } ], "summary": "DELETE /images/{id} \u2014 drop the image row and unlink the erofs manifest it\nleft on NFS, so the offline layer sweeper can reclaim whatever is now\nexclusive to it (PLAN-LAYER-GC.md \u00a73).", "tags": [ "images" ] }, "get": { "description": "Mirrors `GET /snapshots/{id}`: a build is asynchronous, so a client that\njust POSTed needs somewhere to wait. (Before\nPLAN-ARTIFACT-UNIFICATION.md DP-7 the only such surface was the Daytona\nalias facade, which polled the same row through a second table.)", "operationId": "get_image", "parameters": [ { "description": "Block until the image reaches this status (`ready`) or a terminal state\n(`ready`/`failed`). Absent => return immediately.", "in": "query", "name": "wait", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "timeout_ms", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "image id (`img_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageListItem" } } }, "description": "The image" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:images`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found in the caller's project or among the platform images" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:images" ] }, { "platform_token": [ "read:images" ] } ], "summary": "GET /images/{id} \u2014 one image, optional long-poll via `?wait=ready`.", "tags": [ "images" ] }, "patch": { "description": "Promotion only: an image that already has a name answers 409. Renaming a\nnamed image is deliberately not offered yet \u2014 sandboxes reference images by\nid, so a rename would silently relabel every sandbox created from it, and\nnothing would record the name the caller created them with.", "operationId": "promote_image", "parameters": [ { "description": "image id (`img_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteImageReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageListItem" } } }, "description": "The now-named, permanent image" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Reserved image name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:images`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found in the caller's project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image name already exists (`IMAGE_NAME_TAKEN`), or the image already has a name (renaming is not supported)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:images" ] }, { "platform_token": [ "write:images" ] } ], "summary": "Name an ANONYMOUS image, making it permanent (PLAN-CREATION-SHAPE \u00a75).", "tags": [ "images" ] } }, "/images/{id}/build-logs-url": { "get": { "operationId": "image_url", "parameters": [ { "description": "image id (`img_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildLogsUrl" } } }, "description": "Absolute regional proxy URL" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid project API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Requires read:images" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Build-log metadata unavailable, including a build claimed for garbage collection" } }, "security": [ { "api_key": [ "read:images" ] }, { "platform_token": [ "read:images" ] } ], "tags": [ "images" ] } }, "/images/{id}/convert": { "post": { "description": "The same conversion the first create runs (`images::format::convert`): an\nimage below the current format (`format_outdated`) flips to `pending` and\nits conversion job \u2014 for a format-1 image, the registry import of its v1\nref \u2014 is enqueued in the image's region. Idempotent and safe to repeat: a\nconversion already in flight is joined (nothing enqueued), a failed one is\nretried, and an image already at the current format answers\n`converted: false` with its own status, whatever that is \u2014 its build is\n`POST /images`' business.", "operationId": "convert_image", "parameters": [ { "description": "image id (`img_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageConversion" } } }, "description": "The conversion started or joined (`converted: true`), or nothing to convert (`converted: false`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:images`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found in the caller's project (`IMAGE_NOT_FOUND`)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The image records no source its format can be converted from" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization concurrent-builds limit reached (`limit_exceeded`, PLAN-ORG-LIMITS)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:images" ] }, { "platform_token": [ "write:images" ] } ], "summary": "`POST /images/{id}/convert` \u2014 convert an image to the current image format\nnow, instead of on its first Linux sandbox create (#3032).", "tags": [ "images" ] } }, "/invitations/accept": { "post": { "description": "Accept the invitation an emailed `dtni_` token refers to, seating the caller in the organization with the invitation's roles (an already-seated caller keeps their roles; the invitation is consumed either way). Possession of the token is the authorization; no organization permission is checked because the caller is not yet seated, and the caller's address is not compared with the invited one \u2014 the audit record carries both. Only an OIDC user JWT is admitted; `dtno_` organization API keys are not.", "operationId": "mgmt_accept_invitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationTokenReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedInvitationResponse" } } }, "description": "Accepted invitation" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invitation not found: the token is malformed, unknown, already accepted or declined, or expired" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization seat cap reached (`limit_exceeded`, PLAN-PRICING-PLANS.md D6/D8): the invitation was valid but the organization can no longer seat a member, e.g. after a plan downgrade; body carries `limit`/`current`/`max`" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "invitations" ] } }, "/invitations/decline": { "post": { "description": "Decline the invitation an emailed `dtni_` token refers to. Possession of the token is the authorization; no organization permission is checked because the caller is not yet seated. The row stays visible to the organization as declined until it is revoked or the address is re-invited. Only an OIDC user JWT is admitted; `dtno_` organization API keys are not.", "operationId": "mgmt_decline_invitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationTokenReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclinedInvitationResponse" } } }, "description": "Declined invitation" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invitation not found: the token is malformed, unknown, already accepted or declined, or expired" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "Records an invitee's refusal by stamping `declined_at`, authorized by the\nemailed token (PLAN-INVITATION-DECLINED-VISIBILITY.md,\nPLAN-INVITATION-EMAIL.md). The row and its roles remain visible to the org\nuntil revoke dismisses it; a re-invite reuses the row, clears the refusal\nand mints a new token. The transaction keeps `accept_invitation`'s lock\norder. No delegation check (refusing a grant offered to you exercises no\nauthority over anyone) and no last-Admin guard (an invitation seats\nnobody).", "tags": [ "invitations" ] } }, "/invitations/lookup": { "post": { "description": "Show the invitation an emailed `dtni_` token refers to: the organization, the roles it would grant, who sent it, the invited address and the expiry. Possession of the token is the authorization; no organization permission is checked because the caller is not yet seated. A missing, used, declined, expired, or malformed token answers `404`. Only an OIDC user JWT is admitted; `dtno_` organization API keys are not.", "operationId": "mgmt_lookup_invitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationTokenReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationLookupResponse" } } }, "description": "The pending invitation the token refers to" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invitation not found: the token is malformed, unknown, already accepted or declined, or expired" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "invitations" ] } }, "/jobs/{id}": { "get": { "operationId": "get_job", "parameters": [ { "description": "job id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResp" } } }, "description": "Job status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Job not found (or not visible to this project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /jobs/:id \u2014 status of one async job. Visible only if the vm/image the\njob acts on belongs to the caller's project.", "tags": [ "jobs" ] } }, "/macro-regions": { "get": { "operationId": "list_macro_regions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MacroRegionInfo" }, "type": "array" } } }, "description": "Macro regions with eligible member counts" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /macro-regions \u2014 the macro-region (cell) catalog\n(PLAN-REGION-HIERARCHY.md). A macro region is the public selector for one\nworkload cell; `eligible_local_region_count` is how many of its Edge regions\na broad create may actually land in.", "tags": [ "regions" ] } }, "/manage/global-refs": { "delete": { "description": "Remove one normalized bare registry ref from this cell's global-routing set. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The `ref` is a query parameter because image refs contain `/` and `:`.", "operationId": "admin_delete_global_ref", "parameters": [ { "in": "query", "name": "ref", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalRefDeleteResp" } } }, "description": "Global ref removed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or malformed `ref` query parameter" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Global ref not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "get": { "description": "List the normalized bare registry refs that this cell routes globally. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The set is evaluated in the cell-local routing snapshot alongside `images.global`.", "operationId": "admin_list_global_refs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGlobalRefsResp" } } }, "description": "Global registry refs for this cell" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "post": { "description": "Add or update a normalized bare registry ref in this cell's global-routing set. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The set is cell-local because the routing snapshot is cell-local.", "operationId": "admin_add_global_ref", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGlobalRefReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalRefEntry" } } }, "description": "Global ref added or updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Ref invalid or empty" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/global-regions": { "get": { "description": "List the global-region groups. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The global-region catalog is served centrally: served on home and central cells (central is the write authority for this replicated tenancy metadata); a workload cell answers 501 `MANAGEMENT_PLANE_ELSEWHERE`.", "operationId": "admin_list_global_regions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/GlobalRegionInfo" }, "type": "array" } } }, "description": "Global-region catalog" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "post": { "description": "Create a global-region group. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The global-region catalog is served centrally: served on home and central cells (central is the write authority for this replicated tenancy metadata); a workload cell answers 501 `MANAGEMENT_PLANE_ELSEWHERE`.", "operationId": "admin_create_global_region", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGlobalRegionReq" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalRegionInfo" } } }, "description": "Global-region group created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body or global-region id invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Global-region id already exists or collides with a concrete region" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/global-regions/{id}": { "patch": { "description": "Rename a global-region group. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The global-region catalog is served centrally: served on home and central cells (central is the write authority for this replicated tenancy metadata); a workload cell answers 501 `MANAGEMENT_PLANE_ELSEWHERE`.", "operationId": "admin_update_global_region", "parameters": [ { "description": "global-region id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGlobalRegionReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalRegionInfo" } } }, "description": "Global-region group renamed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Global-region group not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/groups": { "get": { "description": "List the affinity-group routing state for the current cell. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Group membership, breaker state, and vslot routing are cell-local, so callers must query the cell whose fleet they want to inspect.", "operationId": "admin_list_groups", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupsResponse" } } }, "description": "Affinity-group state for this cell" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This central deployment has no workload fleet; the body names the workload API to query instead" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/images": { "get": { "description": "List the registry and Dockerfile images known to this cell's layer index; capture and Windows images are not listed. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Image routing flags and indexed layer totals are cell-local because the manifest and layer index describe the current cell's storage.", "operationId": "admin_list_images", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListImagesResp" } } }, "description": "Images and indexed layer totals for this cell" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/images/{id}": { "patch": { "description": "Update operator-only image flags on the owning cell. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The `global` flag changes only routing within the image's own cell; it does not copy artifacts, mutate workload-plane JSON fields, or make the image visible to any other project. Only setting `global: true` is restricted to registry and dockerfile images; `global: false` is accepted on any image to clear a stale flag.", "operationId": "admin_patch_image", "parameters": [ { "description": "image id (region-tagged external id or raw UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchImageReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchImageResp" } } }, "description": "Image flags updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found on this cell" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`global: true` requested on a capture or Windows image, which global routing does not apply to (clearing is accepted)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/images/{id}/layers": { "get": { "description": "List the indexed layer stack for one image on the owning cell. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Layer sharing and reclaimability are cell-local because the manifest and layer index describe the current cell's storage.", "operationId": "admin_image_layers", "parameters": [ { "description": "image id (region-tagged external id or raw UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageLayersResp" } } }, "description": "Image layer stack" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/layers/backfill": { "post": { "description": "Backfill missing manifest-layer index rows on this cell. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The work is cell-local because manifests are read through this cell's own runners.", "operationId": "admin_backfill_layers", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackfillResp" } } }, "description": "Backfill progress summary" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed `limit` query parameter" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No runner could answer manifest-layer reads" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/layers/{diff_id}/dependents": { "get": { "description": "List every artifact on this cell that still references one diff-id. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The answer is cell-local because layer reachability is determined from this cell's manifest index and live VM rows.", "operationId": "admin_layer_dependents", "parameters": [ { "description": "layer diff-id, with or without the `sha256:` prefix", "in": "path", "name": "diff_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerDependentsResp" } } }, "description": "Layer dependents on this cell" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Layer not indexed on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/macro-regions": { "get": { "description": "List the imported Macro regions (one per workload cell). This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The Macro catalog is served by whichever deployment mounts the management plane from the replicated topology metadata: Home in a fused deployment, Central in a split deployment; a workload cell answers 501 `MANAGEMENT_PLANE_ELSEWHERE`.", "operationId": "admin_list_macro_regions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MacroRegionInfo" }, "type": "array" } } }, "description": "Macro-region catalog" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/macro-regions/{id}": { "patch": { "description": "Rename one Macro region or move it under a different Geo region. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Macro regions are imported from deployment inventory, so only the display name and Geo parent are editable here; the Macro id and its bound cell remain immutable.", "operationId": "admin_update_macro_region", "parameters": [ { "description": "Macro-region id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMacroRegionReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroRegionInfo" } } }, "description": "Macro region updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body invalid or Geo parent invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Macro region not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Macro region cannot be changed that way" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/manifests/{name}/layers": { "get": { "description": "List the indexed layer stack for one manifest name on this cell. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The answer is cell-local because manifest indexing happens against this cell's storage.", "operationId": "admin_manifest_layers", "parameters": [ { "description": "manifest name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestLayersResp" } } }, "description": "Manifest layer stack" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Manifest not indexed on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/platform-images": { "get": { "description": "List this cell's platform images: operator-published Linux images every organization and project can create sandboxes from, with the cell's platform default per class. Requires the platform-operator credential: an OIDC JWT for a configured platform admin, or the internal token. Served on home and workload cells, each answering for its own images; a central deployment answers 501 `WORKLOAD_PLANE_ELSEWHERE`.", "operationId": "admin_list_platform_images", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPlatformImagesResp" } } }, "description": "Platform images and the cell's defaults" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "post": { "description": "Publish a platform image on this cell: import a public registry ref, pinned by digest, under a name every project can create sandboxes from. A project's own image of the same name takes precedence for that project. Idempotent per name and ref: publishing an existing name with the same ref answers 200 and enqueues nothing, unless its import failed, which retries it. Platform images are immutable; a new ref needs a new name. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_publish_platform_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPlatformImageReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformImageResp" } } }, "description": "The name already exists with this ref; nothing enqueued, and the existing row (its deprecation and description included) is returned unchanged \u2014 use PATCH to change it" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPlatformImageResp" } } }, "description": "Image created (or a failed import reset) and its import enqueued" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid name, a ref that is not pinned by `@sha256:<64 hex>`, or a description over 256 characters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The name exists with a different ref, or the cell's post-deploy migration has not run yet" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No default region is loaded on this cell" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/platform-images/default": { "delete": { "description": "Clear the cell's platform default image for a class (idempotent). A `POST /sandboxes` without `image` then answers 400 `DEFAULT_IMAGE_NOT_CONFIGURED`. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_clear_platform_default_image", "parameters": [ { "description": "The class whose default to clear. Only `linux`; absent means `linux`.", "in": "query", "name": "class", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No default is set for the class" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A class other than `linux`" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "put": { "description": "Set the cell's platform default image for a class: the image a `POST /sandboxes` without `image` boots. Only `linux`. The image must be a ready, non-deprecated Linux platform image. Takes effect on the next create. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_set_platform_default_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPlatformDefaultReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDefaultResp" } } }, "description": "The new default" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or a class other than `linux`" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The image is not a platform image of the class, not ready, or deprecated" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/platform-images/{id}": { "delete": { "description": "Delete a platform image. Refused while any sandbox references it or while it is the platform default; deprecate it first to stop new creates. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_delete_platform_image", "parameters": [ { "description": "Platform image id (`img_\u2026`)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Platform image deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No platform image with this id on this cell" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The image is the platform default, or a sandbox still references it" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "patch": { "description": "Deprecate or restore a platform image, or change its description. A deprecated image takes no new creates by name and is not listed to tenants; sandboxes that already use it keep booting, and its `img_\u2026` id still resolves. The current default cannot be deprecated. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_patch_platform_image", "parameters": [ { "description": "Platform image id (`img_\u2026`)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchPlatformImageReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformImageResp" } } }, "description": "The updated platform image" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or a description over 256 characters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No platform image with this id on this cell" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The image is the current platform default" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/regions": { "get": { "description": "List the concrete region catalog visible on this cell for operator routing. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Workload and home cells serve the concrete regions they mount. A standalone central deployment does not author a concrete-region catalog: it keeps this GET only as the cell router's authenticated discovery oracle, returning the empty response the router replaces with its own directory.", "operationId": "admin_list_regions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RegionInfo" }, "type": "array" } } }, "description": "Region catalog for operator discovery" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/registries/global": { "get": { "description": "List the global registry credentials: credentials an operator stored for image pulls by every organization, each scoped to a registry host and a repository prefix. Passwords are never returned. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token. Served on home and workload cells (each reads its own rows, where its pulls resolve); a central deployment answers 501 `WORKLOAD_PLANE_ELSEWHERE`.", "operationId": "admin_list_global_registries", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGlobalRegistriesResp" } } }, "description": "Global registry credential metadata (never passwords)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "put": { "description": "Create or replace the global registry credential for a registry host and repository prefix. Every organization's pulls of an image under that prefix authenticate with it; an empty prefix covers every repository on the host. A prefixed credential takes precedence over a project's own credential for the host; a host-wide one does not. With `import_only: true` the credential serves only pulls of images the platform imported from Daytona v1 (the archived-sandbox import), never an organization's own pull of the same image ref \u2014 set it for a v1 registry, which holds every organization's backups. `import_only` absent keeps the stored value on a replace (`false` on a create). The password is write-only; an empty password keeps the stored one when the kind and username are unchanged. For `kind: ecr` with a new secret, the keys must belong to the AWS account in the host. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_put_global_registry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutGlobalRegistryReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalRegistryMeta" } } }, "description": "Credential replaced" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalRegistryMeta" } } }, "description": "Credential created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid host, prefix, kind/host mismatch, or missing/oversized credential fields; for `kind: ecr`, `ECR_CREDENTIALS_INVALID` or `ECR_ACCOUNT_MISMATCH`" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The credential changed concurrently while keeping its stored password; retry with the password" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`ECR_OWNERSHIP_UNVERIFIABLE` \u2014 AWS STS could not be asked whether the keys own the ECR account; the write fails closed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No master encryption key configured \u2014 credential writes fail closed" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/registries/global/{id}": { "delete": { "description": "Delete a global registry credential (idempotent). New pulls stop using it; images already cached with it stay bootable for existing sandboxes. Requires the platform-operator credential (an OIDC JWT for a configured platform admin, or the internal token).", "operationId": "admin_delete_global_registry", "parameters": [ { "description": "Global registry credential id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Credential removed (or none existed)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners": { "get": { "description": "List the runner fleet visible to the current cell. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Runner liveness and capacity are cell-local, so callers must query the cell whose fleet they want to inspect; a standalone central deployment has no fleet and answers 501 `workload_plane_elsewhere` with the workload API URL to use instead.", "operationId": "admin_list_runners", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerListResp" } } }, "description": "Runner fleet for this cell" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners/{id}": { "get": { "description": "Get one runner and every sandbox currently recorded on it. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. Runner state is cell-local, so the request must go to the cell that owns the runner.", "operationId": "admin_get_runner", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerDetailResp" } } }, "description": "Runner detail for this cell" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Runner not found on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners/{id}/cordon": { "post": { "description": "Cordon a runner so it stops accepting new work. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The change applies only on the runner's own cell, where its heartbeats and NATS control channel live.", "operationId": "admin_cordon_runner", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerAdminStateResp" } } }, "description": "Runner cordoned" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Runner not found on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners/{id}/nats-credentials": { "delete": { "description": "Revoke EVERY live NATS credential of a runner \u2014 the decommission step. 200 with the count, also when it is zero. Requires an operator's own login: the internal token is refused on this route.", "operationId": "admin_revoke_all_runner_nats_credentials", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialsRevokedResp" } } }, "description": "Live credentials revoked (count may be zero)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid runner id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not a configured platform admin, or the internal token" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "summary": "`DELETE /manage/runners/:id/nats-credentials` \u2014 revoke every live\ncredential of the runner (decommission; `credentials::revoke_all`). 200\nwith the count, also when it is zero: the end state \"this runner can no\nlonger authenticate\" holds either way.", "tags": [ "admin" ] }, "get": { "description": "List one runner's NATS credentials (live and revoked; never the token or its hash). Requires an operator's own login: the internal token is refused on this route.", "operationId": "admin_list_runner_nats_credentials", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialListResp" } } }, "description": "The runner's credentials" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid runner id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not a configured platform admin, or the internal token" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] }, "post": { "description": "Mint a NATS credential for one runner (PLAN-NATS-CLIENT-IDENTITY.md D4/D14/D15). The token is returned once and only its hash is stored; the runner presents it to the api's auth callout and receives a user JWT scoped to its own subjects. Requires an operator's own login (OIDC JWT of a configured platform admin): the internal token is refused on this route, automation mints with `rlp-api nats-runner-credential mint`. An empty body means the configured default lifetime; `expires_at` and `no_expiry` are mutually exclusive, and an unknown field is a 400.", "operationId": "admin_mint_runner_nats_credential", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintBody" } } }, "description": "Optional mint options; an empty body is accepted", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Minted" } } }, "description": "Credential minted; `token` is shown only in this response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid runner id, malformed body, unknown field, past `expires_at`, or both `expires_at` and `no_expiry`" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not a configured platform admin, or the internal token (runner identities are minted by a person)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners/{id}/nats-credentials/{cred_id}": { "delete": { "description": "Revoke one NATS credential of a runner. A connection authenticated with it is cut the next time the callout or the bus re-evaluates it. Requires an operator's own login: the internal token is refused on this route.", "operationId": "admin_revoke_runner_nats_credential", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "credential id", "in": "path", "name": "cred_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRevokedResp" } } }, "description": "Credential revoked" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid runner id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not a configured platform admin, or the internal token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No live credential with that id on this runner" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners/{id}/uncordon": { "post": { "description": "Return a runner to the active scheduling state. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The change applies only on the runner's own cell, where its heartbeats and NATS control channel live.", "operationId": "admin_uncordon_runner", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerAdminStateResp" } } }, "description": "Runner uncordoned" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Runner not found on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/manage/runners/{id}/usage": { "get": { "description": "Per-runner billed usage over time (hourly or daily), proxied verbatim from rlp-billing's ClickHouse export of delivered billing events. This route requires the platform-operator credential: either an OIDC JWT for a configured platform admin or the internal token; organization roles and org API keys are not accepted. The runner must exist on the addressed cell.", "operationId": "admin_runner_usage", "parameters": [ { "description": "runner id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "RFC3339 window start. Default: `to` \u2212 7 days. An unparseable value\ntakes the default, as on the sandbox usage routes.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 window end, exclusive. Default: now. Unparseable => default.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "`\"h\"` (hourly, default) or `\"d\"` (daily). Anything else is a 400.", "in": "query", "name": "resolution", "required": false, "schema": { "description": "Query parameters of `GET /manage/runners/:id/usage`. The real extractor\nstruct is also the documented one (no doc-only twin to drift).", "enum": [ "h", "d" ], "type": "string", "x-daytona-exact-enum": "parameter" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Usage series as served by rlp-billing (passthrough body)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`resolution` is not `h` or `d`, or rlp-billing rejected the window" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid platform-operator credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authenticated but not a configured platform admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Runner not found on this cell" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "rlp-billing unreachable or answered an unhandled status (`billing_unreachable`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Usage unavailable: no billing proxy on this cell or ClickHouse not configured (`usage_unavailable`)" } }, "security": [ { "operator": [] } ], "tags": [ "admin" ] } }, "/me": { "get": { "description": "Return the signed-in management-plane user. This route reads only the authenticated principal itself and therefore requires no organization or project permission. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_me", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } }, "description": "Signed-in user" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "me" ] } }, "/me/privacy-policy": { "get": { "description": "Whether the signed-in user has accepted the privacy-policy version the platform currently requires, with the version and a link to the policy text. Reads only the authenticated principal, so it needs no organization or project permission. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_privacy_policy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacyPolicyStatus" } } }, "description": "Consent status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "me" ] } }, "/me/privacy-policy/accept": { "post": { "description": "Record that the signed-in user accepts the named privacy-policy version. The version must be the one the platform currently requires (as returned by `GET /me/privacy-policy`); any other value is refused with 409 so consent is only ever recorded against the text the user was shown. Idempotent: accepting an already-accepted version only refreshes the acceptance time. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_accept_privacy_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptPrivacyPolicyRequest" } } }, "required": true }, "responses": { "204": { "description": "Acceptance recorded" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The named version is not the one the platform currently requires, or the platform requires no consent" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "me" ] } }, "/migration/v1/sandboxes": { "get": { "operationId": "list_v1_sandboxes", "parameters": [ { "description": "Max rows to return. Clamped to `[1, MAX_PAGE_SIZE]`; default\n`DEFAULT_PAGE_SIZE`.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Opaque continuation token from a previous page's `next_cursor`. Absent =\nfirst page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SandboxList" } } }, "description": "One page of the organization's Daytona v1 sandboxes (newest first), read from v1 now; `next_cursor` continues the walk until it is `null`. An organization v1 does not know answers an empty page." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed cursor (not a `next_cursor` this route answered)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing `read:sandboxes`, or a credential for a project other than `default` (`V1_MIGRATION_DEFAULT_PROJECT_ONLY`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The v1 bridge is not configured or did not answer (`V1_BRIDGE_UNAVAILABLE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "`GET /migration/v1/sandboxes?cursor=&limit=`", "tags": [ "migration" ] } }, "/migration/v1/sandboxes/{v1_id}/import": { "post": { "operationId": "import_v1_sandbox", "parameters": [ { "description": "The sandbox's id on Daytona v1", "in": "path", "name": "v1_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ImportV1SandboxReq" } ] } } }, "description": "Optional; an empty body imports with the defaults" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportV1SandboxResp" } } }, "description": "The persistent rlp sandbox the v1 sandbox was imported into: a new one, or the existing import (`existing: true`) unless `force` is set" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body, or the v1 sandbox's settings are refused by sandbox create" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning org is suspended (`ORG_SUSPENDED`), or the project reached its monthly budget (`PROJECT_BUDGET_EXCEEDED`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing `write:sandboxes`, or a credential for a project other than `default` (`V1_MIGRATION_DEFAULT_PROJECT_ONLY`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such v1 sandbox in the organization (`V1_SANDBOX_NOT_FOUND`)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The v1 sandbox cannot be imported (`V1_SANDBOX_NOT_IMPORTABLE`; the message names v1's reason), or a create conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Overload shed (`OVERLOADED`, with `retry_after_secs`: the create queue, or every import slot in this api process busy for 5 s), or the org sandbox limit" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The v1 bridge is not configured or did not answer (`V1_BRIDGE_UNAVAILABLE`), no registry credential covers the backup image's registry (`V1_BACKUP_REGISTRY_UNCONFIGURED`: an operator must store an import-only global registry credential for it), or placement is unavailable" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "`POST /migration/v1/sandboxes/{v1_id}/import`", "tags": [ "migration" ] } }, "/migration/v1/summary": { "get": { "operationId": "get_v1_migration_summary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1MigrationSummary" } } }, "description": "Whether the caller's organization arrived from Daytona v1, and the counts of what came over into its `default` project (the only project synced with v1)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing `read:sandboxes`, or a credential for a project other than `default` (`V1_MIGRATION_DEFAULT_PROJECT_ONLY`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /migration/v1/summary \u2014 what came over from Daytona v1.", "tags": [ "migration" ] } }, "/network-classes": { "get": { "operationId": "list_network_classes", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ClassInfo" }, "type": "array" } } }, "description": "The network class registry" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /network-classes \u2014 the network (NIC) class registry: the classes runners\nadvertise and regions default to, with their tier. Informational \u2014 a create\ncannot select a network class.", "tags": [ "catalog" ] } }, "/org-api-keys/{id}": { "delete": { "description": "Revoke one organization API key. The caller must be a seated member holding `delete:org_api_keys`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_revoke_org_api_key", "parameters": [ { "description": "Organization API key id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedOrgApiKeyResponse" } } }, "description": "Revoked organization API key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `delete:org_api_keys`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Key not found, organization not found, or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /org-api-keys/:id \u2014 revoke an org key (`delete:org_api_keys`). Repeat revoke is\nan idempotent 200, mirroring the project-key `revoke_key`.", "tags": [ "api-keys" ] } }, "/orgs": { "get": { "description": "List the organizations the caller belongs to, including the caller's effective org permissions and assignable project-permission ceiling in each organization. Membership alone admits an organization onto this list; no additional organization permission is required. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_orgs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationsResponse" } } }, "description": "Organizations for the caller" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "organizations" ] }, "post": { "description": "Create a non-personal organization and seat the caller as its initial admin. No existing organization permission is required because this route creates the org context itself. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_org", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedOrganizationResponse" } } }, "description": "Created organization: the caller's membership row for it (id, name, personal, role, roles, permission sets). A fresh organization is never suspended, so the suspension fields of the list/get shape are omitted here." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "organizations" ] } }, "/orgs/{id}": { "delete": { "description": "Delete one organization after the guarded project and resource checks pass. The caller must be a seated member holding `delete:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_delete_org", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedOrganizationResponse" } } }, "description": "Deleted organization" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `delete:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization is personal or still owns blocking resources" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /orgs/:id \u2014 the guarded delete (issue #1122). `delete:organization`;\nthe personal org is undeletable (409); everything else is\n`delete_org_guarded`'s transaction plus the same post-commit key eviction\nthe project delete performs.", "tags": [ "organizations" ] }, "get": { "description": "Read one organization. The caller must be a seated member holding `read:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_org", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": "Organization details" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "organizations" ] }, "patch": { "description": "Rename one organization. The caller must be a seated member holding `write:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not. The name is trimmed and validated (non-empty, no control characters, bounded length); the stored value is the trimmed one.", "operationId": "mgmt_rename_org", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenamedOrganizationResponse" } } }, "description": "Renamed organization" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body or name (empty, control characters, too long)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /orgs/:id \u2014 rename (`write:organization`). The name goes through\n`validate_org_name` (trimmed, non-empty, no control characters, at most\n`ORG_NAME_MAX_CHARS`) and the STORED value is the trimmed one. Downstream,\nthe rename reaches rlp-billing, Stripe and Metronome through the\n`updated_at` the touch trigger bumps and `GET /internal/orgs/renames`\n(PLAN-ORG-RENAME-PROPAGATION); nothing here calls billing.", "tags": [ "organizations" ] } }, "/orgs/{id}/api-keys": { "get": { "description": "List the organization API keys of one organization. The caller must be a seated member holding `read:org_api_keys`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_org_api_keys", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "When true, return revoked keys as well (same semantics as the\nproject-key list).", "in": "query", "name": "include_revoked", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeysResponse" } } }, "description": "Organization API keys" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:org_api_keys`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/api-keys \u2014 list org keys (`read:org_api_keys`; wallet-capable\ncredentials are not visible to a member who lacks it).", "tags": [ "api-keys" ] }, "post": { "description": "Mint an organization API key (`dtno_\u2026`). The caller must be a seated member holding `write:org_api_keys`; the requested `org_permissions` set must stay within the org-key mint allow-list. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_org_api_key", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgKeyReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedOrgApiKeyResponse" } } }, "description": "Minted organization API key; plaintext token is returned once" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:org_api_keys`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization reached its live key cap" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/api-keys \u2014 mint an org key (`write:org_api_keys`). Plaintext token\n(`dtno_\u2026`) returned ONCE; only the sha256 hash is stored.", "tags": [ "api-keys" ] } }, "/orgs/{id}/audit-logs": { "get": { "description": "List one organization's audit logs. The caller must hold `read:audit`: an OIDC user JWT is admitted for any seated member with that permission, and a `dtno_` organization API key is additionally admitted on this route when it holds `read:audit` for the same organization. `actor_created_by` \u2014 the minting user of an actor key \u2014 is member identity and is masked to `null` unless a JWT caller also holds `read:members`; organization API keys never reveal it.", "operationId": "mgmt_list_audit_logs", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Page size (house default/cap)", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Keyset cursor from a previous page's `next_cursor`", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Equality filter on `action`; `action[op]=\u2026` for the operator DSL (PLAN-AUDIT-FILTER-DSL.md)", "in": "query", "name": "action", "required": false, "schema": { "type": "string" } }, { "description": "Equality filter; `target_type[op]=\u2026` for operators", "in": "query", "name": "target_type", "required": false, "schema": { "type": "string" } }, { "description": "Equality filter; `target_id[op]=\u2026` for operators", "in": "query", "name": "target_id", "required": false, "schema": { "type": "string" } }, { "description": "A user id or key id; a non-UUID value yields an empty page, not a 400", "in": "query", "name": "actor", "required": false, "schema": { "type": "string" } }, { "description": "HTTP status of the audited call; `status[op]=\u2026` for operators", "in": "query", "name": "status", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "RFC3339 lower bound (inclusive)", "in": "query", "name": "since", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 upper bound (inclusive: `created_at <= until` on both backends)", "in": "query", "name": "until", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogsResponse" } } }, "description": "Audit-log page" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid cursor or filters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT or organization API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can see the organization but lacks `read:audit`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or org key belongs to another organization" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] }, { "org_key": [ "read:audit" ] } ], "summary": "GET /orgs/:id/audit-logs \u2014 `read:audit` (\u00a73.5), keyset-paginated, newest\nfirst. Same wire contract on both backends: `{\"next_cursor\": \u2026, \"logs\": [\u2026]}`\nand the same wire contract for either credential \u2014 an org key is not a\nsecond API shape, only a second door.", "tags": [ "audit" ] } }, "/orgs/{id}/audit-logs/config": { "get": { "description": "Read whether audit-log capture is disabled for one organization. The caller must be a seated member holding `read:audit`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_audit_config", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditConfigResponse" } } }, "description": "Audit configuration" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:audit`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/audit-logs/config \u2014 `read:audit`; `{\"disabled\": bool}`.", "tags": [ "audit" ] }, "patch": { "description": "Enable or disable workload-plane audit-log capture for one organization. The caller must be a seated member holding `write:audit`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_set_audit_config", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditConfigReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditConfigResponse" } } }, "description": "Updated audit configuration" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:audit`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /orgs/:id/audit-logs/config \u2014 `write:audit` toggle (\u00a73.4). Sheds the\nworkload plane only and is never retroactive; the flusher compares each\nrow's capture time against `audit_logs_disabled_at`.", "tags": [ "audit" ] } }, "/orgs/{id}/billing/balance-notification": { "get": { "description": "Read the balance-notification rule for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_balance_notification", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceNotificationResponse" } } }, "description": "Balance-notification rule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/balance-notification \u2014 member-readable balance\nnotification rule (PLAN-BILLING-NOTIFICATIONS): `{enabled,\nthreshold_amount}` in dollars, derived from the org's Metronome alert.", "tags": [ "billing" ] }, "put": { "description": "Set the balance-notification rule for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_balance_notification", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceNotificationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceNotificationResponse" } } }, "description": "Updated balance-notification rule" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the notification rule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PUT /orgs/:id/billing/balance-notification \u2014 owner-gated rule update\n(PLAN-BILLING-NOTIFICATIONS): body (dollars) forwards verbatim;\nrlp-billing owns the $5\u2013$50,000 bounds and their user-facing messages.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/balances": { "get": { "description": "List itemized balances for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_balances", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "next_page", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceListResponse" } } }, "description": "Balance list" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the query parameters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/balances \u2014 member-readable itemized balances.\n`limit` / `next_page` forward verbatim; rlp-billing owns validation.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/charges": { "get": { "description": "List charge history for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_charges", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "starting_after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeListResponse" } } }, "description": "Charge history" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the query parameters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`stripe_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/charges \u2014 member-readable charge history.\n`limit` / `starting_after` forward verbatim; rlp-billing owns validation\n(`400 bad_limit`).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/charges/{charge_id}/pdf": { "get": { "description": "Download the PDF receipt for one charge. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_charge_pdf", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Charge id", "in": "path", "name": "charge_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/InvoicePdfBody" } } }, "description": "Charge receipt PDF (binary)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Charge id was malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or charge not found, caller is not a member, or billing is not provisioned" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Charge exists but is not yet succeeded" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable or charge PDF rendering is unavailable or busy (`stripe_disabled`, `pdf_unconfigured`, or `pdf_busy`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/charges/:charge_id/pdf \u2014 member-readable receipt\nfor a succeeded charge of the org's Stripe customer, rendered by\nrlp-billing (PLAN-BILLING-PDF); the invoice-PDF route's streaming twin.\nrlp-billing's vocabulary passes through verbatim: `404 charge_not_found`\n(nonexistent AND foreign charges alike \u2014 the route confirms nothing about\nids the org does not own), `409 charge_not_succeeded`,\n`503 pdf_unconfigured`, `503 pdf_busy`.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/email": { "get": { "description": "Read the billing-contact email for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_billing_email", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEmailResponse" } } }, "description": "Billing-contact email" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/email \u2014 member-readable billing contact\n(PLAN-BILLING-PAYMENTS-REMAINDER): `{billing_email, effective_email}`,\nthe rlp-local address billing mail goes to and its creator fallback.\nDistinct from the Stripe customer email on `/billing/info`, which the\nportal owns.", "tags": [ "billing" ] }, "put": { "description": "Set or clear the billing-contact email for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_billing_email", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEmailRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEmailResponse" } } }, "description": "Updated billing-contact email" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the billing-contact body or email" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PUT /orgs/:id/billing/email \u2014 write:wallet-gated billing-contact update\n(PLAN-BILLING-PAYMENTS-REMAINDER): body `{billing_email: string | null}`\nforwards verbatim; rlp-billing owns validation (`400 bad_email` /\n`bad_body`) and the clear-on-null semantics. Audited (audit::ROUTES).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/info": { "get": { "description": "Read the billing identity for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_billing_info", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInfoResponse" } } }, "description": "Billing identity" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled` or `stripe_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/info \u2014 member-readable billing identity (name,\nemail, phone, address) read live from the org's Stripe customer\n(PLAN-BILLING-INFO). Read-only by design: edits go through the Stripe\nbilling portal.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/invoices": { "get": { "description": "List invoices for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_invoices", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "page", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "per_page", "required": false, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } }, "description": "Invoices" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the query parameters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/invoices \u2014 member-readable invoice list\n(PLAN-BILLING-INVOICES). `page` / `per_page` forward verbatim;\nrlp-billing owns validation (`400 bad_pagination`).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/invoices/{invoice_id}/payment-url": { "post": { "description": "Mint a fresh hosted payment URL for one invoice. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_post_invoice_payment_url", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Invoice id", "in": "path", "name": "invoice_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlResponse" } } }, "description": "Invoice payment URL" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invoice id was malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or invoice not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled` or `stripe_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/billing/invoices/:invoice_id/payment-url \u2014 owner-gated:\nthe hosted invoice URL collects money.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/invoices/{invoice_id}/pdf": { "get": { "description": "Download the PDF for one invoice. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_invoice_pdf", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Invoice id", "in": "path", "name": "invoice_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "$ref": "#/components/schemas/InvoicePdfBody" } } }, "description": "Invoice PDF (binary)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invoice id was malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or invoice not found, caller is not a member, or billing is not provisioned" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invoice exists but no document can be rendered for its current state" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable or invoice PDF rendering is unavailable or busy (`metronome_disabled`, `stripe_disabled`, `pdf_unconfigured`, or `pdf_busy`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/invoices/:invoice_id/pdf \u2014 member-readable,\nstreaming pass-through: the Stripe-hosted PDF, or the document rlp-billing\nrenders for an invoice Stripe never hosted (PLAN-BILLING-PDF), forwards\nwith its Content-Type/Content-Disposition and no buffering. rlp-billing's\nJSON errors (`404 invoice_not_found`, `409 invoice_not_finalized`,\n`503 pdf_unconfigured`, `503 pdf_busy` + `Retry-After`) pass through\nverbatim like every other route.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/payment-methods": { "get": { "description": "List saved payment methods for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_payment_methods", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PaymentMethodResponse" }, "type": "array" } } }, "description": "Saved payment methods" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`stripe_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/payment-methods \u2014 member-readable saved cards\n(PLAN-BILLING-PAYMENTS.md).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/plan": { "get": { "description": "The organization's pricing plan: the current and any pending plan, the effective numbers and the plan catalog, proxied verbatim from rlp-billing (PLAN-PRICING-PLANS.md). The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_plan", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Plan DTO as served by rlp-billing (passthrough body)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/plan \u2014 member-readable plan (PLAN-PRICING-PLANS.md\n\u00a7Plan endpoints): the current and pending plan, the effective numbers and\nthe catalog, verbatim from rlp-billing's `GET /orgs/{id}/plan`.", "tags": [ "billing" ] }, "post": { "description": "Self-serve plan change for one organization: `{\"plan\": \"starter\"|\"team\"}` forwarded verbatim to rlp-billing, which owns every check (`unknown_plan`, `contact_sales`, `plan_change_pending`, `payment_method_required`, \u2026) and answers the same DTO as the read. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_post_plan", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "`{\"plan\": \"starter\" | \"team\"}` \u2014 forwarded verbatim; rlp-billing validates it", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Plan DTO after the change (passthrough body)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "rlp-billing rejected the change (`unknown_plan`, `contact_sales`, `plan_change_pending`, `payment_method_required`, \u2026)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/billing/plan \u2014 owner-gated self-serve plan change\n(PLAN-PRICING-PLANS.md D13): forwards `{\"plan\": \"team\"|\"starter\"}`\nverbatim to rlp-billing's `POST /orgs/{id}/plan`, which owns every check\n(`unknown_plan`, `contact_sales`, `plan_change_pending`,\n`payment_method_required`, \u2026) and answers the same DTO as the read.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/portal-url": { "get": { "description": "Mint a fresh billing-portal URL for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_portal_url", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlResponse" } } }, "description": "Billing portal URL" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`stripe_disabled` or `dashboard_url_unset`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/portal-url \u2014 owner-gated: the minted portal session\nURL is itself a capability (its holder can change payment state).\nResponses are fresh sessions and are never cached (the proxy caches\nnothing by design).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/redeem-coupon/{code}": { "post": { "description": "Redeem one coupon for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_post_redeem_coupon", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Coupon code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemCouponResponse" } } }, "description": "Coupon redeemed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, billing is not provisioned, or the coupon code was not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This organization already redeemed that coupon" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The coupon expired or ran out of uses" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/billing/redeem-coupon/:code \u2014 owner-gated coupon\nredemption (PLAN-BILLING-COUPONS): claim-then-grant runs in rlp-billing;\nits status and error strings (\"coupon not found\", \"coupon expired\",\n\"coupon max uses reached\", \"coupon already used\") are user-facing copy\nand pass through verbatim.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/setup-checkout-url": { "get": { "description": "Mint a fresh setup-checkout URL for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_setup_checkout_url", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlResponse" } } }, "description": "Setup-checkout URL" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`stripe_disabled` or `dashboard_url_unset`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/setup-checkout-url \u2014 owner-gated save-a-card\nCheckout session, same capability rationale as the portal URL.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/unpaid-invoices": { "get": { "description": "List unpaid invoices and suspension deadlines for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_unpaid_invoices", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/UnpaidInvoiceResponse" }, "type": "array" } } }, "description": "Unpaid invoices" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/unpaid-invoices \u2014 member-readable open Stripe\ninvoices with the pre-paid suspension deadline (PLAN-BILLING-INVOICES).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/usage": { "get": { "description": "Read current-period priced usage for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_billing_usage", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUsageResponse" } } }, "description": "Current billing usage" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/usage \u2014 member-readable current-period priced usage\n(PLAN-BILLING-USAGE-REPORTS.md).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/usage/past": { "get": { "description": "List past closed billing periods for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_billing_usage_past", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "periods", "required": false, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/OrganizationUsageResponse" }, "type": "array" } } }, "description": "Past billing periods" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the query parameters" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/usage/past \u2014 member-readable closed billing periods.\n`periods` forwards verbatim; rlp-billing owns validation (`400\nbad_periods`).", "tags": [ "billing" ] } }, "/orgs/{id}/billing/wallet": { "get": { "description": "Read the billing wallet for one organization. The caller must be a seated member holding `read:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_wallet", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } }, "description": "Organization wallet" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/billing/wallet \u2014 member-readable wallet.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/wallet/automatic-top-up": { "put": { "description": "Set or clear the automatic top-up rule for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_automatic_top_up", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticTopUpRequest" } } }, "required": true }, "responses": { "204": { "description": "Automatic top-up updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the automatic top-up rule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PUT /orgs/:id/billing/wallet/automatic-top-up \u2014 owner-gated threshold\nrule (PLAN-BILLING-TOPUPS): body (dollars) forwards verbatim; rlp-billing\nowns the validation ladder and the post-paid rejection.", "tags": [ "billing" ] } }, "/orgs/{id}/billing/wallet/top-up": { "post": { "description": "Create a manual wallet top-up session for one organization. The caller must be a seated member holding `write:wallet`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_post_top_up", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlResponse" } } }, "description": "Top-up checkout URL" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing rejected the top-up request body (`bad_body`) or the amount was outside the manual top-up bounds (1,000-99,999,999 cents)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:wallet`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or billing is not provisioned" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing proxy disabled on this deployment (`BILLING_DISABLED`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing service unreachable (`BILLING_UNREACHABLE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing dependency unavailable (`metronome_disabled`, `stripe_disabled`, `stripe_webhook_not_configured`, or `dashboard_url_unset`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/billing/wallet/top-up \u2014 owner-gated manual top-up\n(PLAN-BILLING-TOPUPS): forwards `{\"amount_cents\": N}` verbatim and\nre-serves the minted Stripe Checkout session URL. Fresh session per\nrequest, never cached.", "tags": [ "billing" ] } }, "/orgs/{id}/entitlements": { "get": { "description": "The organization's entitlements as a full catalog map (every catalog key present, `true` when held) plus whether the platform enforces them at admission. The caller must be a seated member holding `read:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_org_entitlements", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsResponse" } } }, "description": "Entitlement map and enforcement switch" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "`GET /orgs/:id/entitlements` (management plane): gated on\n`read:organization`, the floor permission every member holds \u2014 the\ndashboard's `RequireEntitlement` gate needs the map for every member.\nResponse: `{\"enforced\": bool, \"entitlements\": {\"\": bool, \u2026}}` with\nEVERY catalog key present, so the dashboard never guesses at an absent\nkey; `enforced` lets it fail to \"entitled\" while the switch is off.", "tags": [ "organizations" ] } }, "/orgs/{id}/feature-flags": { "get": { "description": "Return the fully evaluated feature-flag map for one organization. The caller must be a seated member holding `read:organization`, which every catalog role implies. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_org_feature_flags", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgFeatureFlagsResponse" } } }, "description": "Evaluated organization feature flags" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/feature-flags \u2014 gated on `read:organization`, the floor\npermission every member holds (PLAN-ORG-ROLES.md): the dashboard needs\nflags for every member, not just the ones who can administer. Response:\n`{\"flags\": {\"\": bool, \u2026}}` \u2014 every catalog key always present,\nforced override already applied (D2: the API is the only evaluator).", "tags": [ "organizations" ] } }, "/orgs/{id}/identity-providers/workos-admin-portal-link": { "post": { "description": "Mint a WorkOS Admin Portal link where the organization's IT admin configures single sign-on (`intent: sso`) or directory sync (`intent: dsync`). The link expires five minutes after issuance. The caller must be a seated member holding `write:sso`; the organization needs the `sso` entitlement (Enterprise plan) where entitlement enforcement is on. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_workos_admin_portal_link", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPortalLinkReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPortalLinkResponse" } } }, "description": "The Admin Portal link" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed body, unknown field or unknown intent" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks `write:sso`, or `ENTITLEMENT_REQUIRED`: single sign-on is not included in the organization's plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A personal organization has no single sign-on, or the organization is not synced with WorkOS" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "WorkOS could not be reached or refused the request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "WorkOS is not configured on this deployment, or the organization is not linked to WorkOS yet" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/identity-providers/workos-admin-portal-link \u2014 `write:sso`.", "tags": [ "organizations" ] } }, "/orgs/{id}/identity-providers/workos-sso-connections": { "get": { "description": "List the SSO connections configured for the organization in the WorkOS Admin Portal. An organization not yet linked to WorkOS has none. The caller must be a seated member holding `read:sso`; the organization needs the `sso` entitlement (Enterprise plan) where entitlement enforcement is on. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_workos_sso_connections", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoConnectionsResponse" } } }, "description": "The organization's SSO connections" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks `read:sso`, or `ENTITLEMENT_REQUIRED`: single sign-on is not included in the organization's plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "WorkOS could not be reached or refused the request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "WorkOS is not configured on this deployment" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/identity-providers/workos-sso-connections \u2014 `read:sso`.", "tags": [ "organizations" ] } }, "/orgs/{id}/invitations": { "get": { "description": "List the undecided invitations of one organization: pending, declined, and expired rows (each carries `declined_at` and `expires_at` so a consumer can tell them apart). The caller must be a seated member holding `read:members`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_org_invitations", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationsResponse" } } }, "description": "Organization invitations" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:members`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "invitations" ] }, "post": { "description": "Create or re-issue an organization invitation. Mints a single-use `dtni_` token and, when the api has an SMTP mailer configured, emails the invitee a link carrying it after the request commits (a re-invite rotates the token and is the resend); without a mailer the response's `accept_url` carries the link instead. The caller must be a seated member holding `write:members`; the route also enforces the role-delegation rules for the invited role set. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_invitation", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationResponse" } } }, "description": "Created or refreshed invitation" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:members`, or the invited role set violates delegation rules" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization is personal or the email already belongs to a member" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization seat cap reached (`limit_exceeded`, PLAN-PRICING-PLANS.md D8): seated members plus undecided invitations are at `max_members`; body carries `limit`/`current`/`max`" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "invitations" ] } }, "/orgs/{id}/invitations/{invitation_id}": { "delete": { "description": "Revoke an unaccepted organization invitation. The caller must be a seated member holding `write:members`; the route also enforces the current-side delegation rule for the invited role set. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_revoke_invitation", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Invitation id", "in": "path", "name": "invitation_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedInvitationResponse" } } }, "description": "Revoked invitation" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:members`, or the invitation violates delegation rules" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or invitation not found, or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /orgs/:id/invitations/:invitation_id \u2014 withdraw an unaccepted\ninvitation (PLAN-INVITATION-REVOKE.md). Requires `write:members`, the same\npermission that created it: an invitation seats nobody, and create and\nrevoke are the two halves of one operation, so splitting them behind\n`delete:members` would produce a caller who can fill the pending list and\ncannot clear it (D1).", "tags": [ "invitations" ] } }, "/orgs/{id}/limits": { "get": { "description": "Effective sandbox limits for one organization with their source (assigned on the organization, the platform default, or unlimited) and current usage: global totals for the soft tier, and the reserved GPU and Windows counts for the strict tier. A limit refusal at admission is a 429 whose envelope `code` is `LIMIT_EXCEEDED`, with `limit`, `current` and `max` as extras. The caller must be a seated member holding `read:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_org_limits", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsResponse" } } }, "description": "Effective limits and usage" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "`GET /orgs/:id/limits` (management plane, home-served): effective limits\nwith their D4 source, usage totals summed from the per-domain rollup (the\nserving cell's own rows included \u2014 its reporter writes them locally on\nboth the fused and the linked arm \u2014 one code path, every row at most one\nexchange window stale; the rows themselves are internal topology and stay\noff the wire), and the scarce-class counts from the LOCAL reservation\nledger.\nThat last source is only authoritative where the ledger lives (a fused\nhome, or central): on a home linked to a standalone central the strict\ntier reserves through central and this read reports 0 \u2014 enforcement stays\ncorrect, the display undercounts. A topology-aware strict read ships with\nthe rest of the linked scarce-class support (tracked in the deferred-work\nissues; no linked deployment exists today).", "tags": [ "organizations" ] }, "patch": { "description": "Set or clear the organization's own `max_timeout_secs`, the one self-service limit: a number in `1..=` the platform maximum to cap every sandbox `timeout_secs` under it, or `null` to inherit the platform maximum. A cap above the platform maximum is an operator assignment and is refused here. The caller must be a seated member holding `write:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_set_org_limits", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServeLimitsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServeLimitsResponse" } } }, "description": "The refreshed timeout limits after the write" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed body, unknown field, a non-positive value, or a value above the platform maximum" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "`PATCH /orgs/:id/limits` (management plane, `write:organization`): an org\nadmin sets \u2014 or clears \u2014 their own `max_timeout_secs`, bounded by the\nplatform's global maximum timeout. The global value is the\nSELF-SERVICE ceiling (Decision 7 as amended): a member can move the org's\ncap anywhere in `1..=` the global max (clearing inherits it), while a cap\nABOVE the global value remains an operator action on the internal plane\n(`POST /internal/orgs/:id/limits`) \u2014 which also means a member write can\nLOWER an operator-granted escape but never re-raise it past the global\nvalue. There is no default knob at any level (Decision 7 as amended), so\nunlike the internal assignment there is no cross-field rule to hold a\nsnapshot for: after the bound checks this is one bare UPDATE of the one\ncolumn, no transaction or row lock needed. Echoes the refreshed `timeouts`\ngroup so the Limits page can re-render from the response.", "tags": [ "organizations" ] } }, "/orgs/{id}/macos-settings": { "get": { "operationId": "mgmt_get_macos_settings", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacosSettings" } } }, "description": "Organization macOS auto-reserve settings" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing read:organization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/macos-settings \u2014 `read:organization`.", "tags": [ "organizations" ] }, "patch": { "operationId": "mgmt_set_macos_settings", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacosSettingsPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacosSettings" } } }, "description": "Stored macOS auto-reserve settings" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or auto-reserve cap" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing write:organization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /orgs/:id/macos-settings \u2014 `write:organization` (admins). Turning\nauto-reserve on records when and by whom; turning it on again while on\nkeeps the original record; turning it off clears it.", "tags": [ "organizations" ] } }, "/orgs/{id}/members": { "get": { "description": "List the members of one organization. The caller must be a seated member holding `read:members`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_members", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembersResponse" } } }, "description": "Organization members" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:members`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "members" ] } }, "/orgs/{id}/members/{user_id}": { "delete": { "description": "Remove a membership from one organization. Removing yourself requires only `read:organization`; removing another member requires `delete:members`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_remove_member", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Member user id", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedMemberResponse" } } }, "description": "Removed member" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks the permission required to remove this member" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or member not found, or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Removing this member would remove the last admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "members" ] }, "patch": { "description": "Replace a member's role assignments in one organization. The caller must be a seated member holding `write:members`; the route also enforces the delegation rules and last-admin guard. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_update_member", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Member user id", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdateResponse" } } }, "description": "Updated member, or a dry-run preview when `dry_run` is true" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks `write:members`, attempted to change their own membership, or violated the delegation rules" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or member not found, or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Demoting this member would remove the last admin" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /orgs/:id/members/:user_id \u2014 replace a member's role assignments\nwholesale. Requires `write:members`, and is the ONLY surface that can\nnarrow a seated member, which is why the cascade has one call site.", "tags": [ "members" ] } }, "/orgs/{id}/members/{user_id}/removal-preview": { "get": { "description": "Preview how many keys would be revoked if this membership were removed. Removing yourself requires only `read:organization`; removing someone else requires `delete:members`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_member_removal_preview", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Member user id", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalPreviewResponse" } } }, "description": "Membership-removal preview" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks the permission required for this preview" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization or member not found, or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "Read-only preview of the member-removal key-revocation cascade\n(PLAN-MEMBER-REMOVAL-PREVIEW.md). Authorization copies `remove_member`'s\nself/other split and checks authority, not last-Admin or delegation\nfeasibility (D2).", "tags": [ "members" ] } }, "/orgs/{id}/otel-config": { "delete": { "description": "Remove the organization's OTEL forwarding config; sandbox telemetry stops being forwarded. Idempotent. The caller must be a seated member holding `write:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_delete_otel_config", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Config removed (or none was set)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "`DELETE /orgs/:id/otel-config` \u2014 `write:organization`; `204`, also when\nnothing was stored.", "tags": [ "organizations" ] }, "get": { "description": "The organization's OTEL forwarding config (PLAN-ORG-OTEL-CONFIG.md): the tenant's OTLP/HTTP endpoint and the NAMES of its request headers \u2014 header values are write-only and never returned. The caller must be a seated member holding `read:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_otel_config", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtelConfigView" } } }, "description": "The organization's OTEL config" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or no config is set" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "`GET /orgs/:id/otel-config` \u2014 `read:organization`; `404 not_found` when\nthe organization has no config.", "tags": [ "organizations" ] }, "put": { "description": "Replace the organization's OTEL forwarding config: the OTLP/HTTP endpoint and the request headers to send (header values are write-only). The whole config is replaced; an unknown body field is a 400. The caller must be a seated member holding `write:organization`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_otel_config", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutOtelConfigReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtelConfigView" } } }, "description": "The stored config (header names only)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed body, unknown field, or an endpoint the deployment's policy refuses" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:organization`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "`PUT /orgs/:id/otel-config` \u2014 `write:organization`; replaces the whole\nconfig (D4). The audit row records the endpoint and the header names,\nnever a value.", "tags": [ "organizations" ] } }, "/orgs/{id}/preview-warning": { "patch": { "description": "Turn the proxy's preview warning page off or on for every sandbox preview of the organization. The caller must be a seated member holding `write:organization`; turning the page off (`disabled: true`) additionally needs the `preview_warning_opt_out` entitlement (Team plan and above) where entitlement enforcement is on. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_set_preview_warning", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewWarningReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewWarningResponse" } } }, "description": "The stored value after the write" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed body or unknown field" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks `write:organization`, or `ENTITLEMENT_REQUIRED`: turning the page off is not included in the organization's plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /orgs/:id/preview-warning \u2014 `write:organization`; `{\"disabled\": bool}`\nin, `{\"disabled\": bool}` out. Order of checks: non-member 404, missing\npermission 403 (`require_permission`), a refused body 400 (enveloped,\nlike the otel-config PUT), then \u2014 only for `disabled: true` \u2014 403\n`entitlement_required` naming `preview_warning_opt_out`, all before the\nwrite.", "tags": [ "organizations" ] } }, "/orgs/{id}/principal": { "get": { "description": "The caller's own resolved principal in one organization: its kind (`user` or `org_key`), identity and the canonical-order org permission strings it holds. No permission beyond membership (users) or key scoping (org keys) is required \u2014 it reveals only the caller's own grants. A non-member user, or an org key scoped to another organization, is a 404. This is one of the two management routes that admit a `dtno_` organization API key.", "operationId": "mgmt_get_principal", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalResponse" } } }, "description": "The caller's principal" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid credential" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found, caller is not a member, or the org key is scoped to another organization" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] }, { "org_key": [] } ], "summary": "GET /orgs/:id/principal \u2014 `200` with the caller's kind, identity and\ncanonical-order org permission strings:", "tags": [ "organizations" ] } }, "/orgs/{id}/projects": { "get": { "description": "List the projects the caller may enter inside one organization. The caller must be a seated member holding `read:projects`; non-admin members see the org's `default` project plus projects where they hold an explicit membership row. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_projects", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectsResponse" } } }, "description": "Projects visible to the caller" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:projects`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "post": { "description": "Create a project inside one organization. The caller must be a seated member holding `write:projects`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_project", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } }, "description": "Created project" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid project name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:projects`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project name already exists" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] } }, "/orgs/{id}/service-accounts": { "get": { "description": "List the service accounts of one organization. The caller must be a seated member holding `read:service_accounts`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_service_accounts", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "When true, return archived accounts as well. Mirrors `include_revoked`\non the key list: retired principals are noise, shown only on request.", "in": "query", "name": "include_archived", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountsResponse" } } }, "description": "Service accounts" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:service_accounts`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /orgs/:id/service-accounts \u2014 `read:service_accounts`.", "tags": [ "service-accounts" ] }, "post": { "description": "Create a service account in one organization. The caller must be a seated member holding `write:service_accounts`, and the requested role set must stay within the caller's effective permissions. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_service_account", "parameters": [ { "description": "Organization id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountResponse" } } }, "description": "Created service account" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:service_accounts`, or the requested roles exceeded the caller's permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization not found or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization was personal or the service account name already existed" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /orgs/:id/service-accounts \u2014 `write:service_accounts`.", "tags": [ "service-accounts" ] } }, "/projects/{id}": { "delete": { "description": "Delete one project after the guarded resource checks pass. The caller must be able to enter the project and hold `delete:projects` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_delete_project", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedProjectResponse" } } }, "description": "Deleted project" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `delete:projects`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project was the default project or still owned blocking resources" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /projects/:id \u2014 the guarded delete (PLAN-PROJECTS.md D7/D8).", "tags": [ "projects" ] }, "get": { "description": "Read one project. The caller must be able to enter the project and hold `read:projects` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_project", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } }, "description": "Project details" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:projects`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /projects/:id \u2014 one project. `read:projects`; unknown, non-member and\nno-access all answer 404 through `resolve_project`.", "tags": [ "projects" ] }, "patch": { "description": "Rename one project. The caller must be able to enter the project and hold `write:projects` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_rename_project", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } }, "description": "Renamed project" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the new project name was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:projects`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project was the default project or the new name already existed" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /projects/:id \u2014 rename. `write:projects`. The default project cannot\nbe renamed (its name IS the default marker) and `default` is reserved.", "tags": [ "projects" ] } }, "/projects/{id}/api-keys": { "get": { "description": "List the API keys of one project. The caller must be able to enter the project and hold `read:project_api_keys`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_project_api_keys", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "When true, return revoked keys as well. Defaults to false so the list\nonly surfaces live keys \u2014 revoked keys are noise (and are purged after 7\ndays by the reaper), shown only on explicit request.", "in": "query", "name": "include_revoked", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKeysResponse" } } }, "description": "Project API keys" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:project_api_keys`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "api-keys" ] }, "post": { "description": "Mint a project API key. The caller must be able to enter the project and hold `write:project_api_keys`; the requested `project_permissions` set must stay within the caller's assignable project-permission ceiling. Minting for a service account additionally requires `write:service_accounts`, and the ceiling is intersected with that account's permissions. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_create_project_api_key", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedProjectApiKeyResponse" } } }, "description": "Minted project API key; plaintext token is returned once" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the key request was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:project_api_keys` (or `write:service_accounts` when minting for a service account), or the requested permissions exceeded the assignable ceiling" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, caller cannot enter the project, or the service account was not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Service account was archived or the project reached its live key cap" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "api-keys" ] } }, "/projects/{id}/budget": { "delete": { "description": "Remove one project's monthly spend budget. A budget hold on the project is released; sandboxes already stopped stay stopped. The caller must be able to enter the project and hold `write:budgets` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_delete_project_budget", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Budget removed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:budgets`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, caller cannot enter the project, or the project has no budget" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /projects/:id/budget \u2014 `write:budgets`; no entitlement (D8: a\ndowngraded organization can still remove a budget). Releases the hold.", "tags": [ "projects" ] }, "get": { "description": "Read one project's monthly spend budget and its current state. The caller must be able to enter the project and hold `read:budgets` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_project_budget", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudget" } } }, "description": "The project's budget" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:budgets`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, caller cannot enter the project, or the project has no budget" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /projects/:id/budget \u2014 `read:budgets`.", "tags": [ "projects" ] }, "put": { "description": "Set one project's monthly spend budget, in US cents. When the project's month-to-date spend reaches the budget, new sandboxes in the project are refused with `PROJECT_BUDGET_EXCEEDED`, and after the organization's grace period running persistent sandboxes are stopped and running ephemeral sandboxes deleted. A macOS sandbox runs on a prepaid Mac lease and is exempt from both; the hold refuses buying or renewing a Mac lease the project bought instead. The caller must be able to enter the project and hold `write:budgets` in the owning organization; the organization needs the `project_budgets` entitlement (Team plan and above) where entitlement enforcement is on. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_project_budget", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutProjectBudgetReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudget" } } }, "description": "The project's budget after the write" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the body was invalid (`monthly_limit_cents` must be an integer from 100 to 100000000000)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:budgets`, or `ENTITLEMENT_REQUIRED`: project budgets are not included in the organization's plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PUT /projects/:id/budget \u2014 `write:budgets` plus the `project_budgets`\nentitlement. Order: 404 (unknown/non-member/no access), 403 permission,\n400 body, 403 `entitlement_required`.", "tags": [ "projects" ] } }, "/projects/{id}/lifecycle-policy": { "get": { "description": "Read stored project lifecycle defaults and the effective policy a bare create receives for each supported sandbox class and persistence mode. The caller must be able to enter the project and hold `read:projects` in the owning organization. Only an OIDC user JWT is admitted.", "operationId": "mgmt_get_project_lifecycle_policy", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectLifecyclePolicyDto" } } }, "description": "Stored and effective project lifecycle defaults" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:projects`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "patch": { "description": "Update project lifecycle defaults at block granularity: a block absent from the body is kept as stored, `null` clears it, and an object replaces the whole block (a field missing inside it is unset). Only the blocks in the body are validated; a timeout equal to the stored value is not re-checked against a maximum lowered since it was stored. The caller must be able to enter the project and hold `write:projects`; changing a delete-bearing trigger additionally requires `delete:sandboxes` in the project. Only an OIDC user JWT is admitted.", "operationId": "mgmt_update_project_lifecycle_policy", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectLifecyclePolicyReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectLifecyclePolicyDto" } } }, "description": "Stored and effective project lifecycle defaults after the update" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed body, unknown field, invalid pair, unsupported value, or timeout above the effective maximum" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller lacks `write:projects` or the required `delete:sandboxes` project permission" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] } }, "/projects/{id}/members": { "get": { "description": "List who can access one project. The caller must be able to enter the project and hold `read:members` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_project_members", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectMembersResponse" } } }, "description": "Project members" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:members`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /projects/:id/members \u2014 who can access the project. Every explicit row,\nplus every admin flagged `implicit`; on the default project every org\nmember is listed and every row is implicit.", "tags": [ "members" ] }, "post": { "description": "Add one explicit project-membership row. The caller must be able to enter the project and hold `write:members` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_add_project_member", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProjectMemberReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddedProjectMembersResponse" } } }, "description": "Added project member ids" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:members`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or member not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The default project is open to every member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /projects/:id/members \u2014 add one member. Idempotent: `{\"added\": [id]}`\nwhen a row was inserted, `{\"added\": []}` when it already existed \u2014 the same\ncontract as the bulk route.", "tags": [ "members" ] } }, "/projects/{id}/members/bulk": { "post": { "description": "Add up to 200 explicit project-membership rows in one request. The caller must be able to enter the project and hold `write:members` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_add_project_members_bulk", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProjectMembersBulkReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddedProjectMembersResponse" } } }, "description": "Added project member ids" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the request exceeded the bulk limit" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:members`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or member not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The default project is open to every member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /projects/:id/members/bulk \u2014 add up to 200 members, all-or-nothing.", "tags": [ "members" ] } }, "/projects/{id}/members/{user_id}": { "delete": { "description": "Remove one explicit project-membership row and revoke that member's keys in the project when needed. The caller must be able to enter the project and hold `write:members` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_remove_project_member", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Member user id", "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedProjectMemberResponse" } } }, "description": "Removed project member" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:members`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or membership not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The default project is open to every member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /projects/:id/members/:user_id \u2014 remove an explicit row and, unless\nthe member holds `admin` (implicit access anyway), revoke the live keys\nthey minted in this project (D9). Self-removal is allowed; there is no\nlast-member guard because every admin can still reach the project.", "tags": [ "members" ] } }, "/projects/{id}/registries": { "get": { "description": "List registry credentials metadata for one project. The caller must be able to enter the project and hold `read:registries`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_project_registries", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRegistriesResp" } } }, "description": "Project registries" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:registries`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "put": { "description": "Create or update one registry credential for a project, naming the host in the request body instead of the path. The caller must be able to enter the project and hold `write:registries`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_project_registry_body", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutRegistryBodyReq" } } }, "required": true }, "responses": { "204": { "description": "Registry upserted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the request body was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:registries`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secret encryption is unavailable on this deployment (`queue_timeout`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] } }, "/projects/{id}/registries/{host}": { "delete": { "description": "Delete one registry credential from a project. The caller must be able to enter the project and hold `delete:registries`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_delete_project_registry", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Registry host", "in": "path", "name": "host", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Registry deleted (idempotent: 204 even when the host was already absent)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the host was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `delete:registries`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "get": { "description": "Read one registry credential metadata row for a project. The caller must be able to enter the project and hold `read:registries`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_project_registry", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Registry host", "in": "path", "name": "host", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryMeta" } } }, "description": "Project registry metadata" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the host was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:registries`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or registry not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Central control plane unreachable (workload-cell call-through)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "put": { "description": "Create or update one registry credential for a project. The caller must be able to enter the project and hold `write:registries`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_project_registry", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Registry host", "in": "path", "name": "host", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutRegistryReq" } } }, "required": true }, "responses": { "204": { "description": "Registry upserted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, the host was invalid, or the request body was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:registries`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secret encryption is unavailable on this deployment (`queue_timeout`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] } }, "/projects/{id}/secrets": { "get": { "description": "List secret metadata for one project. The caller must be able to enter the project and hold `read:secrets`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_project_secrets", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSecretsResp" } } }, "description": "Project secrets metadata" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:secrets`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "put": { "description": "Create or update one secret in a project, naming it in the request body instead of the path. The caller must be able to enter the project and hold `write:secrets`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_project_secret_body", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSecretBodyReq" } } }, "required": true }, "responses": { "204": { "description": "Secret upserted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the request body was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:secrets`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secret already existed with create-only semantics, or another create for the same name won a concurrent race" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secret encryption is unavailable on this deployment (`queue_timeout`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PUT /projects/:id/secrets with `{name, value, ...}` in the body \u2014 an\nalternative to the path-named form for clients that prefer a single\ncollection endpoint.", "tags": [ "projects" ] } }, "/projects/{id}/secrets/{name}": { "delete": { "description": "Delete one secret from a project. The caller must be able to enter the project and hold `delete:secrets`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_delete_project_secret", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Secret name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Secret deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `delete:secrets`" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "get": { "description": "Read one secret metadata row from a project. The caller must be able to enter the project and hold `read:secrets`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_project_secret", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Secret name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretMeta" } } }, "description": "Secret metadata" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:secrets`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or secret not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] }, "put": { "description": "Create or update one secret in a project. The caller must be able to enter the project and hold `write:secrets`. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_put_project_secret", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Secret name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSecretReq" } } }, "required": true }, "responses": { "204": { "description": "Secret upserted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed, `default` was ambiguous, or the request body was invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:secrets`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secret already existed with create-only semantics, or another create for the same name won a concurrent race" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secret encryption is unavailable on this deployment (`queue_timeout`)" } }, "security": [ { "user_jwt": [] } ], "tags": [ "projects" ] } }, "/projects/{id}/service-accounts": { "get": { "description": "List which service accounts can hold API keys in one project. The caller must be able to enter the project and hold `read:service_accounts` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_project_service_accounts", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccountsResponse" } } }, "description": "Project service accounts" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `read:service_accounts`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project not found, caller is not a member, or caller cannot enter the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /projects/:id/service-accounts \u2014 which accounts can be minted keys in\nthe project. On a non-default project, every account with a row (archived\nones included, with `archived_at` set, so an operator can see and clean up\na retired account's reach); on the default project every live account of\nthe org, all `implicit: true` with no `added_at`.", "tags": [ "service-accounts" ] }, "post": { "description": "Add one explicit service-account membership row to a project. The caller must be able to enter the project and hold `write:service_accounts` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_add_project_service_account", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddProjectServiceAccountReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddedProjectServiceAccountsResponse" } } }, "description": "Added project service-account ids" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:service_accounts`, or lacked authority over the account" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or service account not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The default project is open to every service account, or the service account was archived" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "POST /projects/:id/service-accounts \u2014 add one account. Idempotent:\n`{\"added\": [id]}` when a row was inserted, `{\"added\": []}` when it already\nexisted \u2014 the member routes' contract.", "tags": [ "service-accounts" ] } }, "/projects/{id}/service-accounts/{sa_id}": { "delete": { "description": "Remove one explicit service-account membership row from a project and revoke the account's keys in that project. The caller must be able to enter the project and hold `write:service_accounts` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_remove_project_service_account", "parameters": [ { "description": "Project id, or the literal `default` for the caller's default project alias", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Service account id", "in": "path", "name": "sa_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovedProjectServiceAccountResponse" } } }, "description": "Removed project service account" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project id was malformed or `default` was ambiguous" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller can enter the project but lacks `write:service_accounts`, or lacked authority over the account" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Project or membership not found, caller is not a member, or caller cannot enter the project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The default project is open to every service account" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /projects/:id/service-accounts/:sa_id \u2014 remove the row and revoke\nthe live keys the account owns in this project (D9, account side): an\naccount that can no longer enter a project must not keep a credential to\nit. The account itself survives.", "tags": [ "service-accounts" ] } }, "/region-catalog": { "get": { "description": "The structured counterpart of `GET /macro-regions` for clients that only\nneed to know which regions exist and how they nest. A Macro region\ndedicated to another organization is never listed. The catalog describes\ntopology, not capacity or health: a listed Macro can still refuse a create\nit has no capacity or matching hardware for.", "operationId": "get_region_catalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionCatalogResp" } } }, "description": "Macro region IDs grouped by Geo group under the Global root; an empty platform is a 200 with an empty `global` object" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /region-catalog \u2014 the Macro regions available on the platform, grouped\nby Geo group under the Global root.", "tags": [ "regions" ] } }, "/region-hierarchy": { "get": { "description": "Every id here is a valid create-time `region` selector (the levels share one\nnamespace, guarded by database triggers). The response separates three\ndifferent facts about each node, and a client gates on the right one:\n\n * `local_region_count` \u2014 structural descendants, disabled ones included.\n * `eligible_local_region_count` \u2014 descendants the FLEET may place in\n (active, routable, opted into broad placement). Gate what you *show*\n on this; it does not depend on which API answered.\n * `selectable` \u2014 this API's local broad-execution eligibility, or an\n Edge's direct routability. A separately configured workload router has\n its own request path; router-aware clients combine that path with the\n positive fleet count rather than this API's local served scope.\n\nCounts are inventory, never capacity: a `selectable` node can still be\nrefused by class-aware narrowing, artifact locality or admission.", "operationId": "get_region_hierarchy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionHierarchy" } } }, "description": "The region hierarchy, one node per level" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /region-hierarchy \u2014 the four-level placement hierarchy.", "tags": [ "regions" ] } }, "/regions": { "get": { "description": "Rows are filtered to active AND **routable** ones: the dashboard fans its\nsandbox list out over this catalog's `api_base_url`s, so a row whose URL no\nclient can build a request from is a wasted (and possibly slow-failing) leg\non every list, forever \u2014 see `RegionInfo::is_routable`. The row still exists\nand still resolves for placement; it is only kept out of the catalog handed\nto clients.", "operationId": "list_regions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RegionInfo" }, "type": "array" } } }, "description": "Active Edge regions" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [] }, { "platform_token": [] } ], "summary": "GET /regions \u2014 the active Edge region catalog (project/machine plane). Clients\nuse this for region discovery (the `target` a create names).", "tags": [ "regions" ] } }, "/registries": { "get": { "operationId": "list_registries", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRegistriesResp" } } }, "description": "Registry credential metadata for the project (never passwords)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:registries`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:registries" ] }, { "platform_token": [ "read:registries" ] } ], "summary": "GET /registries \u2014 list the project's registry credentials (metadata only;\npasswords are write-only and never returned).", "tags": [ "registries" ] }, "put": { "operationId": "put_registry_body", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutRegistryBodyReq" } } }, "required": true }, "responses": { "204": { "description": "Credential stored" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid host, kind/host mismatch, or missing/oversized credential fields; for `kind: ecr`, `ECR_CREDENTIALS_INVALID` (the username is not an AWS access key id, or AWS STS refused the keys) or `ECR_ACCOUNT_MISMATCH` (the keys belong to another AWS account than the host names)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:registries`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`ECR_OWNERSHIP_UNVERIFIABLE` \u2014 AWS STS could not be asked whether the keys own the ECR account (`kind: ecr` only); the write fails closed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No master encryption key configured \u2014 credential writes fail closed" } }, "security": [ { "api_key": [ "write:registries" ] }, { "platform_token": [ "write:registries" ] } ], "summary": "PUT /registries \u2014 body form of the upsert (host in the body instead of the\npath). Same write-only password semantics as `PUT /registries/{host}`.", "tags": [ "registries" ] } }, "/registries/{host}": { "delete": { "operationId": "delete_registry", "parameters": [ { "description": "Registry host (`host[:port]`, no scheme/path); Docker Hub aliases normalize to `index.docker.io`", "in": "path", "name": "host", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Credential removed (or none existed)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid registry host" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`delete:registries`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "delete:registries" ] }, { "platform_token": [ "delete:registries" ] } ], "summary": "DELETE /registries/:host \u2014 remove the credential for a host (idempotent:\n204 whether or not a credential existed).", "tags": [ "registries" ] }, "get": { "operationId": "get_registry", "parameters": [ { "description": "Registry host (`host[:port]`, no scheme/path); Docker Hub aliases normalize to `index.docker.io`", "in": "path", "name": "host", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryMeta" } } }, "description": "Registry credential metadata (never the password)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid registry host" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:registries`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No credential for that host" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Central control plane unreachable (workload-cell call-through)" } }, "security": [ { "api_key": [ "read:registries" ] }, { "platform_token": [ "read:registries" ] } ], "summary": "GET /registries/:host \u2014 metadata for one registry credential (never the\npassword). The host is normalized before lookup, so Docker Hub aliases\n(e.g. `docker.io`) find the canonical `index.docker.io` row.", "tags": [ "registries" ] }, "put": { "operationId": "put_registry", "parameters": [ { "description": "Registry host (`host[:port]`, no scheme/path); Docker Hub aliases normalize to `index.docker.io`", "in": "path", "name": "host", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutRegistryReq" } } }, "required": true }, "responses": { "204": { "description": "Credential stored" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid host, kind/host mismatch, or missing/oversized credential fields; for `kind: ecr`, `ECR_CREDENTIALS_INVALID` (the username is not an AWS access key id, or AWS STS refused the keys) or `ECR_ACCOUNT_MISMATCH` (the keys belong to another AWS account than the host names)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:registries`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`ECR_OWNERSHIP_UNVERIFIABLE` \u2014 AWS STS could not be asked whether the keys own the ECR account (`kind: ecr` only); the write fails closed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No master encryption key configured \u2014 credential writes fail closed" } }, "security": [ { "api_key": [ "write:registries" ] }, { "platform_token": [ "write:registries" ] } ], "summary": "PUT /registries/:host \u2014 create or replace the credential for a registry\nhost (one credential per host, docker-config semantics). The password is\nwrite-only: encrypted at rest and never returned by any endpoint. With the\nECR ownership check on (the default), a `kind: ecr` credential is stored\nonly once AWS STS confirms the keys belong to the account named in the host.", "tags": [ "registries" ] } }, "/reservations": { "get": { "operationId": "list_reservations", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReservationsResp" } } }, "description": "The organization's leases" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /reservations \u2014 the organization's leases, newest first (open ones\nplus those ended in the last 30 days).", "tags": [ "reservations" ] }, "post": { "operationId": "create_reservation", "parameters": [ { "description": "Required. Unique per organization; a replay with the same body returns the existing lease", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReservationReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacReservation" } } }, "description": "Idempotent replay of an existing lease" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacReservation" } } }, "description": "Lease created (`leasing`, or `pending_charge` while billing answers)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid Idempotency-Key, unknown region, or vms_per_mac outside 1..2" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization suspended (`org_suspended`), the key's project reached its monthly budget (`project_budget_exceeded`), balance too low (`insufficient_balance`), or billing rejected the charge (`charge_failed`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the organization does not have the `macos_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No unleased Mac is free in the region (`no_mac_available`), or the Idempotency-Key was used with a different body (`idempotency_key_reused`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing's balance check is unavailable; retry" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /reservations \u2014 lease one Mac in a region for the caller's\norganization. Charges the first period, then publishes the lease to the\nregion's unleased Macs; period 1 starts when a Mac claims it.", "tags": [ "reservations" ] } }, "/reservations/{id}": { "get": { "operationId": "get_reservation", "parameters": [ { "description": "External reservation id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacReservation" } } }, "description": "The lease" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another organization, or a region tag that does not match)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /reservations/{id} \u2014 one lease.", "tags": [ "reservations" ] }, "patch": { "operationId": "update_reservation", "parameters": [ { "description": "External reservation id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReservationReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacReservation" } } }, "description": "The updated lease" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the request turns auto-renew on and the organization does not have the `macos_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The lease has ended or failed" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "PATCH /reservations/{id} \u2014 turn a live lease's auto-renew on or off.\nTurning it on needs the `macos_sandboxes` flag; turning it off works\nwithout it, so an organization whose flag is off can let a lease lapse.", "tags": [ "reservations" ] } }, "/reservations/{id}/renew": { "post": { "operationId": "renew_reservation", "parameters": [ { "description": "External reservation id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacReservation" } } }, "description": "Renewed, or renewal pending while billing answers (`renewal_pending`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization suspended (`org_suspended`), the lease's project reached its monthly budget (`project_budget_exceeded`), balance too low (`insufficient_balance`), or billing rejected the charge (`charge_failed`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the organization does not have the `macos_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The lease is not active" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing's balance check is unavailable; retry" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /reservations/{id}/renew \u2014 charge the next period of an active lease;\non acknowledgement `period_end` moves out by one period on the same Mac.\nThe manual path; an `auto_renew` lease renews itself while a sandbox is\nactive on it.", "tags": [ "reservations" ] } }, "/roles": { "get": { "description": "Return the fixed role catalog and the permission metadata those roles reference. This is vocabulary, not org-scoped data, so no organization or project permission is required. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_list_roles", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesCatalogResponse" } } }, "description": "Role catalog and permission metadata" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /roles \u2014 the fixed role catalog plus the permission metadata it refers\nto, in ONE response so a client never has to join two fetches to render a\nrole's permissions grouped by category. No org scoping and no permission\ngate: this is a vocabulary, not data.", "tags": [ "roles" ] } }, "/runners/{id}/capacity": { "get": { "description": "Scoped to runners that currently host one of the caller's project's live\nsandboxes (any non-terminal status \u2014 `stopped`/`paused` persistent sandboxes\nare still placed there): any other id \u2014 malformed, unknown, another\ntenant's placement, or a runner the project only used in the past \u2014 is a\n400 or a 404, never a probe.", "operationId": "runner_capacity", "parameters": [ { "description": "runner id (`[A-Za-z0-9_-]{1,128}`)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerCapacityResp" } } }, "description": "Capacity report (live or last heartbeat)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed runner id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:runners`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Runner unknown to this cell, or none of the caller's project's live sandboxes is placed on it" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:runners" ] }, { "platform_token": [ "read:runners" ] } ], "summary": "GET /runners/:id/capacity \u2014 a runner's capacity, probed live over NATS with\nfallback to the last stored heartbeat.", "tags": [ "runners" ] } }, "/sandboxes": { "get": { "operationId": "list_sandboxes", "parameters": [ { "description": "Page size (list mode). Clamped server-side; ignored with `ids`.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Opaque continuation token from a previous page's `next_cursor` (or a\nrow's own `cursor`). Ignored with `ids`.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated external sandbox ids (max 200) \u2014 switches to batch-wait\nmode. Malformed/unowned ids are silently omitted from the result.", "in": "query", "name": "ids", "required": false, "schema": { "type": "string" } }, { "description": "Batch-wait mode: block until at least one id reaches this status (or a\nterminal state).", "in": "query", "name": "wait", "required": false, "schema": { "type": "string" } }, { "description": "Like `wait`, but the status must be reached exactly (terminal-bound\nstates other than the target do not satisfy it). Takes precedence.", "in": "query", "name": "wait_exact", "required": false, "schema": { "type": "string" } }, { "description": "Max time to block in batch-wait mode, ms. Clamped to [0, 60000];\ndefault 30000.", "in": "query", "name": "timeout_ms", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Label filter (list mode, migration 0053): a JSON-encoded object\n`{\"k\":\"v\",...}`. Only sandboxes whose labels CONTAIN every pair are\nreturned. Malformed / non-object => 400. Ignored with `ids`.", "in": "query", "name": "labels", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVmsResp" } } }, "description": "Sandboxes in the project (keyset-paginated, newest first) \u2014 or, with `ids=`, a snapshot of the requested set after the optional wait" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed cursor, empty `ids`, or too many ids (max 200)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "tags": [ "sandboxes" ] }, "post": { "operationId": "create_sandbox", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResp" } } }, "description": "Sandbox admitted (status may be queued/pending/running depending on wait), or an idempotent replay of an earlier create" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body, unknown image, image not ready, class mismatch, or out-of-range create_ttl/wait; `DEFAULT_IMAGE_NOT_CONFIGURED` when `image` is omitted and the platform has no default image" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning org is suspended (`ORG_SUSPENDED`), or the project reached its monthly budget (`PROJECT_BUDGET_EXCEEDED`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks write:sandboxes (or read:secrets when attaching secrets)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not ready, class mismatch, or placement conflict" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Overload shed or org sandbox limit" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Placement unavailable" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes \u2014 create a Linux sandbox (PLAN-CREATION-SHAPE \u00a72).", "tags": [ "sandboxes" ] } }, "/sandboxes/from-snapshot": { "post": { "operationId": "create_sandbox_from_snapshot", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxFromSnapshotReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResp" } } }, "description": "Sandbox restore admitted (or an idempotent replay)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body shape/value (including unknown fields), a region mismatch, or a snapshot not valid for this route" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks write:sandboxes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Snapshot not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Snapshot not ready or capturing runner unavailable" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Overload shed or org sandbox limit" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Placement unavailable" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/from-snapshot \u2014 restore a Linux sandbox from a full memory\nsnapshot (PLAN-CREATION-SHAPE \u00a72).", "tags": [ "sandboxes" ] } }, "/sandboxes/gpu": { "post": { "description": "Create a GPU sandbox. Behind a feature flag: GPU sandboxes are experimental and available only to organizations with the `gpu_sandboxes` feature flag enabled; other organizations get 403 `FEATURE_FLAG_DISABLED`.", "operationId": "create_gpu_sandbox", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGpuSandboxReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResp" } } }, "description": "GPU sandbox admitted (or an idempotent replay)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or request shape" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning org is suspended (`ORG_SUSPENDED`), or the project reached its monthly budget (`PROJECT_BUDGET_EXCEEDED`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`; attaching `secrets` additionally requires `read:secrets`), or the organization does not have the `gpu_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Referenced snapshot not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Referenced checkpoint not ready / missing its artifact, conflicting create identity or request, missing placement routing, or an incompatible volume-create reservation" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create operation permanently retired" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create metadata or placement receipt exceeds its size limit" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create queue at capacity \u2014 overload shed (`overloaded`, with `Retry-After`) \u2014 or an organization sandbox limit reached, including the strict gpu class cap; applies to checkpoint restores too, which are new sandboxes (`limit_exceeded`, PLAN-ORG-LIMITS; body carries `limit`/`current`/`max` and deliberately NO `Retry-After`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Central control plane unreachable for the strict gpu class reservation \u2014 fail-closed call-through on a cell linked to a central (`central_unreachable`, PLAN-ORG-LIMITS)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Placement unavailable; retry the identical request and key" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/sandboxes/gpu/from-snapshot": { "post": { "description": "Restore a GPU checkpoint snapshot into a new GPU sandbox. Behind a feature flag: GPU sandboxes are experimental and available only to organizations with the `gpu_sandboxes` feature flag enabled; other organizations get 403 `FEATURE_FLAG_DISABLED`.", "operationId": "create_gpu_sandbox_from_snapshot", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGpuSandboxFromSnapshotReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResp" } } }, "description": "GPU checkpoint restore admitted (or an idempotent replay)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or snapshot kind" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission, or the organization does not have the `gpu_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Snapshot not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Snapshot not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Overload shed or org sandbox limit" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Placement unavailable" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/sandboxes/macos": { "post": { "description": "Create a macOS sandbox on a Mac the organization leases. Behind a feature flag: macOS sandboxes are available only to organizations with the `macos_sandboxes` feature flag enabled; other organizations get 403 `FEATURE_FLAG_DISABLED`.", "operationId": "create_macos_sandbox", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMacosSandboxReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResp" } } }, "description": "macOS sandbox create enqueued (or an idempotent replay); `reservation_id` names the admitting lease" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body (unknown/other-class fields are rejected, including `vcpus` and `mem_mib`), attached secrets (`secrets_unsupported_on_macos`), a malformed `reservation`, `auto_renew` without `reservation: \"new\"`, an out-of-range `create_ttl` (`create_ttl_out_of_range`) or `wait`, or an unknown region" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Buying a lease was refused: organization suspended (`org_suspended`), the project reached its monthly budget (`project_budget_exceeded`), balance too low (`insufficient_balance`), or billing rejected the charge (`charge_failed`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the organization does not have the `macos_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`image` names no macOS image (`image_not_found`), or `reservation` names no live Mac lease of the organization in the region (`reservation_not_found`)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`image` is not a ready macOS image (`image_not_ready`, `image_class_mismatch`), no Mac lease in the region (`no_active_reservation`), every slot in use (`no_free_slot`), the auto-reserve cap reached (`auto_reserve_limit_reached`), no unleased Mac to buy (`no_mac_available`), or the Idempotency-Key's lease has ended; nothing was published" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create queue at capacity \u2014 overload shed" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Billing's balance check is unavailable, or a persistent sandbox's non-empty env cannot be stored" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/macos \u2014 create a macOS sandbox on a Mac the organization\nleases.", "tags": [ "sandboxes" ] } }, "/sandboxes/search": { "get": { "description": "Reads the central search index (OpenSearch), not this cell's database, so\none call spans the whole fleet. Filters compose with AND; comma lists\n(`status`, `class`, `region`) match any member. Nothing is excluded\nimplicitly: deleted sandboxes are returned until retention removes the\nrow, exactly as `GET /sandboxes` behaves \u2014 narrow with `status`.\n\n**Consistency.** The index is eventually consistent: a committed change is\nsearchable about 2\u20133 s later in steady state, longer during a cluster or\nnetwork incident (documents go stale; nothing is lost). Each item carries\n`updated_at` so you can tell how stale a hit is. For read-your-writes use\n`GET /sandboxes` and `GET /sandboxes/{id}`, which read the database. Results for a\nregion whose cell is still indexing (a newly enabled cell, or one that has\nnot heartbeated) may be incomplete: such regions are named in\n`partial_regions` (and the `x-daytona-search-partial` response header)\nrather than failing the request; results for the other regions are\ncomplete.\n\n**Cursor.** `next_cursor` (and each item's `cursor`) is opaque and bound to\nthe exact filter and sort that produced it: presenting it with a different\nfilter or sort is a `400 cursor does not match this query`, never a silent\nreset. `limit` may change between pages. Paging is best-effort under\nconcurrent mutation \u2014 a sandbox whose sort field changes between two page\nfetches (`status`, `name`, `mem_mib`, `updated_at`, \u2026 are mutable) can\nappear on both pages or on neither, and a sandbox created or deleted\nmid-walk shifts later pages.\n\n**Errors.** `501 SEARCH_NOT_CONFIGURED`: search is not enabled on this\ndeployment \u2014 fall back to `GET /sandboxes`. `503 SEARCH_UNAVAILABLE`: the search\ncluster did not answer (transport, timeout, 5xx); retry later, or fall\nback to `GET /sandboxes`. Both carry the code in the body's `code` field. A\n`400` is always the request's own fault \u2014 fix the parameter, do not retry.", "operationId": "search_sandboxes", "parameters": [ { "description": "Free text over the sandbox `name` and `image_ref`. When the value is\nan external sandbox id (tagged or bare UUID) it also matches that id\nexactly.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "`name` starts with this string (exact, case-sensitive).", "in": "query", "name": "name_prefix", "required": false, "schema": { "type": "string" } }, { "description": "The id starts with this string \u2014 matched against both the\nregion-tagged external id and the bare UUID, so whichever id shape the\nclient saw works. The server-side form of the SDKs' `startsWith` on\n`id`.", "in": "query", "name": "id_prefix", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated lifecycle states (`pending`, `assigned`, `building`,\n`booting`, `running`, `pausing`, `paused`, `stopping`, `stopped`,\n`deleting`, `deleted`, `failed`, `lost`). Unknown => 400.", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated sandbox classes: `linux`, `windows`, `gpu`, `macos`.", "in": "query", "name": "class", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated region slugs. Default: every region.", "in": "query", "name": "region", "required": false, "schema": { "type": "string" } }, { "description": "Exact image reference.", "in": "query", "name": "image_ref", "required": false, "schema": { "type": "string" } }, { "description": "`image_ref` starts with this string.", "in": "query", "name": "image_ref_prefix", "required": false, "schema": { "type": "string" } }, { "description": "Label containment filter: a JSON-encoded object `{\"k\":\"v\",...}`; only\nsandboxes whose labels contain every pair match. Same format as\n`GET /sandboxes?labels=`. Malformed or non-object => 400.", "in": "query", "name": "labels", "required": false, "schema": { "type": "string" } }, { "description": "Persistent (warm-lifecycle) sandboxes only (`true`) or ephemeral only\n(`false`).", "in": "query", "name": "persistent", "required": false, "schema": { "type": "boolean" } }, { "description": "Spot-tier sandboxes only (`true`) or on-demand only (`false`).", "in": "query", "name": "spot", "required": false, "schema": { "type": "boolean" } }, { "description": "Sandboxes forked from this sandbox (external id).", "in": "query", "name": "forked_from", "required": false, "schema": { "type": "string" } }, { "description": "Inclusive lower bound on vCPUs.", "in": "query", "name": "min_vcpus", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Inclusive upper bound on vCPUs.", "in": "query", "name": "max_vcpus", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Inclusive lower bound on memory (MiB).", "in": "query", "name": "min_mem_mib", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Inclusive upper bound on memory (MiB).", "in": "query", "name": "max_mem_mib", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Inclusive lower bound on scratch disk (MiB).", "in": "query", "name": "min_scratch_mib", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Inclusive upper bound on scratch disk (MiB).", "in": "query", "name": "max_scratch_mib", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Created at or after this RFC 3339 instant.", "in": "query", "name": "created_after", "required": false, "schema": { "type": "string" } }, { "description": "Created at or before this RFC 3339 instant.", "in": "query", "name": "created_before", "required": false, "schema": { "type": "string" } }, { "description": "Last modified at or after this RFC 3339 instant.", "in": "query", "name": "updated_after", "required": false, "schema": { "type": "string" } }, { "description": "Last modified at or before this RFC 3339 instant.", "in": "query", "name": "updated_before", "required": false, "schema": { "type": "string" } }, { "description": "Last activity at or after this RFC 3339 instant.", "in": "query", "name": "last_active_after", "required": false, "schema": { "type": "string" } }, { "description": "Last activity at or before this RFC 3339 instant.", "in": "query", "name": "last_active_before", "required": false, "schema": { "type": "string" } }, { "description": "Sort field: `created_at` (default), `updated_at`, `last_activity_at`\n(sandboxes without activity sort last), `name`, `vcpus`, `mem_mib`,\n`scratch_mib`. Ties break on the id.", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "`asc` or `desc` (default).", "in": "query", "name": "order", "required": false, "schema": { "type": "string" } }, { "description": "Page size, clamped to `[1, 200]`; default 100.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Opaque continuation token from a previous page's `next_cursor` (or an\nitem's own `cursor`). Bound to the exact filter and sort of the\nrequest that issued it: presenting it with a different filter or sort\nis a 400. Not part of the token: `limit`.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPage" } } }, "description": "Matching sandboxes in the project, sorted as requested, with `total`, `next_cursor`, and `partial_regions`. Header `x-daytona-search-partial` repeats `partial_regions` (comma-separated) when non-empty." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A parameter that does not parse as its type (a non-integer `limit`, a non-boolean `spot`), unknown `status`/`class`/`sort`/`order`, a string parameter over 256 bytes (` too long`), malformed `labels` (not a JSON object), a `min_*` above its `max_*`, a bad timestamp or id, a malformed cursor, a cursor issued by a different filter/sort (`cursor does not match this query`), or a query the index rejected as malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`SEARCH_NOT_CONFIGURED`: sandbox search is not enabled on this deployment; use `GET /sandboxes`" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`SEARCH_UNAVAILABLE`: the search cluster did not answer (transport failure, timeout, or a 5xx); retry or fall back to `GET /sandboxes`" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "Search sandboxes across every region.", "tags": [ "sandboxes" ] } }, "/sandboxes/windows": { "post": { "description": "Create a Windows sandbox. Behind a feature flag: Windows sandboxes are experimental and available only to organizations with the `windows_sandboxes` feature flag enabled; other organizations get 403 `FEATURE_FLAG_DISABLED`.", "operationId": "create_windows_sandbox", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWindowsSandboxReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVmResp" } } }, "description": "Windows sandbox admitted (or an idempotent replay)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or request shape" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning org is suspended (`ORG_SUSPENDED`), or the project reached its monthly budget (`PROJECT_BUDGET_EXCEEDED`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`; attaching `secrets` additionally requires `read:secrets`), or the organization does not have the `windows_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not found (`IMAGE_NOT_FOUND`)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Image not ready, failed, of another class, or missing its Windows artifact (`IMAGE_NOT_READY` / `IMAGE_BUILD_FAILED` / `IMAGE_CLASS_MISMATCH`), conflicting create identity or request, missing placement routing, or an incompatible volume-create reservation" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create operation permanently retired" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create metadata or placement receipt exceeds its size limit" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Create queue at capacity \u2014 overload shed (`overloaded`, with `Retry-After`) \u2014 or an organization sandbox limit reached, including the strict windows class cap (`limit_exceeded`, PLAN-ORG-LIMITS; body carries `limit`/`current`/`max` and deliberately NO `Retry-After`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Central control plane unreachable for the strict windows class reservation \u2014 fail-closed call-through on a cell linked to a central (`central_unreachable`, PLAN-ORG-LIMITS)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Placement unavailable; retry the identical request and key" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/sandboxes/{id}": { "delete": { "description": "Class-blind by design (unlike the other `/sandboxes` mutations): the in-guest\ndaemon's self-delete calls this URL for every class, and delete dispatches\nper class internally. `/sandboxes/windows/{id}` and `/sandboxes/gpu/{id}` remain\nequivalent class-scoped surfaces.", "operationId": "delete_sandbox", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmActionResp" } } }, "description": "Teardown initiated (`status: deleting`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`delete:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or a per-VM token targeting a sibling sandbox)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "delete:sandboxes" ] }, { "vm_token": [] }, { "sandbox_token": [] }, { "platform_token": [ "delete:sandboxes" ] } ], "summary": "DELETE /sandboxes/:id \u2014 ask the owning runner to tear the VM down, mark 'deleting'.", "tags": [ "sandboxes" ] }, "get": { "operationId": "get_sandbox", "parameters": [ { "description": "External sandbox id (base58 UUID with `-` suffix; bare UUIDs accepted)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "If set (e.g. `running`), block until the VM reaches this status (or a\nterminal state) before responding. Absent = return immediately.", "in": "query", "name": "wait", "required": false, "schema": { "type": "string" } }, { "description": "Like `wait`, but the target status must be reached *exactly* \u2014 a\nterminal-bound state that is not the target does NOT satisfy it. Needed\nfor `wait_exact=stopped`: a VM is `stopping` the instant DELETE is acked,\nand the loose `wait=` predicate treats `stopping` as satisfying any wait,\nso `wait=stopped` returns immediately on the transient `stopping` row.\n`wait_exact=stopped` blocks until the authoritative `stopped` event.\n(PLAN-SUSTAINED-THROUGHPUT Item 3.) It is also the wait to use before a\n`start`: a persistent sandbox with a volume stays `stopping` until its\nvolume execution settles, and only `stopped` means it can start again\n(PLAN-VOLUME-STOP-READINESS). `failed`/`lost` still short-circuit so a\nVM that will never reach the target does not hang until timeout.", "in": "query", "name": "wait_exact", "required": false, "schema": { "type": "string" } }, { "description": "Max time to block, ms. Clamped to [0, 60000]. Default 30000.", "in": "query", "name": "timeout_ms", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmDetail" } } }, "description": "Sandbox detail. With `wait`/`wait_exact`, returned once the predicate is met or the timeout elapses (whichever first)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (or owned by another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/access-token": { "post": { "operationId": "mint_sandbox_access_token", "parameters": [ { "description": "External sandbox id (base58 UUID with `-` suffix; bare UUIDs accepted)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MintAccessTokenReq" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessTokenResp" } } }, "description": "Sandbox access token minted (stateless \u2014 nothing is stored; the token cannot be revoked before its expiry)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Unknown operation string, an operation outside the minter's grantable set (`sandbox:delete` needs `delete:sandboxes` on the minter), `ttl_secs` outside 1..=the deployment cap, or invalid ports (out of 1..=65535, or more than 128 distinct)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key (per-VM and sandbox tokens are rejected \u2014 the data-plane credential never mints new credentials)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the credential's user is no longer a member of the organization or cannot enter the project" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The sandbox is in a terminal state (deleted/failed/lost)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body over 64 KiB" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No platform token issuer is configured on this deployment" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/{id}/access-token \u2014 mint a scoped, short-lived sandbox\naccess token (an ES256 `at+jwt` with `aud: daytona:toolbox`) for one\nsandbox (PLAN-SANDBOX-TOKEN-JWT.md). Class-blind like the other sandbox\nmutations; thin wrapper over the shared mint service.", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/build-logs-url": { "get": { "operationId": "sandbox_url", "parameters": [ { "description": "External sandbox ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildLogsUrl" } } }, "description": "Absolute regional proxy URL" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid project API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Requires read:sandboxes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox or associated build not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Build-log metadata unavailable, including a build claimed for garbage collection" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/endpoints": { "get": { "operationId": "list", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointListResp" } } }, "description": "The sandbox's preview endpoints" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found (or owned by another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /sandboxes/:id/endpoints \u2014 list this sandbox's preview endpoints.", "tags": [ "previews" ] }, "post": { "operationId": "create", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndpointReq" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewEndpoint" } } }, "description": "Endpoint created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Port out of range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found (or owned by another project)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Port already exposed for this sandbox" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/endpoints \u2014 expose a port. 409 if the port is already exposed.", "tags": [ "previews" ] } }, "/sandboxes/{id}/endpoints/{eid}": { "delete": { "operationId": "delete", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "preview endpoint id", "in": "path", "name": "eid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Endpoint removed (or was already gone)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found (or owned by another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "DELETE /sandboxes/:id/endpoints/:eid \u2014 stop exposing a port (idempotent, 204).", "tags": [ "previews" ] }, "patch": { "operationId": "update", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "preview endpoint id", "in": "path", "name": "eid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndpointReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewEndpoint" } } }, "description": "Updated endpoint" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox or endpoint not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "PATCH /sandboxes/:id/endpoints/:eid \u2014 flip an endpoint between public/private.", "tags": [ "previews" ] } }, "/sandboxes/{id}/entrypoint-logs": { "get": { "operationId": "sandbox_entrypoint_logs", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Daemon entrypoint-session log (live for a running sandbox, the persisted copy otherwise)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found, or the sandbox was never placed on a runner" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning runner unreachable" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /sandboxes/:id/entrypoint-logs \u2014 daemon entrypoint-session log\n(PLAN-ENTRYPOINT-LOGS.md + PLAN-JETSTREAM-CRITICAL-ONLY Phase 2). Twin of\n`vm_logs`: the owning runner serves the live daemon output for a RUNNING VM\nand its persisted terminal-store copy otherwise. No longer reads the\nvmentrypointlogs JetStream bucket.", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/files/sign": { "post": { "operationId": "sign_sandbox_file_url", "parameters": [ { "description": "External sandbox id (base58 UUID with `-` suffix; bare UUIDs accepted)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignFileUrlReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedFileUrlResp" } } }, "description": "The pre-signed URL and its parts" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "method not GET/POST, empty path, or `expires` not in the future / beyond the deployment's signed-URL ceiling (7 days by default)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the credential's user is no longer a member of the organization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or a sandbox that cannot carry a signing key)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/{id}/files/sign \u2014 mint a pre-signed download/upload link\nfor a sandbox file (PLAN-SIGNED-FILE-URLS.md). Server-side: the signing\nkey never leaves the API. Class-blind like the other sandbox mutations.", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/fork": { "post": { "operationId": "fork_sandbox", "parameters": [ { "description": "External sandbox id of the (running, paused or stopped persistent) source", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ForkReq" } ] } } }, "description": "Optional body; omit it entirely for a memory fork with the default name" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkResp" } } }, "description": "Fork enqueued (a memory fork lands `paused`, a disk-only fork `stopped`; a fork of a running source is then started automatically)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Fork of a paused or stopped source into a region with no linux-class runner online or seen within the create-queue grace (the fork is placed region-wide; a fork of a running source is taken on the source's own runner and is not subject to this check)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or not a linux sandbox)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Source not persistent, has attached volumes, not running/paused/stopped, a paused memory fork's source is missing its memory artifact, or a fork is already in progress" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization sandbox limit reached \u2014 a fork is a new sandbox, so both the concurrent and total limits apply (`limit_exceeded`, PLAN-ORG-LIMITS; body carries `limit`/`current`/`max` and deliberately NO `Retry-After`) \u2014 or the org's admission queue is saturated (`overloaded`, with `Retry-After`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No runner in the sandbox's region can accept this fork right now (generic `SERVICE_UNAVAILABLE`, with `Retry-After: 10`, one runner heartbeat; PLAN-FAIL-FAST-ADMISSION). Nothing was written: no fork sandbox was created; retry." } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/fork \u2014 duplicate a persistent linux sandbox into a new one\n(PLAN-FORK.md).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/images": { "post": { "operationId": "create_sandbox_image", "parameters": [ { "description": "external sandbox id (base58 body with optional region tag, or a bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageCaptureReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageListItem" } } }, "description": "Filesystem capture accepted; image row queued on the sandbox's runner" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid idle semantics or reserved image name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:images`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found in the caller's project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not running/placed, or duplicate image name" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:images" ] }, { "platform_token": [ "write:images" ] } ], "tags": [ "images" ] } }, "/sandboxes/{id}/labels": { "put": { "operationId": "set_sandbox_labels", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetVmLabelsReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmLabelsResp" } } }, "description": "Labels replaced" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many labels, or a key/value over the 512-byte cap" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or not a linux sandbox \u2014 class routes own their labels)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "PUT /sandboxes/:id/labels \u2014 replace a linux sandbox's labels (migration 0053).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/lifecycle": { "patch": { "description": "PROJECT-KEY ONLY, unlike delete/stop/pause: the wall-clock deadline is a\nsafety knob the sandbox itself must not be able to disable, so a per-VM\n`dtnv_` token has no route here (same reasoning that keeps start/resume off\nthe self-service plane).\n\nA body that sets `on_timeout` or `on_idle_timeout` to `delete` \u2014 or\ntouches any field of a pair whose stored or resulting action is `delete`,\nclearing and switching away included \u2014 additionally requires\n`delete:sandboxes`: scheduling, re-anchoring, or disarming the destruction\nof an existing sandbox delegates the delete capability (issue #651,\nPLAN-LIFECYCLE-TIMEOUTS.md Decision 9).", "operationId": "set_sandbox_lifecycle", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifecycleReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmLifecycleResp" } } }, "description": "Lifecycle policy updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A malformed body (unknown field, wrong value type, non-JSON content type, or unparseable JSON), an out-of-range duration (`timeout_secs` cannot be disabled and must be `1..=` the effective max; `idle_timeout_secs` takes `-1` to clear, never `0`), an action this class or persistence mode does not support, an action supplied without its interval stored or supplied, or an idle pair armed without its action" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks a required project permission \u2014 `write:sandboxes`, or `delete:sandboxes` when the body sets an action to `delete` or touches a pair whose stored or resulting action is `delete`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "PATCH /sandboxes/{id}/lifecycle \u2014 replace a sandbox's lifecycle policy\n(PLAN-LIFECYCLE-TIMEOUTS.md). Class-blind: one route for every class, the\npolicy is validated against the row's own class (a windows or gpu sandbox\nstill refuses the knobs its class lacks with a 400, never a 404).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/logs": { "get": { "operationId": "sandbox_logs", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Serial console log (live for a running sandbox, the persisted terminal log otherwise)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found, or the sandbox was never placed on a runner" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning runner unreachable" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /sandboxes/:id/logs \u2014 serial log served by the owning runner\n(PLAN-JETSTREAM-CRITICAL-ONLY Phase 2). For a RUNNING VM the runner returns\nthe live serial console; for a terminal VM (stopped/failed/lost) the runner\nfalls back to its local terminal-log store. Logs no longer transit the\nOBJ_vmlogs JetStream bucket. A terminal VM whose runner host is gone (no\nrunner_id, or an unreachable runner) has no retrievable log \u2192 NotFound.", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/network-policy": { "get": { "operationId": "get_vm_network_policy", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyResponse" } } }, "description": "Desired vs applied network policy state" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Unsupported class/backend. The shared NetworkPolicyInput schema also documents that allow_domains with explicit block_all=false is rejected as network_policy_domains_require_block_all." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks read:sandboxes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "tags": [ "sandboxes" ] }, "put": { "operationId": "put_vm_network_policy", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkPolicyInput" } ] } } }, "description": "Full replacement. Send a JSON object to set policy, or literal null to reset to open while preserving revision history. Empty body is invalid. With a non-null allow_domains, explicit block_all=false is rejected as network_policy_domains_require_block_all and an omitted/null block_all normalizes to true." }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkPolicyResponse" } } }, "description": "Desired policy stored with durable dispatch intent" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid body or unsupported class/backend. allow_domains with explicit block_all=false is rejected as network_policy_domains_require_block_all." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks write:sandboxes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Provisioning transition in progress" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Stale desired revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing If-Match header" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Admission disabled or no capable runner pool" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/pause": { "post": { "operationId": "pause_sandbox", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmActionResp" } } }, "description": "Pause initiated (`status: pausing`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or a per-VM token targeting a sibling sandbox)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not persistent, not running, has disk volumes attached, a class that cannot pause (windows, gpu), or a macOS sandbox that owes a checkpoint (`checkpoint_pending`): its lease is ending, or it was stopped and its checkpoint is still uploading" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "vm_token": [] }, { "sandbox_token": [] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/pause \u2014 memory-preserving pause of a persistent linux\nsandbox (PLAN-PAUSE-RESUME.md), or of a running persistent macOS sandbox,\nwhose Mac saves the guest's memory to disk; a paused macOS sandbox keeps its\nMac slot but does not keep an auto-renewing lease renewing\n(PLAN-MACOS-LIFECYCLE.md).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/ports/{port}/preview-url": { "get": { "description": "**Semantic bridge** (ported from the Daytona facade): the upstream contract\nis \"any listening port can be previewed\" with no registration step; ours is\nopt-in per `(vm_id, port)` and fail-closed. This route honours the former\nwithout weakening the latter \u2014 the port becomes previewable, but only to a\ncaller presenting the token. It never silently makes a port public.", "operationId": "preview_url", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "in-VM TCP port (1..65535)", "in": "path", "name": "port", "required": true, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewUrlResp" } } }, "description": "Preview URL + access token (endpoint auto-registered as private if new)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Port out of range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the credential's user is no longer a member of the organization or cannot enter the project" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found (or owned by another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Preview tokens are not configured on this deployment" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "GET /sandboxes/:id/ports/:port/preview-url \u2014 preview URL + access token for one\nin-VM port, auto-registering the endpoint as PRIVATE on first request.", "tags": [ "previews" ] } }, "/sandboxes/{id}/ports/{port}/signed-preview-url": { "get": { "description": "Every call mints a NEW token (Daytona semantics: links are per-recipient so\nthey revoke independently). Like the stateless preview-url route, minting\nauto-registers the `(vm_id, port)` endpoint as PRIVATE (idempotent \u2014 the\nsigned link does not bypass the endpoint opt-in, plan D3), and the URL is\nbuilt against the VM's REGION preview domain. write:sandboxes for the same\nreason as preview_url: this mutates AND hands out a data-plane credential.", "operationId": "signed_preview_url", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "in-VM TCP port (1..65535)", "in": "path", "name": "port", "required": true, "schema": { "format": "int32", "type": "integer" } }, { "description": "Link lifetime in seconds (default 60; 400 outside\n`1..=deployment-configured limit`, default 7 days).", "in": "query", "name": "expires_in_secs", "required": false, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedPreviewUrlResp" } } }, "description": "Signed preview URL (endpoint auto-registered as private if new)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Port or expires_in_secs out of range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the credential's user is no longer a member of the organization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found (or owned by another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Signed preview links are not configured on this deployment or the token could not be stored" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "GET /sandboxes/:id/ports/:port/signed-preview-url \u2014 mint a short-lived (default\n60 s), single-port, individually revocable preview link.", "tags": [ "previews" ] } }, "/sandboxes/{id}/ports/{port}/signed-preview-url/{token}/expire": { "post": { "description": "Idempotent by design: 204 on a real revocation AND on any no-match \u2014\nunknown/already-expired token, or a token that belongs to a different\n(vm_id, port) than the authenticated route (not yours to expire, treated as\nno-match rather than disclosed). 404 only for the sandbox-ownership\nfailure. The `:token` path param is the plaintext credential \u2014 never logged\n(spans record the matched route template, not the raw path).", "operationId": "expire_signed_preview_url", "parameters": [ { "description": "sandbox id (region-tagged external id or bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "in-VM TCP port the link was minted for", "in": "path", "name": "port", "required": true, "schema": { "format": "int32", "type": "integer" } }, { "description": "the plaintext signed token to revoke", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Link revoked (or was already gone / not a match \u2014 idempotent)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found (or owned by another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Signed preview links are not configured on this deployment or the revocation could not be confirmed" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/ports/:port/signed-preview-url/:token/expire \u2014 revoke one\nsigned link before its natural expiry (Daytona-parity).", "tags": [ "previews" ] } }, "/sandboxes/{id}/reset-idle-timer": { "post": { "operationId": "reset_sandbox_idle_timer", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmLifecycleResp" } } }, "description": "Idle timer reset (advance-only; the echoed lifecycle is the post-reset state, with `idle_timeout_at` re-anchored and `timeout_at` unchanged)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks a required project permission \u2014 `write:sandboxes`, or `delete:sandboxes` when the stored `on_idle_timeout` action is `delete` (resetting re-anchors, or arms, a deletion countdown \u2014 Decision 9)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/{id}/reset-idle-timer \u2014 explicit out-of-band keepalive\n(PLAN-LIFECYCLE-TIMEOUTS.md \u00a7 Manual idle-timer reset): restart the idle\ncountdown as if the sandbox had just been used, attributed as activity\nsource `api`. The wall-clock `timeout_at` is untouched. Class-blind like\nthe lifecycle PATCH. PROJECT-KEY ONLY, also like the PATCH: a sandbox must\nnot be able to keep ITSELF alive from inside, so the per-VM `dtnv_` token\nhas no route here.", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/resume": { "post": { "operationId": "resume_sandbox", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmJobResp" } } }, "description": "Resume enqueued (`status: assigned`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning org is suspended (`ORG_SUSPENDED`), or the project reached its monthly budget (`PROJECT_BUDGET_EXCEEDED`). Never for a macOS sandbox, which resumes inside its paid Mac lease" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not paused, the paused sandbox has no memory artifact (use start), a class that cannot resume (windows, gpu), or a macOS sandbox whose lease is ending (`no_active_reservation`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization concurrent-sandbox limit reached (`limit_exceeded`, PLAN-ORG-LIMITS; body carries `limit`/`current`/`max` and deliberately NO `Retry-After`) \u2014 or the org's admission queue is saturated (`overloaded`, with `Retry-After`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No runner in the sandbox's region can accept this resume right now (generic `SERVICE_UNAVAILABLE`, with `Retry-After: 10`, one runner heartbeat; PLAN-FAIL-FAST-ADMISSION). Nothing was written and the sandbox is still paused; retry." } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/resume \u2014 restore a paused persistent linux sandbox's memory +\ndevice so processes continue (PLAN-PAUSE-RESUME.md). A paused macOS sandbox\nresumes on the Mac that holds its saved memory; `mac_boot_mode` then tells\nwhether the memory was restored (`restored`) or the Mac booted the disk\n(`cold_after_restore_failure`) (PLAN-MACOS-LIFECYCLE.md).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/signing-key/rotate": { "post": { "operationId": "rotate_sandbox_signing_key", "parameters": [ { "description": "External sandbox id (base58 UUID with `-` suffix; bare UUIDs accepted)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyRotatedResp" } } }, "description": "The signing key was rotated; outstanding links stop verifying within the proxies' key-cache TTL" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or the credential's user is no longer a member of the organization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or a sandbox that cannot carry a signing key)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/{id}/signing-key/rotate \u2014 retire every outstanding\npre-signed link on a sandbox at once (PLAN-SIGNED-FILE-URLS.md \u00a73). The new\nkey never leaves the server; the next `POST \u2026/files/sign` signs with it.", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/snapshots": { "post": { "operationId": "create_sandbox_snapshot", "parameters": [ { "description": "external VM id (base58 body with optional region tag, or a bare UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotResp" } } }, "description": "Snapshot accepted; capture job queued on the VM's runner" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Class unsupported for memory snapshots" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:snapshots`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not found in the caller's project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sandbox not running/placed, or duplicate snapshot name" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:snapshots" ] }, { "platform_token": [ "write:snapshots" ] } ], "tags": [ "snapshots" ] } }, "/sandboxes/{id}/start": { "post": { "operationId": "start_sandbox", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmJobResp" } } }, "description": "Warm start enqueued" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "macOS: auto-reserve's lease purchase was refused \u2014 organization suspended (`org_suspended`), balance too low (`insufficient_balance`), or billing rejected the charge (`charge_failed`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`), or, for a macOS sandbox, the organization does not have the `macos_sandboxes` feature flag enabled (`FEATURE_FLAG_DISABLED`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or a class that cannot warm-start)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not a persistent sandbox, not stopped, or no resolved manifest to boot from. macOS: the latest checkpoint is still uploading (`checkpoint_pending`) or failed (`checkpoint_failed`), no committed checkpoint (`no_checkpoint`), no Mac lease (`no_active_reservation`), no free slot (`no_free_slot`), the auto-reserve cap reached (`auto_reserve_limit_reached`), or no unleased Mac to buy (`no_mac_available`); nothing was published" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Organization concurrent-sandbox limit reached (`limit_exceeded`, PLAN-ORG-LIMITS; body carries `limit`/`current`/`max` and deliberately NO `Retry-After`) \u2014 or the org's admission queue is saturated (`overloaded`, with `Retry-After`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No runner in the sandbox's region can accept this warm start right now (generic `SERVICE_UNAVAILABLE`, with `Retry-After: 10`, one runner heartbeat; PLAN-FAIL-FAST-ADMISSION). Nothing was written and the sandbox is still stopped; retry." } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/start \u2014 warm-start a stopped persistent sandbox\n(PLAN-PERSISTENT-SANDBOXES.md \u00a76). A macOS sandbox restores its latest\ncommitted checkpoint on any Mac its organization leases, buying a lease\nunder auto-reserve when none has a free slot (PLAN-MACOS-LIFECYCLE.md).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/stop": { "post": { "description": "Class-blind like DELETE (the daemon self-stop path is hardcoded to this\nURL): stop dispatches per class internally \u2014 a Windows row warm-stops via\nACPI, a non-persistent row of any class 409s exactly as before the split.", "operationId": "stop_sandbox", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmActionResp" } } }, "description": "Warm stop initiated (`status: stopping`)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found (another project, or a per-VM token targeting a sibling sandbox)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not a persistent sandbox, or not in a stoppable state" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "write:sandboxes" ] }, { "vm_token": [] }, { "sandbox_token": [] }, { "platform_token": [ "write:sandboxes" ] } ], "summary": "POST /sandboxes/:id/stop \u2014 warm-stop a persistent sandbox\n(PLAN-PERSISTENT-SANDBOXES.md \u00a76).", "tags": [ "sandboxes" ] } }, "/sandboxes/{id}/usage": { "get": { "operationId": "sandbox_usage", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmUsageResp" } } }, "description": "Live usage snapshot from the owning runner" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found, or not placed on a runner" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owning runner unreachable" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /sandboxes/:id/usage \u2014 live per-sandbox resource usage from the owning runner\n(PLAN-USAGE-TRACKING.md). Resolves the VM's runner and requests\nrunner..usage over NATS (filtered to this vm_id). Mirrors\nrunner_capacity. 404 when the VM is unknown or not placed on a runner.", "tags": [ "usage" ] } }, "/sandboxes/{id}/usage/history": { "get": { "operationId": "sandbox_usage_history", "parameters": [ { "description": "External sandbox id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "RFC3339 window start. Default: 24h before `to`. Unparseable values fall\nback to the default.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 window end (exclusive). Default: now.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "\"m\" (minute periods, default) | \"h\" (hourly).", "in": "query", "name": "resolution", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageHistoryResp" } } }, "description": "Usage time series (or `available: false` when the collector DB is not configured)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:sandboxes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "GET /sandboxes/:id/usage/history \u2014 per-sandbox usage time series for the details\nsheet. Ownership is enforced (the vm must belong to the caller's project);\ndata comes from the collector's `usage_periods` (minute) or `usage_hourly`.", "tags": [ "usage" ] } }, "/secrets": { "get": { "operationId": "list_secrets", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSecretsResp" } } }, "description": "The project's secrets (metadata only \u2014 never values)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:secrets`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:secrets" ] }, { "platform_token": [ "read:secrets" ] } ], "summary": "List the project's secrets \u2014 metadata only. Secret values are write-only\nand never returned by any endpoint.", "tags": [ "secrets" ] } }, "/secrets/{name}": { "delete": { "operationId": "delete_secret", "parameters": [ { "description": "secret name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Secret deleted (or did not exist \u2014 idempotent)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`delete:secrets`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "delete:secrets" ] }, { "platform_token": [ "delete:secrets" ] } ], "summary": "Delete a secret (idempotent). Running VMs that reference it keep their\ninjected value until teardown.", "tags": [ "secrets" ] }, "get": { "operationId": "get_secret", "parameters": [ { "description": "secret name", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretMeta" } } }, "description": "Secret metadata (never the value)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:secrets`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No secret with this name in the project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:secrets" ] }, { "platform_token": [ "read:secrets" ] } ], "summary": "One secret's metadata. The value is write-only and never returned.", "tags": [ "secrets" ] }, "put": { "operationId": "put_secret", "parameters": [ { "description": "secret name \u2014 doubles as the injected env var name ([A-Za-z_][A-Za-z0-9_]*)", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSecretReq" } } }, "required": true }, "responses": { "204": { "description": "Secret stored (created or updated)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid name, missing or empty allowed_domains, [\"*\"] combined with other entries, an invalid allowed_domains entry or an over-broad wildcard, more than 50 allowed_domains entries, description > 1 KiB, or value > 64 KiB" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`write:secrets`)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`if_not_exists` was set and a secret with this name already exists, a plain upsert lost a concurrent-create race (retry), or the project already has the maximum of 500 secrets" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Secrets master key not configured \u2014 writes fail closed" } }, "security": [ { "api_key": [ "write:secrets" ] }, { "platform_token": [ "write:secrets" ] } ], "summary": "Create or update a secret's value + metadata. The value is write-only: it\ncan only be (re)written here, never read back.", "tags": [ "secrets" ] } }, "/service-accounts/{sa_id}": { "delete": { "description": "Archive one service account and revoke every project API key it owns. The caller must be a seated member holding `delete:service_accounts`; the route also enforces authority over the account's current permissions. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_archive_service_account", "parameters": [ { "description": "Service account id", "in": "path", "name": "sa_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchivedServiceAccountResponse" } } }, "description": "Archived service account" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `delete:service_accounts`, or lacked authority over the account" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Service account not found, organization not found, or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "DELETE /service-accounts/:sa_id \u2014 `delete:service_accounts`. A SOFT delete\nthat cascade-revokes: `archived_at` is set, every live key the account owns\nis revoked in the same transaction, and each eviction is published\npost-commit. There is no un-archive (D9) \u2014 only each token's hash is stored,\nso restoring the principal would restore no working credential.", "tags": [ "service-accounts" ] }, "get": { "description": "Read one service account. The caller must be a seated member holding `read:service_accounts` in the owning organization. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_get_service_account", "parameters": [ { "description": "Service account id", "in": "path", "name": "sa_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountResponse" } } }, "description": "Service account" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `read:service_accounts`" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Service account not found, organization not found, or caller is not a member" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "GET /service-accounts/:sa_id \u2014 `read:service_accounts`.", "tags": [ "service-accounts" ] }, "patch": { "description": "Update one service account. The caller must be a seated member holding `write:service_accounts`; the route also enforces grant-within-caller and authority-over-account checks, and revokes out-of-scope project keys when roles narrow. Only an OIDC user JWT is admitted on this route; `dtno_` organization API keys are not.", "operationId": "mgmt_update_service_account", "parameters": [ { "description": "Service account id", "in": "path", "name": "sa_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceAccountReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountUpdateResponse" } } }, "description": "Updated service account, or a dry-run preview when `dry_run` is true" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing or invalid OIDC user JWT" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Caller is a member but lacks `write:service_accounts`, or the requested change exceeded caller authority" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Service account not found, organization not found, or caller is not a member" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Service account was archived or the name already existed" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no management plane (workload cell); the body names the home/central API to call (`MANAGEMENT_PLANE_ELSEWHERE`)" } }, "security": [ { "user_jwt": [] } ], "summary": "PATCH /service-accounts/:sa_id \u2014 `write:service_accounts`. `roles` REPLACES\nwholesale rather than merging, exactly as a member's PATCH does, and a\nreplacement that narrows runs the cascade below.", "tags": [ "service-accounts" ] } }, "/snapshots": { "get": { "operationId": "list_snapshots", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSnapshotsResp" } } }, "description": "One page of the project's snapshots" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed cursor" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:snapshots`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:snapshots" ] }, { "platform_token": [ "read:snapshots" ] } ], "summary": "GET /snapshots \u2014 cursor-paginated list of snapshots.", "tags": [ "snapshots" ] } }, "/snapshots/{id}": { "delete": { "operationId": "delete_snapshot", "parameters": [ { "description": "snapshot id (`snap_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSnapshotResp" } } }, "description": "Snapshot deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`delete:snapshots`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Snapshot not found in the caller's project" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A non-deleted sandbox still references this snapshot" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "delete:snapshots" ] }, { "platform_token": [ "delete:snapshots" ] } ], "tags": [ "snapshots" ] }, "get": { "operationId": "get_snapshot", "parameters": [ { "description": "Block until the snapshot reaches this status (`ready`) or a terminal\nstate. Absent = return immediately.", "in": "query", "name": "wait", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "timeout_ms", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "snapshot id (`snap_\u2026`; bare UUID also accepted during the transition)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotRow" } } }, "description": "The snapshot" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:snapshots`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Snapshot not found in the caller's project" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:snapshots" ] }, { "platform_token": [ "read:snapshots" ] } ], "summary": "GET /snapshots/:id \u2014 one snapshot, optional long-poll via ?wait=ready.", "tags": [ "snapshots" ] } }, "/usage/budget": { "get": { "description": "Read the monthly spend budget of the API key's project and its current state. On a workload cell the budget is read from the central control plane and cached briefly, so the response can lag a change made through the management routes by up to the call-through cache TTL (30 seconds by default).", "operationId": "usage_budget", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectBudget" } } }, "description": "The monthly spend budget of the API key's project" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:spending`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The project has no budget" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Central control plane unreachable (workload-cell call-through)" } }, "security": [ { "api_key": [ "read:spending" ] }, { "platform_token": [ "read:spending" ] } ], "summary": "GET /usage/budget \u2014 the key's project budget, for the SDKs.", "tags": [ "usage" ] } }, "/usage/report": { "get": { "operationId": "usage_report", "parameters": [ { "description": "RFC3339 lower bound (inclusive). Default: end - 1 day.", "in": "query", "name": "start", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 upper bound (exclusive). Default: now.", "in": "query", "name": "end", "required": false, "schema": { "type": "string" } }, { "description": "\"h\" (hourly, default) | \"d\" (daily).", "in": "query", "name": "resolution", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReport" } } }, "description": "Usage aggregates for the caller's project (`available: false` when no usage DB is configured)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:spending`, or the grandfathered `read:sandboxes`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:spending" ] }, { "api_key": [ "read:sandboxes" ] }, { "platform_token": [ "read:spending" ] }, { "platform_token": [ "read:sandboxes" ] } ], "summary": "Project-scoped Modal-style usage report. Aggregates the collector's\n`usage_hourly` for THIS project's sandboxes only.", "tags": [ "usage" ] } }, "/volumes": { "get": { "operationId": "list_volumes", "parameters": [ { "description": "Include retired (`deleted`) volumes in the listing.", "in": "query", "name": "include_deleted", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVolumesResp" } } }, "description": "Volumes in the project" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:volumes`)" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:volumes" ] }, { "platform_token": [ "read:volumes" ] } ], "summary": "GET /volumes \u2014 list volumes for the project (no CAS read-through).", "tags": [ "volumes" ] }, "post": { "operationId": "create_volume", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVolumeReq" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeDto" } } }, "description": "Volume created (ready immediately)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid name, type, size, or bucket options \u2014 including a credential secret whose `allowed_domains` does not admit the host the bucket's requests are signed for" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks a required project permission \u2014 `write:volumes`, or `read:secrets` when the body names project secrets as external bucket credentials" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A volume with that name already exists" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`bucket_create_failed`: the platform bucket could not be created" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Platform bucket volumes are not configured on this deployment" } }, "security": [ { "api_key": [ "write:volumes" ] }, { "platform_token": [ "write:volumes" ] } ], "summary": "POST /volumes \u2014 create a volume (ready immediately). A `bucket` volume with\nno `bucket` block gets a freshly created, rlp-owned bucket.", "tags": [ "volumes" ] } }, "/volumes/{id}": { "delete": { "operationId": "delete_volume", "parameters": [ { "description": "Volume id or name", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Resolve the path strictly as a UUID, without a name fallback.", "in": "query", "name": "id_only", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVolumeResp" } } }, "description": "Deletion complete" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVolumeResp" } } }, "description": "Deletion accepted; writers are being fenced" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Ref matches both a volume id and a different volume's name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`delete:volumes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Volume is attached to a live sandbox, or `bucket_not_empty`" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`bucket_delete_failed`: the platform bucket could not be deleted" } }, "security": [ { "api_key": [ "delete:volumes" ] }, { "platform_token": [ "delete:volumes" ] } ], "summary": "DELETE /volumes/:id", "tags": [ "volumes" ] }, "get": { "operationId": "get_volume", "parameters": [ { "description": "Volume id or name", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Resolve the path strictly as a UUID, without a name fallback.", "in": "query", "name": "id_only", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeDto" } } }, "description": "Volume detail (CAS fields best-effort)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Ref matches both a volume id and a different volume's name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Missing/invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "API key lacks the required project permission (`read:volumes`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Not found" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This cell serves no fleet (central); the body names the workload API to call (`WORKLOAD_PLANE_ELSEWHERE`)" } }, "security": [ { "api_key": [ "read:volumes" ] }, { "platform_token": [ "read:volumes" ] } ], "summary": "GET /volumes/:id_or_name \u2014 detail, enriched best-effort from the CAS store.", "tags": [ "volumes" ] } } }, "servers": [ { "description": "this deployment", "url": "/" } ], "tags": [ { "description": "Sandbox (micro-VM) lifecycle: create, list, inspect, start/stop/pause/resume/fork/delete, logs, runtime mounts, and network-policy desired/applied state.", "name": "sandboxes" }, { "description": "Image build + registry-ref resolution, list, and the shared artifact cache.", "name": "images" }, { "description": "Moving an organization from Daytona v1: what came over for the caller's organization, its v1 sandboxes, and importing an archived one as a persistent sandbox in the default project.", "name": "migration" }, { "description": "Sandbox snapshots: capture, list, delete; create-from-snapshot.", "name": "snapshots" }, { "description": "Persistent disk volumes and S3 bucket volumes (PLAN-VOLUMES.md, PLAN-VOLUME-TYPES.md).", "name": "volumes" }, { "description": "Project-scoped secrets. Values are write-only \u2014 never returned by any endpoint.", "name": "secrets" }, { "description": "Project-scoped private container registries. Passwords are write-only.", "name": "registries" }, { "description": "HTTP preview endpoints exposing a sandbox's in-VM ports through the proxy.", "name": "previews" }, { "description": "Region catalog for SDK target discovery (read-only).", "name": "regions" }, { "description": "Hardware catalogs: CPU types, network classes, disk classes (read-only).", "name": "catalog" }, { "description": "Async job status reads.", "name": "jobs" }, { "description": "Runner fleet reads available to project keys.", "name": "runners" }, { "description": "Project-scoped usage reports.", "name": "usage" }, { "description": "Identity of the signed-in management-plane user.", "name": "me" }, { "description": "Organization lifecycle and org-scoped reads.", "name": "organizations" }, { "description": "Project lifecycle, membership reach, and project-scoped management reads.", "name": "projects" }, { "description": "Organization and project membership plus feature-flag reads.", "name": "members" }, { "description": "Organization invitations: create (which emails the invitee a single-use link when SMTP is configured), list, revoke, and the token-authorized lookup, accept and decline.", "name": "invitations" }, { "description": "Fixed role catalog and permission metadata.", "name": "roles" }, { "description": "Project and organization API-key mint/list/read/revoke surfaces, and introspection of the project key presented on a workload request.", "name": "api-keys" }, { "description": "Non-human principals and their project reach.", "name": "service-accounts" }, { "description": "Organization billing, wallet, invoice, and payment proxy routes.", "name": "billing" }, { "description": "Organization audit-log queries and capture configuration, and the supported action \u00d7 target-type matrix.", "name": "audit" }, { "description": "Platform-operator routes under `/manage/*`: runner operations, cell-local routing/layer introspection, and global/macro region management from whichever deployment mounts the management plane (Home in a fused deployment, Central in a split deployment). Workload cells forward the management-owned subset there.", "name": "admin" }, { "description": "Health and readiness probes.", "name": "system" }, { "description": "Token exchange: trade a signed-in user's OIDC session for a short-lived project-scoped platform token (RFC 8693).", "name": "auth" } ], "x-daytona-error-codes": { "AUTO_RESERVE_LIMIT_REACHED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "BAD_RANGE": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "BAD_RESOLUTION": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "BAD_RUNNER": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "BILLING_DISABLED": { "extras": [], "source": "DAYTONA_API", "status": 501 }, "BILLING_ERROR": { "extras": [], "source": "DAYTONA_API", "status": 502 }, "BILLING_FORBIDDEN": { "extras": [], "source": "DAYTONA_API", "status": 502 }, "BILLING_UNREACHABLE": { "extras": [], "source": "DAYTONA_API", "status": 502 }, "BUCKET_CREATE_FAILED": { "extras": [], "source": "DAYTONA_API", "status": 502 }, "BUCKET_DELETE_FAILED": { "extras": [], "source": "DAYTONA_API", "status": 502 }, "BUCKET_NOT_EMPTY": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "BUILD_LOG_BATCH_TOO_LARGE": { "extras": [], "source": "DAYTONA_API", "status": 413 }, "CHARGE_FAILED": { "extras": [], "source": "DAYTONA_API", "status": 402 }, "CHECKPOINT_FAILED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "CHECKPOINT_PENDING": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "CREATE_BODY_TOO_LARGE": { "extras": [], "source": "DAYTONA_API", "status": 413 }, "CREATE_OPERATION_RETIRED": { "extras": [], "source": "DAYTONA_API", "status": 410 }, "CREATE_TTL_OUT_OF_RANGE": { "extras": [ "max" ], "source": "DAYTONA_API", "status": 400 }, "CROSS_CELL_PLACEMENT_UNSUPPORTED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "DEFAULT_IMAGE_NOT_CONFIGURED": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "ECR_ACCOUNT_MISMATCH": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "ECR_CREDENTIALS_INVALID": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "ECR_OWNERSHIP_UNVERIFIABLE": { "extras": [], "source": "DAYTONA_API", "status": 502 }, "EMAIL_ACCESS_DENIED": { "extras": [], "source": "DAYTONA_API", "status": 403 }, "ENTITLEMENT_REQUIRED": { "extras": [ "entitlement" ], "source": "DAYTONA_API", "status": 403 }, "FEATURE_FLAG_DISABLED": { "extras": [ "flag" ], "source": "DAYTONA_API", "status": 403 }, "HARDWARE_REPLY_TOO_LARGE": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "IDEMPOTENCY_KEY_REUSED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "IDENTITY_NOT_FOUND": { "extras": [], "source": "DAYTONA_API", "status": 404 }, "IDLE_OUT_OF_RANGE": { "extras": [ "max" ], "source": "DAYTONA_API", "status": 400 }, "IF_MATCH_REQUIRED": { "extras": [], "source": "DAYTONA_API", "status": 428 }, "IMAGE_BUILD_FAILED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "IMAGE_CLASS_MISMATCH": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "IMAGE_FORMAT_OUTDATED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "IMAGE_NAME_RESERVED": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "IMAGE_NAME_TAKEN": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "IMAGE_NOT_FOUND": { "extras": [], "source": "DAYTONA_API", "status": 404 }, "IMAGE_NOT_READY": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "IMPORTED_KEY_ALWAYS_SYNCED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "INSTANCE_CREATE_FAILED": { "extras": [ "invocation_id" ], "source": "DAYTONA_API", "status": 503 }, "INSTANCE_UNREACHABLE": { "extras": [ "invocation_id" ], "source": "DAYTONA_API", "status": 502 }, "INSUFFICIENT_BALANCE": { "extras": [], "source": "DAYTONA_API", "status": 402 }, "INVALID_FOR_SOURCE": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "INVOCATION_TIMEOUT": { "extras": [ "invocation_id" ], "source": "DAYTONA_API", "status": 504 }, "KEY_SYNC_NOT_APPLICABLE": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "LIMIT_EXCEEDED": { "extras": [ "limit", "current", "max" ], "source": "DAYTONA_API", "status": 429 }, "MANAGEMENT_PLANE_ELSEWHERE": { "extras": [ "central_api_url" ], "source": "DAYTONA_API", "status": 501 }, "NETWORK_POLICY_DOMAINS_REQUIRE_BLOCK_ALL": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "NETWORK_POLICY_TRANSITION_IN_PROGRESS": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "NOT_SUPPORTED_FOR_CLASS": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "NO_ACTIVE_RESERVATION": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "NO_CHECKPOINT": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "NO_FREE_SLOT": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "NO_MAC_AVAILABLE": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "ORG_SUSPENDED": { "extras": [], "source": "DAYTONA_API", "status": 402 }, "ORIGIN_IMPORT_ONLY": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "OVERLOADED": { "extras": [ "retry_after_secs", "invocation_id" ], "source": "DAYTONA_API", "status": 429 }, "PLACEMENT_AUTHORITY_REQUIRED": { "extras": [], "source": "DAYTONA_API", "status": 501 }, "PLACEMENT_CONTEXT_TOO_LARGE": { "extras": [], "source": "DAYTONA_API", "status": 413 }, "PLACEMENT_RECEIPT_TOO_LARGE": { "extras": [], "source": "DAYTONA_API", "status": 413 }, "PLACEMENT_ROUTER_REQUIRED": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "PLACEMENT_UNAVAILABLE": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "PROJECT_BUDGET_EXCEEDED": { "extras": [], "source": "DAYTONA_API", "status": 402 }, "RATE_LIMITED": { "extras": [ "retry_after_secs" ], "source": "DAYTONA_API", "status": 429 }, "READ_ONLY_UNSUPPORTED": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "RESERVATION_NOT_FOUND": { "extras": [], "source": "DAYTONA_API", "status": 404 }, "SEARCH_NOT_CONFIGURED": { "extras": [], "source": "DAYTONA_API", "status": 501 }, "SEARCH_UNAVAILABLE": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "SECRETS_UNSUPPORTED_ON_MACOS": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "SIGNUP_NOT_INVITED": { "extras": [], "source": "DAYTONA_API", "status": 403 }, "SNAPSHOT_CLASS_MISMATCH": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "SNAPSHOT_NOT_FOUND": { "extras": [], "source": "DAYTONA_API", "status": 404 }, "SNAPSHOT_NOT_READY": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "SOURCE_AMBIGUOUS": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "STALE_NETWORK_POLICY_REVISION": { "extras": [], "source": "DAYTONA_API", "status": 412 }, "TOPOLOGY_NOT_READY": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "UNSUPPORTED_VOLUME_TYPE": { "extras": [], "source": "DAYTONA_API", "status": 400 }, "USAGE_UNAVAILABLE": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "V1_BACKUP_REGISTRY_UNCONFIGURED": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "V1_BRIDGE_UNAVAILABLE": { "extras": [], "source": "DAYTONA_API", "status": 503 }, "V1_MIGRATION_DEFAULT_PROJECT_ONLY": { "extras": [], "source": "DAYTONA_API", "status": 403 }, "V1_SANDBOX_NOT_FOUND": { "extras": [], "source": "DAYTONA_API", "status": 404 }, "V1_SANDBOX_NOT_IMPORTABLE": { "extras": [], "source": "DAYTONA_API", "status": 409 }, "WORKLOAD_PLANE_ELSEWHERE": { "extras": [ "workload_api_url" ], "source": "DAYTONA_API", "status": 501 }, "WORKOS_SYNC_DISABLED": { "extras": [], "source": "DAYTONA_API", "status": 402 } }, "x-daytona-generic-codes": { "BAD_GATEWAY": { "extras": [], "status": 502 }, "BAD_REQUEST": { "extras": [], "status": 400 }, "CONFLICT": { "extras": [], "status": 409 }, "FORBIDDEN": { "extras": [], "status": 403 }, "GATEWAY_TIMEOUT": { "extras": [], "status": 504 }, "GONE": { "extras": [ "replacement" ], "status": 410 }, "INTERNAL_SERVER_ERROR": { "extras": [], "status": 500 }, "METHOD_NOT_ALLOWED": { "extras": [], "status": 405 }, "NOT_FOUND": { "extras": [], "status": 404 }, "NOT_IMPLEMENTED": { "extras": [], "status": 501 }, "PAYLOAD_TOO_LARGE": { "extras": [], "status": 413 }, "PAYMENT_REQUIRED": { "extras": [], "status": 402 }, "REQUEST_TIMEOUT": { "extras": [], "status": 408 }, "SERVICE_UNAVAILABLE": { "extras": [], "status": 503 }, "TOO_MANY_REQUESTS": { "extras": [], "status": 429 }, "UNAUTHORIZED": { "extras": [], "status": 401 }, "UNPROCESSABLE_ENTITY": { "extras": [], "status": 422 }, "UNSUPPORTED_MEDIA_TYPE": { "extras": [], "status": 415 } } }