From 77168fcde4f16d50f9bd4212c203873b1b0c7964 Mon Sep 17 00:00:00 2001 From: dobrac <4323173+dobrac@users.noreply.github.com> Date: Sun, 22 Nov 2026 15:22:20 +0000 Subject: [PATCH] chore: sync infra OpenAPI specs --- spec/openapi.infra.yaml | 1072 +++++++++--------- src/core/shared/contracts/infra-api.types.ts | 1047 +++++++++-------- 2 files changed, 1094 insertions(+), 1025 deletions(-) diff --git a/spec/openapi.infra.yaml b/spec/openapi.infra.yaml index 0e54deeaf..6675c9850 100644 --- a/spec/openapi.infra.yaml +++ b/spec/openapi.infra.yaml @@ -265,6 +265,30 @@ components: type: array items: $ref: "#/components/schemas/BuildStatus" + templateBuildStatuses: + name: statuses + in: query + required: false + description: Comma-separated list of build statuses to include. Every status when omitted. + style: form + explode: false + schema: + type: array + uniqueItems: true + items: + $ref: "#/components/schemas/TemplateBuildStatus" + templateBuildTags: + name: tags + in: query + required: false + description: Comma-separated list of tags. Only the builds these tags point at are returned. Every build when omitted. + style: form + explode: false + schema: + type: array + maxItems: 100 + items: + type: string buildsCursor: name: cursor in: query @@ -438,6 +462,39 @@ components: $ref: "#/components/schemas/Error" schemas: + TelemetryNames: + type: object + required: [teams, clusters] + properties: + teams: + type: object + additionalProperties: + $ref: "#/components/schemas/TelemetryTeamName" + clusters: + type: array + items: + $ref: "#/components/schemas/TelemetryClusterName" + TelemetryTeamName: + type: object + required: [name] + properties: + name: + type: string + clusterId: + type: string + format: uuid + TelemetryClusterName: + type: object + required: [id, name] + properties: + id: + type: string + format: uuid + name: + type: string + clientId: + type: string + Rig: description: An orchestrator node pool backed by one cloud scaling group required: @@ -535,26 +592,6 @@ components: type: string description: Action being performed when the error occurred (e.g. CREATING) - Team: - required: - - teamID - - name - - apiKey - - isDefault - properties: - teamID: - type: string - description: Identifier of the team - name: - type: string - description: Name of the team - apiKey: - type: string - description: API key for the team - isDefault: - type: boolean - description: Whether the team is the default team - TeamUser: required: - id @@ -1700,118 +1737,54 @@ components: limits: $ref: "#/components/schemas/TeamLimits" - ClusterDetail: + ClusterTeamListItem: type: object - description: A cluster's configuration. The cluster's token is never returned. required: - id - - name - - endpoint - - endpointTls - - deletionProtection + - email + - isBanned + - createdAt properties: id: type: string format: uuid - name: - type: string - endpoint: + email: type: string - endpointTls: - type: boolean - sandboxProxyDomain: + name: type: string nullable: true - authOrgId: + slug: type: string nullable: true - deletionProtection: + isBanned: type: boolean - description: While true, deleting the cluster is refused. - - ClusterDetailWithTeams: - type: object - required: - - cluster - - teams - - teamCount - - templateCount - properties: - cluster: - $ref: "#/components/schemas/ClusterDetail" - teams: - $ref: "#/components/schemas/ClusterTeamListResponse" - teamCount: - type: integer - format: int64 - description: Teams assigned to the cluster. Must be 0 before the cluster can be deleted. - templateCount: - type: integer - format: int64 - description: Live templates on the cluster. Deleting the cluster deletes them. + createdAt: + type: string + format: date-time - ClusterListItem: + ClusterTeamCount: type: object required: - - id - - name - - endpoint + - clusterId - teamCount properties: - id: + clusterId: type: string format: uuid - name: - type: string - endpoint: - type: string - sandboxProxyDomain: - type: string - nullable: true teamCount: type: integer format: int64 - description: Number of teams assigned to the cluster. + description: Number of live teams assigned to the cluster - ClusterListResponse: + ClusterTeamCountList: type: object required: - items - - total properties: items: type: array items: - $ref: "#/components/schemas/ClusterListItem" - total: - type: integer - format: int64 - description: Number of clusters matching the search, ignoring limit and offset - - ClusterTeamListItem: - type: object - required: - - id - - email - - isBanned - - createdAt - properties: - id: - type: string - format: uuid - email: - type: string - name: - type: string - nullable: true - slug: - type: string - nullable: true - isBanned: - type: boolean - createdAt: - type: string - format: date-time + $ref: "#/components/schemas/ClusterTeamCount" ClusterTeamListResponse: type: object @@ -1828,70 +1801,6 @@ components: format: int64 description: Number of teams assigned to the cluster, ignoring limit and offset - AdminClusterCreateRequest: - type: object - required: - - name - - endpoint - - endpoint_tls - - token - properties: - cluster_id: - type: string - format: uuid - description: Optional stable identifier for idempotent creation. Reuse succeeds only when the immutable configuration is identical. - name: - type: string - minLength: 1 - endpoint: - type: string - minLength: 1 - endpoint_tls: - type: boolean - token: - type: string - minLength: 1 - sandbox_proxy_domain: - type: string - nullable: true - auth_org_id: - type: string - nullable: true - - ClusterUpdateRequest: - type: object - description: >- - Partial update; only the properties present are written. An explicit - null or an empty string clears `sandboxProxyDomain` or `authOrgId`. - properties: - name: - type: string - minLength: 1 - endpoint: - type: string - minLength: 1 - endpointTls: - type: boolean - sandboxProxyDomain: - type: string - nullable: true - authOrgId: - type: string - nullable: true - deletionProtection: - type: boolean - - ClusterTokenRotateRequest: - type: object - required: - - token - properties: - token: - type: string - minLength: 1 - format: password - description: New cluster access token. Write-only. - AdminSandboxKillResult: required: - killedCount @@ -1976,7 +1885,9 @@ components: description: Tag the build is assigned under status: type: string - description: Build status as stored, for example ready, snapshotting or waiting + deprecated: true + x-deprecated-reason: Use statusGroup + description: Same value as statusGroup statusGroup: $ref: "#/components/schemas/AdminSandboxBuildStatusGroup" clusterNodeID: @@ -2185,7 +2096,9 @@ components: description: Tag the build is assigned under status: type: string - description: Build status as stored, for example ready, snapshotting or waiting + deprecated: true + x-deprecated-reason: Use statusGroup + description: Same value as statusGroup statusGroup: allOf: - $ref: "#/components/schemas/AdminSandboxBuildStatusGroup" @@ -2717,7 +2630,16 @@ components: - $ref: "#/components/schemas/CPUCount" description: "Maximum CPU count for resizable templates; absent for fixed-size templates." memoryMB: - $ref: "#/components/schemas/MemoryMB" + allOf: + - $ref: "#/components/schemas/MemoryMB" + description: >- + Memory in MiB a sandbox created from this template starts with: the + build's memory, or for a snapshot template of a grown sandbox the size it + was taken at. A create that names no memoryMB starts at this size. + maxMemoryMB: + allOf: + - $ref: "#/components/schemas/MemoryMB" + description: "Memory the template's sandboxes can grow to, in MiB; absent for templates whose memory cannot grow." diskSizeMB: $ref: "#/components/schemas/DiskSizeMB" public: @@ -3002,12 +2924,101 @@ components: - $ref: "#/components/schemas/CPUCount" description: "Maximum CPU count for resizable templates; absent for fixed-size templates." memoryMB: - $ref: "#/components/schemas/MemoryMB" + allOf: + - $ref: "#/components/schemas/MemoryMB" + description: >- + Memory in MiB a sandbox created from this build starts with: the build's + memory, or for a snapshot of a grown sandbox the size it was taken at. + A create that names no memoryMB starts at this size. + maxMemoryMB: + allOf: + - $ref: "#/components/schemas/MemoryMB" + description: "Memory the template's sandboxes can grow to, in MiB; absent for templates whose memory cannot grow." diskSizeMB: $ref: "#/components/schemas/DiskSizeMB" envdVersion: $ref: "#/components/schemas/EnvdVersion" + TemplateBuildWithTags: + allOf: + - $ref: "#/components/schemas/TemplateBuild" + - type: object + required: + - tags + properties: + tags: + type: array + description: Tags of the template that point at this build. A tag points at the latest ready build it was assigned to, the build a sandbox created with that tag starts from. + items: + type: string + + TemplateV2: + description: > + A template with its default build. `defaultBuild` is the build a sandbox created + without a tag starts from, the latest ready build tagged default; it is absent until + such a build is ready. `buildStatus` is the status of the latest build tagged default + in any state: it is `building` while a rebuild runs, although sandboxes still start + from the default build. + required: + - templateID + - names + - public + - createdAt + - updatedAt + - createdBy + - lastSpawnedAt + - spawnCount + - buildCount + - isDefault + - buildStatus + properties: + templateID: + type: string + description: Identifier of the template + names: + type: array + description: Names of the template (namespace/alias format when namespaced) + items: + type: string + public: + type: boolean + description: Whether the template is public or only accessible by the team + createdAt: + type: string + format: date-time + description: Time when the template was created + updatedAt: + type: string + format: date-time + description: Time when the template was last updated + createdBy: + allOf: + - $ref: "#/components/schemas/TeamUser" + nullable: true + lastSpawnedAt: + type: string + nullable: true + format: date-time + description: Time when the template was last used + spawnCount: + type: integer + format: int64 + description: Number of times the template was used + buildCount: + type: integer + format: int32 + description: Number of times the template was built + isDefault: + type: boolean + description: Whether the template is one of the platform's default templates + description: + type: string + description: Description of the template + buildStatus: + $ref: "#/components/schemas/TemplateBuildStatus" + defaultBuild: + $ref: "#/components/schemas/TemplateBuild" + TemplateWithBuilds: allOf: - $ref: "#/components/schemas/Template" @@ -3084,6 +3095,13 @@ components: description: "Maximum CPU count the template's sandboxes can be resized to; makes the template resizable. Must be at least cpuCount." memoryMB: $ref: "#/components/schemas/MemoryMB" + maxMemoryMB: + allOf: + - $ref: "#/components/schemas/MemoryMB" + description: >- + Memory the template's sandboxes can grow to, in MiB. memoryMB is + what they boot with; the rest is added when a sandbox asks for it. + Must be at least memoryMB, and the difference a multiple of 128 MiB. minFreeDiskMb: $ref: "#/components/schemas/MinFreeDiskMb" @@ -3115,6 +3133,7 @@ components: type: string description: AWS Access Key ID for ECR authentication awsSecretAccessKey: + format: password type: string description: AWS Secret Access Key for ECR authentication awsRegion: @@ -3132,6 +3151,7 @@ components: enum: [gcp] description: Type of registry authentication serviceAccountJson: + format: password type: string description: Service Account JSON for GCP authentication @@ -3150,6 +3170,7 @@ components: type: string description: Username to use for the registry password: + format: password type: string description: Password to use for the registry @@ -3567,6 +3588,8 @@ components: - teamID - sandboxID - executionID + - networkMode + - volumesAttached properties: teamID: type: string @@ -3583,6 +3606,12 @@ components: type: string format: date-time description: Deadline of the operation holding the sandbox's lifecycle, absent when it is not held + networkMode: + type: string + description: Network the execution runs on, legacy, egress-router or full-router + volumesAttached: + type: boolean + description: Whether the sandbox runs with managed volumes attached NodeDetail: required: @@ -3921,10 +3950,7 @@ components: count out of bounds in the stored build; a server error, since no request field reaches that check), internal_server_error, secret_limit_reached, idempotency_request_mismatch, idempotency_in_progress, - idempotency_outcome_unknown, cluster_registration_invalid, - cluster_registration_conflict, cluster_assignment_invalid, - cluster_assignment_project_not_found, cluster_assignment_cluster_not_found, - cluster_assignment_already_assigned, cluster_assignment_cluster_deleting, + idempotency_outcome_unknown, sandbox_snapshot_guest_agent_unresponsive (a plain resume of a snapshot taken while the sandbox guest agent was not responding; resume it with memory: false). @@ -4058,6 +4084,7 @@ components: lower-cased before storage and returned in that canonical form; the sec_ prefix is reserved for secret identifiers. value: + format: password type: string description: Runtime marker stored as the secret's first version. The runtime resolves it to a value at sandbox egress. metadata: @@ -4069,6 +4096,7 @@ components: - value properties: value: + format: password type: string description: Runtime marker stored as the secret's new version. The runtime resolves it to a value at sandbox egress. metadata: @@ -4155,6 +4183,7 @@ components: type: boolean default: true signatureSecret: + format: password type: string description: Secret used to sign the webhook payloads WebhookCreation: @@ -4239,6 +4268,7 @@ components: items: type: string signatureSecret: + format: password type: string description: Secret used to sign the webhook payloads WebhookDelivery: @@ -4419,33 +4449,7 @@ components: type: string nullable: true description: Cursor to pass to the next list request, or null when there is no next page. - ManagementClusterRegistrationRequest: - type: object - required: - - name - - endpoint - - endpoint_tls - - token - properties: - name: - type: string - minLength: 1 - endpoint: - type: string - minLength: 1 - endpoint_tls: - type: boolean - token: - type: string - minLength: 1 - sandbox_proxy_domain: - type: string - nullable: true - auth_org_id: - type: string - nullable: true - - ManagementClusterProjects: + ManagementClusterProjects: type: object required: [project_ids] properties: @@ -4491,8 +4495,7 @@ components: type: object description: >- The properties of a project this side stores. Name, slug and email are - synchronized on every push. The optional cluster assignment is preserved - when omitted. + synchronized on every accepted push. The cluster is fixed at creation. A project's tier is not among them, and this side assigns none. Limits @@ -4502,7 +4505,10 @@ components: cluster_id: type: string format: uuid - description: Cluster assignment to synchronize. Omission preserves the existing assignment. + description: >- + Remote cluster fixed at creation. Omit to create a local project or to preserve an + existing project's cluster. A different cluster returns 409. The response reports + the stored cluster; local projects omit it. name: type: string minLength: 1 @@ -4560,6 +4566,10 @@ components: type: boolean default: false description: Whether this membership is the user's default team. Omitted requests from older sources remain non-default. + role: + type: string + enum: [owner, member, viewer] + description: The member's effective role on the project. A viewer may only read. An omitted role keeps the stored one, and a new member without one is stored as member. identities: type: array maxItems: 16 @@ -4777,29 +4787,6 @@ paths: schema: type: string - /teams: - get: - summary: List teams - description: List all teams - tags: [auth] - security: - - AuthProviderBearerAuth: [] - responses: - "200": - description: Successfully returned all teams - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Team" - "401": - $ref: "#/components/responses/401" - "429": - $ref: "#/components/responses/429" - "500": - $ref: "#/components/responses/500" - /teams/{teamID}/metrics: get: summary: Team metrics @@ -6584,6 +6571,51 @@ paths: "500": $ref: "#/components/responses/500" + /templates/{templateID}/builds: + get: + summary: List a template's builds + x-api-group: list + description: List the builds of a template, newest first. The template is given by its ID or name. A template named `aliases` is given by its ID or by its name with the team prefix. + tags: [templates] + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + - AdminJWTAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + - $ref: "#/components/parameters/paginationNextToken" + - $ref: "#/components/parameters/paginationLimit" + - $ref: "#/components/parameters/templateBuildStatuses" + - $ref: "#/components/parameters/templateBuildTags" + responses: + "200": + description: Successfully returned the template builds + headers: + X-Next-Token: + $ref: "#/components/headers/XNextToken" + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TemplateBuildWithTags" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "403": + $ref: "#/components/responses/403" + "404": + $ref: "#/components/responses/404" + "429": + $ref: "#/components/responses/429" + "500": + $ref: "#/components/responses/500" + /v2/templates/{templateID}/builds/{buildID}: post: summary: Start template build (v2) @@ -6686,6 +6718,40 @@ paths: $ref: "#/components/schemas/Error" /v2/templates/{templateID}: + get: + summary: Template info (v2) + x-api-group: list + description: Get a template by its ID or name, with its default build and without its other builds. + tags: [templates] + security: + - ApiKeyAuth: [] + - AuthProviderBearerAuth: [] + AuthProviderTeamAuth: [] + - AdminApiKeyAuth: [] + AdminTeamAuth: [] + - AdminJWTAuth: [] + AdminTeamAuth: [] + parameters: + - $ref: "#/components/parameters/templateID" + responses: + "200": + description: Successfully returned the template + content: + application/json: + schema: + $ref: "#/components/schemas/TemplateV2" + "400": + $ref: "#/components/responses/400" + "401": + $ref: "#/components/responses/401" + "403": + $ref: "#/components/responses/403" + "404": + $ref: "#/components/responses/404" + "429": + $ref: "#/components/responses/429" + "500": + $ref: "#/components/responses/500" patch: summary: Update template (v2) description: Update template @@ -6839,7 +6905,9 @@ paths: /templates/tags: post: summary: Assign template tags - description: Assign tag(s) to a template build + description: Assign tag(s) to a template build. + parameters: + - $ref: "#/components/parameters/idempotencyKey" tags: [tags] security: - ApiKeyAuth: [] @@ -6863,15 +6931,111 @@ paths: schema: $ref: "#/components/schemas/AssignedTemplateTags" "400": - $ref: "#/components/responses/400" + description: Bad request + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "401": - $ref: "#/components/responses/401" + description: Authentication error + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "403": + description: Forbidden + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "404": - $ref: "#/components/responses/404" + description: Not found + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "408": + description: Request body read timed out before execution + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "409": + description: The Idempotency-Key conflicts with a different request (error_code idempotency_request_mismatch), or the matching original request has no recorded response yet and is within its expected response window (error_code idempotency_in_progress); this request was not executed again + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "413": + description: Request body exceeds the size limit + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + text/plain: + schema: + type: string + "422": + description: The matching original request has no recorded response and its expected response deadline has passed or is unknown (error_code idempotency_outcome_unknown); this request was not executed again + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "429": - $ref: "#/components/responses/429" + description: Too many requests + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + Retry-After: + description: When present, the number of seconds to wait before retrying the request. + required: false + schema: + type: integer + minimum: 0 + example: 30 + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "500": - $ref: "#/components/responses/500" + description: Server error. A failed commit has an uncertain outcome and omits Should-Retry; with an Idempotency-Key that error is replayed without executing again. + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "503": + description: Idempotency is unavailable; the request was not executed + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" delete: summary: Delete template tags description: Delete multiple tags from templates @@ -7635,25 +7799,39 @@ paths: "500": $ref: "#/components/responses/500" + /unstable/management/telemetry/names: + get: + operationId: managementTelemetryNames + summary: Read team and cluster names for telemetry. + description: Requires a direct mutual TLS connection from the configured telemetry reader service identity. Bearer tokens and forwarded identity headers are not accepted. Returns regional team and cluster names without connection credentials. Deleted projects and clusters being deleted are omitted. + tags: [admin] + security: [] + x-mutual-tls-required: true + responses: + "200": + description: Current regional names. + content: + application/json: + schema: + $ref: "#/components/schemas/TelemetryNames" + "401": + $ref: "#/components/responses/401" + "500": + $ref: "#/components/responses/500" + /unstable/management/clusters/{clusterID}: parameters: - $ref: "#/components/parameters/clusterID" - put: - operationId: managementRegisterCluster - summary: Register a cluster. - description: A cluster registered here for the first time starts with deletion protection turned off. Registering an existing cluster again with the same name and auth organization updates its endpoint, TLS setting, sandbox proxy domain and token and keeps its stored deletion protection; a different name or auth organization returns a conflict with error_code cluster_registration_conflict. An invalid registration returns 400 with error_code cluster_registration_invalid. + delete: + operationId: managementDeleteCluster + summary: Delete a cluster and its environments. + description: Deletes a cluster after all team assignments are detached. Deletion protection on the cluster rejects the deletion, and so does a live team assignment, before anything changes. In one transaction, which no team assignment can interleave with, it then soft-deletes every live template, snapshot template and paused sandbox snapshot on the cluster, releases their aliases, and releases all environment references while preserving environment and build history; the cluster service records the deletion and then deletes the cluster. An assignment requested meanwhile waits and is then refused. If the cluster service does not delete the cluster, nothing is soft-deleted and the cluster stays recorded as being deleted. Deleting an absent cluster still releases its templates, and is refused while a live team is assigned to it. The local cluster's nil ID is rejected. Repeating a completed deletion succeeds. tags: [admin] security: - AdminJWTAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ManagementClusterRegistrationRequest" responses: "204": - description: Cluster registration is present. + description: Cluster is absent. "400": $ref: "#/components/responses/400" "401": @@ -7662,20 +7840,21 @@ paths: $ref: "#/components/responses/409" "500": $ref: "#/components/responses/500" + "503": + $ref: "#/components/responses/503" + + /unstable/management/clusters/{clusterID}/registration: + parameters: + - $ref: "#/components/parameters/clusterID" delete: - operationId: managementDeleteCluster - summary: Delete a cluster and its environments. - description: Deletes a cluster after all team assignments are detached. In the same transaction, soft-deletes every live template, snapshot template and paused sandbox snapshot on the cluster, releases their aliases, and releases all environment references while preserving environment and build history. A team assignment rejects the deletion and leaves the environments untouched, and so does deletion protection on the cluster. The local cluster's nil ID is rejected. Repeating a completed deletion succeeds. + operationId: managementRemoveClusterRegistration + summary: Remove a cluster and leave surviving projects without a runtime. tags: [admin] security: - AdminJWTAuth: [] responses: "204": - description: Cluster is absent. - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" + description: Surviving projects keep their original cluster and lose runtime access. To run on another cluster, create a project with a new ID. Deleting the old project releases its slug but does not transfer its templates or API keys. "409": $ref: "#/components/responses/409" "500": @@ -7711,7 +7890,7 @@ paths: put: operationId: managementRequestClusterDeletion summary: Record that a cluster is being deleted. - description: Records that the caller is deleting the cluster, for a caller that deletes the cluster's teams before the cluster itself. Refused while the cluster has deletion protection turned on; a protection change in flight commits before or after the check, never between. Once recorded, deletion protection cannot be turned on, so the cluster delete that follows is not refused for protection, and no team can be newly assigned to the cluster. An assignment either commits before the deletion is recorded, where the caller's next project listing finds it, or is refused with cluster_assignment_cluster_deleting. Succeeds when the cluster is absent. Repeating the request succeeds. The local cluster's nil ID is rejected. + description: Records that the caller is deleting the cluster, for a caller that deletes the cluster's teams before the cluster itself. Refused while the cluster has deletion protection turned on; a protection change in flight commits before or after the check, never between. Once recorded, deletion protection cannot be turned on, so the cluster delete that follows is not refused for protection, and no team can be newly assigned to the cluster. An assignment either commits before this request returns, where the caller's next project listing finds it, or is refused with a conflict. Succeeds when the cluster is absent. Repeating the request succeeds. The local cluster's nil ID is rejected. tags: [admin] security: - AdminJWTAuth: [] @@ -7730,6 +7909,8 @@ paths: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" + "503": + $ref: "#/components/responses/503" /unstable/management/clusters/{clusterID}/destroy-readiness: parameters: @@ -7749,15 +7930,17 @@ paths: "401": $ref: "#/components/responses/401" "409": - description: The cluster has deletion protection turned on, or more than one team uses it and the other teams and their templates must move off it before destroying the cluster. + description: The cluster has deletion protection turned on, or more than one team still uses it. content: application/json: schema: $ref: "#/components/schemas/Error" "500": $ref: "#/components/responses/500" + "503": + $ref: "#/components/responses/503" - /unstable/management/projects/{projectID}/cluster/{clusterID}: + /unstable/management/projects/{projectID}: parameters: - name: projectID in: path @@ -7765,60 +7948,9 @@ paths: schema: type: string format: uuid - - $ref: "#/components/parameters/clusterID" put: - operationId: managementAssignProjectCluster - summary: Assign a cluster to a project. - description: >- - Assigns the cluster when the project has no cluster assigned. Replaying the identical - assignment succeeds; replacing a different assigned cluster returns a conflict. - Answers 404 when the project is missing or deleted. - tags: [admin] - security: - - AdminJWTAuth: [] - responses: - "204": - description: Cluster is assigned to the project. - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" - "404": - $ref: "#/components/responses/404" - "409": - $ref: "#/components/responses/409" - "500": - $ref: "#/components/responses/500" - delete: - operationId: managementDetachProjectCluster - summary: Detach a cluster assignment from a project. - description: Answers 404 when the project is missing or deleted. - tags: [admin] - security: - - AdminJWTAuth: [] - responses: - "204": - description: The matching assignment is absent. - "401": - $ref: "#/components/responses/401" - "404": - $ref: "#/components/responses/404" - "409": - $ref: "#/components/responses/409" - "500": - $ref: "#/components/responses/500" - - /unstable/management/projects/{projectID}: - parameters: - - name: projectID - in: path - required: true - schema: - type: string - format: uuid - put: - operationId: managementUpsertProject - summary: Create or reconcile a project. + operationId: managementUpsertProject + summary: Create or reconcile a project. tags: [admin] security: - AdminJWTAuth: [] @@ -7851,6 +7983,8 @@ paths: $ref: "#/components/responses/409" "500": $ref: "#/components/responses/500" + "503": + $ref: "#/components/responses/503" delete: operationId: managementDeleteProject summary: Soft-delete a project. @@ -8282,211 +8416,26 @@ paths: "500": $ref: "#/components/responses/500" - /unstable/admin/clusters: + /unstable/admin/clusters/team-counts: get: - operationId: adminListClusters - summary: List clusters as admin - description: Lists the registered clusters with the number of teams assigned to each. Never returns a cluster's token. The local cluster is not a registered cluster and is not listed. + operationId: adminListClusterTeamCounts + summary: Count each cluster's teams as admin + description: Returns the number of live teams assigned to each remote cluster. A cluster no live team is assigned to is absent. It reads only the teams, so it answers without a cluster service. tags: [admin] security: - AdminApiKeyAuth: [] - AdminJWTAuth: [] - parameters: - - name: limit - in: query - required: false - description: Maximum number of clusters to return - schema: - type: integer - format: int32 - minimum: 1 - maximum: 100 - default: 50 - - name: offset - in: query - required: false - description: Number of matching clusters to skip - schema: - type: integer - format: int32 - minimum: 0 - default: 0 - - name: search - in: query - required: false - description: Case-insensitive substring match on the cluster name or endpoint - schema: - type: string - - name: sortBy - in: query - required: false - description: Column to order by - schema: - type: string - enum: - - endpoint - - name - - teamCount - default: endpoint - - name: sortOrder - in: query - required: false - schema: - type: string - enum: - - asc - - desc - default: asc - x-enum-varnames: - - AdminListClustersSortOrderAsc - - AdminListClustersSortOrderDesc responses: "200": - description: The page of matching clusters and the number of all matching clusters + description: The team count of every cluster a live team is assigned to content: application/json: schema: - $ref: "#/components/schemas/ClusterListResponse" - "400": - $ref: "#/components/responses/400" + $ref: "#/components/schemas/ClusterTeamCountList" "401": $ref: "#/components/responses/401" "500": $ref: "#/components/responses/500" - post: - operationId: adminCreateCluster - summary: Create a cluster as admin - description: Creates a cluster whose configuration cannot be modified through this route. A new cluster starts with deletion protection turned on. Creating a cluster again with the same `cluster_id` and an identical configuration answers 201 with the stored cluster, whose deletionProtection is whatever is stored; a different configuration, or an auth organization another cluster uses, returns 409 with error_code cluster_registration_conflict. An invalid request returns 400 with error_code cluster_registration_invalid. - tags: [admin] - security: - - AdminApiKeyAuth: [] - - AdminJWTAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AdminClusterCreateRequest" - responses: - "201": - description: Cluster created. - content: - application/json: - schema: - $ref: "#/components/schemas/ClusterDetail" - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" - "409": - $ref: "#/components/responses/409" - "500": - $ref: "#/components/responses/500" - - /unstable/admin/clusters/{clusterID}: - parameters: - - $ref: "#/components/parameters/clusterID" - get: - operationId: adminGetCluster - summary: Cluster as admin - description: Returns a cluster with the first page of its assigned teams, the number of teams assigned to it and the number of live templates on it. Never returns the cluster's token. - tags: [admin] - security: - - AdminApiKeyAuth: [] - - AdminJWTAuth: [] - parameters: - - name: teamsLimit - in: query - required: false - description: Page size for the embedded teams page - schema: - type: integer - format: int32 - minimum: 1 - maximum: 100 - default: 50 - - name: teamsOffset - in: query - required: false - description: Offset for the embedded teams page - schema: - type: integer - format: int32 - minimum: 0 - default: 0 - responses: - "200": - description: The cluster - content: - application/json: - schema: - $ref: "#/components/schemas/ClusterDetailWithTeams" - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" - "404": - $ref: "#/components/responses/404" - "500": - $ref: "#/components/responses/500" - patch: - operationId: adminUpdateCluster - summary: Update a cluster as admin - description: >- - Writes only the properties present in the body. `endpoint` and - `endpointTls` change where orchestration traffic for every team on the - cluster goes, `sandboxProxyDomain` changes the public URL of every - sandbox on it, and `authOrgId` changes how the cluster authenticates. - A body with no property returns 400. Another cluster using the auth organization - returns 409, and so does turning deletion protection on after the - cluster's deletion is recorded. The token is rotated through - `PUT /unstable/admin/clusters/{clusterID}/token`. - tags: [admin] - security: - - AdminApiKeyAuth: [] - - AdminJWTAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ClusterUpdateRequest" - responses: - "200": - description: The cluster as updated - content: - application/json: - schema: - $ref: "#/components/schemas/ClusterDetail" - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" - "404": - $ref: "#/components/responses/404" - "409": - $ref: "#/components/responses/409" - "500": - $ref: "#/components/responses/500" - delete: - operationId: adminDeleteCluster - summary: Delete a cluster and its environments as admin - description: Deletes a cluster after all team assignments are detached. In the same transaction, soft-deletes every live template, snapshot template and paused sandbox snapshot on the cluster, releases their aliases, and releases all environment references while preserving environment and build history. A team assignment rejects the deletion and leaves the environments untouched, and so does deletion protection on the cluster. The local cluster's nil ID is rejected. Repeating a completed deletion succeeds. - tags: [admin] - security: - - AdminApiKeyAuth: [] - - AdminJWTAuth: [] - responses: - "204": - description: Cluster deleted or already absent. - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" - "409": - $ref: "#/components/responses/409" - "500": - $ref: "#/components/responses/500" /unstable/admin/clusters/{clusterID}/teams: parameters: @@ -8529,6 +8478,9 @@ paths: - createdAt - name default: createdAt + x-enum-varnames: + - AdminListClusterTeamsParamsSortByCreatedAt + - AdminListClusterTeamsParamsSortByName - name: sortOrder in: query required: false @@ -8556,35 +8508,8 @@ paths: $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" - - /unstable/admin/clusters/{clusterID}/token: - parameters: - - $ref: "#/components/parameters/clusterID" - put: - operationId: adminRotateClusterToken - summary: Rotate a cluster's token as admin - description: Replaces the token used to reach the cluster. The previous token stops working at once. No route returns a cluster's token. - tags: [admin] - security: - - AdminApiKeyAuth: [] - - AdminJWTAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ClusterTokenRotateRequest" - responses: - "204": - description: Token rotated. - "400": - $ref: "#/components/responses/400" - "401": - $ref: "#/components/responses/401" - "404": - $ref: "#/components/responses/404" - "500": - $ref: "#/components/responses/500" + "503": + $ref: "#/components/responses/503" /unstable/admin/templates/aliases: get: @@ -9091,7 +9016,11 @@ paths: post: summary: Create a secret - description: Create a secret by storing a runtime marker as its first version. The response carries metadata only. + description: >- + Create a secret by storing a runtime marker as its first version. The + response carries metadata only. The value is not part of the + Idempotency-Key comparison: reusing a key with a different value + replays the first result. tags: [secrets] security: - ApiKeyAuth: [] @@ -9101,6 +9030,8 @@ paths: AdminTeamAuth: [] - AdminJWTAuth: [] AdminTeamAuth: [] + parameters: + - $ref: "#/components/parameters/idempotencyKey" requestBody: required: true content: @@ -9115,18 +9046,44 @@ paths: schema: $ref: "#/components/schemas/Secret" "400": - $ref: "#/components/responses/400" + description: Invalid request or value too large + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "401": $ref: "#/components/responses/401" "403": - $ref: "#/components/responses/403" + description: Forbidden, blocked team, or secrets unavailable + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "404": - $ref: "#/components/responses/404" + description: Backend secret not found; creation may have partially committed + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "409": description: >- Secret name conflict or project live-secret limit reached. A quota response has error_code secret_limit_reached and, when reported by - the backend, the effective cap in message. + the backend, the effective cap in message. With an Idempotency-Key, + also returned when the key conflicts with a different request + (error_code idempotency_request_mismatch), or the matching original + request has no recorded response yet and is within its expected + response window (error_code idempotency_in_progress); this request + was not executed again. + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" content: application/json: schema: @@ -9137,14 +9094,59 @@ paths: code: 409 message: Project has reached its limit of 50 live secrets error_code: secret_limit_reached + "413": + description: Request body exceeds the size limit + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "422": + description: The matching original request has no recorded response and its expected response deadline has passed or is unknown (error_code idempotency_outcome_unknown); this request was not executed again + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "429": $ref: "#/components/responses/429" "500": - $ref: "#/components/responses/500" + description: Server error + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "502": - $ref: "#/components/responses/502" + description: Backend error + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "503": + description: With an Idempotency-Key, the request result is unavailable because the idempotency record could not be reserved or read, or idempotency is misconfigured; this request was not executed. Should-Retry true means a retry with the same Idempotency-Key may succeed; false means configuration must be corrected. + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" "504": - $ref: "#/components/responses/504" + description: Deadline exceeded + headers: + Should-Retry: + $ref: "#/components/headers/ShouldRetry" + content: + application/json: + schema: + $ref: "#/components/schemas/Error" /secrets/{secretID}: get: diff --git a/src/core/shared/contracts/infra-api.types.ts b/src/core/shared/contracts/infra-api.types.ts index fa350c697..964268da6 100644 --- a/src/core/shared/contracts/infra-api.types.ts +++ b/src/core/shared/contracts/infra-api.types.ts @@ -54,48 +54,6 @@ export interface paths { patch?: never trace?: never } - '/teams': { - parameters: { - query?: never - header?: never - path?: never - cookie?: never - } - /** - * List teams - * @description List all teams - */ - get: { - parameters: { - query?: never - header?: never - path?: never - cookie?: never - } - requestBody?: never - responses: { - /** @description Successfully returned all teams */ - 200: { - headers: { - [name: string]: unknown - } - content: { - 'application/json': components['schemas']['Team'][] - } - } - 401: components['responses']['401'] - 429: components['responses']['429'] - 500: components['responses']['500'] - } - } - put?: never - post?: never - delete?: never - options?: never - head?: never - patch?: never - trace?: never - } '/teams/{teamID}/metrics': { parameters: { query?: never @@ -2138,6 +2096,63 @@ export interface paths { } trace?: never } + '/templates/{templateID}/builds': { + parameters: { + query?: never + header?: never + path?: never + cookie?: never + } + /** + * List a template's builds + * @description List the builds of a template, newest first. The template is given by its ID or name. A template named `aliases` is given by its ID or by its name with the team prefix. + */ + get: { + parameters: { + query?: { + /** @description Cursor to start the list from */ + nextToken?: components['parameters']['paginationNextToken'] + /** @description Maximum number of items to return per page */ + limit?: components['parameters']['paginationLimit'] + /** @description Comma-separated list of build statuses to include. Every status when omitted. */ + statuses?: components['parameters']['templateBuildStatuses'] + /** @description Comma-separated list of tags. Only the builds these tags point at are returned. Every build when omitted. */ + tags?: components['parameters']['templateBuildTags'] + } + header?: never + path: { + templateID: components['parameters']['templateID'] + } + cookie?: never + } + requestBody?: never + responses: { + /** @description Successfully returned the template builds */ + 200: { + headers: { + 'X-Next-Token': components['headers']['XNextToken'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['TemplateBuildWithTags'][] + } + } + 400: components['responses']['400'] + 401: components['responses']['401'] + 403: components['responses']['403'] + 404: components['responses']['404'] + 429: components['responses']['429'] + 500: components['responses']['500'] + } + } + put?: never + post?: never + delete?: never + options?: never + head?: never + patch?: never + trace?: never + } '/v2/templates/{templateID}/builds/{buildID}': { parameters: { query?: never @@ -2289,7 +2304,38 @@ export interface paths { path?: never cookie?: never } - get?: never + /** + * Template info (v2) + * @description Get a template by its ID or name, with its default build and without its other builds. + */ + get: { + parameters: { + query?: never + header?: never + path: { + templateID: components['parameters']['templateID'] + } + cookie?: never + } + requestBody?: never + responses: { + /** @description Successfully returned the template */ + 200: { + headers: { + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['TemplateV2'] + } + } + 400: components['responses']['400'] + 401: components['responses']['401'] + 403: components['responses']['403'] + 404: components['responses']['404'] + 429: components['responses']['429'] + 500: components['responses']['500'] + } + } put?: never post?: never delete?: never @@ -2449,12 +2495,31 @@ export interface paths { put?: never /** * Assign template tags - * @description Assign tag(s) to a template build + * @description Assign tag(s) to a template build. */ post: { parameters: { query?: never - header?: never + header?: { + /** + * @description Optional team-scoped key for retrying the request. Use 1 to 255 lowercase ASCII letters, + * digits, or hyphens (a-z, 0-9, -), such as a lowercase UUID. The HTTP method, path, query, + * and request content identify the request. When idempotency is enabled, a matching retry of + * a completed request replays its status and body, including the IDs of any resources it + * created, without repeating the operation. A failure explicitly classified as safe to retry + * (Should-Retry: true) permits a fresh attempt with the same key and request. Only one + * attempt can run at a time. A different request returns 409 with error_code + * idempotency_request_mismatch. A matching request whose original has no recorded response + * yet and is within its expected response window returns 409 with error_code + * idempotency_in_progress. A matching request whose original has no recorded response and + * whose expected response deadline has passed or is unknown returns 422 with error_code + * idempotency_outcome_unknown. These conflicts and unknown outcomes do not execute the + * request again. If the key's record is unavailable or idempotency is misconfigured, the + * request returns 503; Should-Retry tells whether to retry with the same key. After the + * retention period expires, the key can start a new operation. + */ + 'Idempotency-Key'?: components['parameters']['idempotencyKey'] + } path?: never cookie?: never } @@ -2473,11 +2538,121 @@ export interface paths { 'application/json': components['schemas']['AssignedTemplateTags'] } } - 400: components['responses']['400'] - 401: components['responses']['401'] - 404: components['responses']['404'] - 429: components['responses']['429'] - 500: components['responses']['500'] + /** @description Bad request */ + 400: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Authentication error */ + 401: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Forbidden */ + 403: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Not found */ + 404: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Request body read timed out before execution */ + 408: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description The Idempotency-Key conflicts with a different request (error_code idempotency_request_mismatch), or the matching original request has no recorded response yet and is within its expected response window (error_code idempotency_in_progress); this request was not executed again */ + 409: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Request body exceeds the size limit */ + 413: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'text/plain': string + } + } + /** @description The matching original request has no recorded response and its expected response deadline has passed or is unknown (error_code idempotency_outcome_unknown); this request was not executed again */ + 422: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Too many requests */ + 429: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + /** + * @description When present, the number of seconds to wait before retrying the request. + * @example 30 + */ + 'Retry-After'?: number + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Server error. A failed commit has an uncertain outcome and omits Should-Retry; with an Idempotency-Key that error is replayed without executing again. */ + 500: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Idempotency is unavailable; the request was not executed */ + 503: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } } } /** @@ -3468,26 +3643,42 @@ export interface paths { patch?: never trace?: never } - '/unstable/management/clusters/{clusterID}': { + '/unstable/management/telemetry/names': { parameters: { query?: never header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } + path?: never cookie?: never } - get?: never /** - * Register a cluster. - * @description A cluster registered here for the first time starts with deletion protection turned off. Registering an existing cluster again with the same name and auth organization updates its endpoint, TLS setting, sandbox proxy domain and token and keeps its stored deletion protection; a different name or auth organization returns a conflict with error_code cluster_registration_conflict. An invalid registration returns 400 with error_code cluster_registration_invalid. + * Read team and cluster names for telemetry. + * @description Requires a direct mutual TLS connection from the configured telemetry reader service identity. Bearer tokens and forwarded identity headers are not accepted. Returns regional team and cluster names without connection credentials. Deleted projects and clusters being deleted are omitted. */ - put: operations['managementRegisterCluster'] + get: operations['managementTelemetryNames'] + put?: never + post?: never + delete?: never + options?: never + head?: never + patch?: never + trace?: never + } + '/unstable/management/clusters/{clusterID}': { + parameters: { + query?: never + header?: never + path: { + /** @description Identifier of the cluster */ + clusterID: components['parameters']['clusterID'] + } + cookie?: never + } + get?: never + put?: never post?: never /** * Delete a cluster and its environments. - * @description Deletes a cluster after all team assignments are detached. In the same transaction, soft-deletes every live template, snapshot template and paused sandbox snapshot on the cluster, releases their aliases, and releases all environment references while preserving environment and build history. A team assignment rejects the deletion and leaves the environments untouched, and so does deletion protection on the cluster. The local cluster's nil ID is rejected. Repeating a completed deletion succeeds. + * @description Deletes a cluster after all team assignments are detached. Deletion protection on the cluster rejects the deletion, and so does a live team assignment, before anything changes. In one transaction, which no team assignment can interleave with, it then soft-deletes every live template, snapshot template and paused sandbox snapshot on the cluster, releases their aliases, and releases all environment references while preserving environment and build history; the cluster service records the deletion and then deletes the cluster. An assignment requested meanwhile waits and is then refused. If the cluster service does not delete the cluster, nothing is soft-deleted and the cluster stays recorded as being deleted. Deleting an absent cluster still releases its templates, and is refused while a live team is assigned to it. The local cluster's nil ID is rejected. Repeating a completed deletion succeeds. */ delete: operations['managementDeleteCluster'] options?: never @@ -3495,7 +3686,7 @@ export interface paths { patch?: never trace?: never } - '/unstable/management/clusters/{clusterID}/projects': { + '/unstable/management/clusters/{clusterID}/registration': { parameters: { query?: never header?: never @@ -3505,20 +3696,17 @@ export interface paths { } cookie?: never } - /** - * List the projects assigned to a cluster. - * @description Returns the ID of every project whose team is assigned to the cluster, whichever way it was assigned. A deleted project is never assigned. An absent cluster has no projects. - */ - get: operations['managementListClusterProjects'] + get?: never put?: never post?: never - delete?: never + /** Remove a cluster and leave surviving projects without a runtime. */ + delete: operations['managementRemoveClusterRegistration'] options?: never head?: never patch?: never trace?: never } - '/unstable/management/clusters/{clusterID}/deletion': { + '/unstable/management/clusters/{clusterID}/projects': { parameters: { query?: never header?: never @@ -3528,12 +3716,12 @@ export interface paths { } cookie?: never } - get?: never /** - * Record that a cluster is being deleted. - * @description Records that the caller is deleting the cluster, for a caller that deletes the cluster's teams before the cluster itself. Refused while the cluster has deletion protection turned on; a protection change in flight commits before or after the check, never between. Once recorded, deletion protection cannot be turned on, so the cluster delete that follows is not refused for protection, and no team can be newly assigned to the cluster. An assignment either commits before the deletion is recorded, where the caller's next project listing finds it, or is refused with cluster_assignment_cluster_deleting. Succeeds when the cluster is absent. Repeating the request succeeds. The local cluster's nil ID is rejected. + * List the projects assigned to a cluster. + * @description Returns the ID of every project whose team is assigned to the cluster, whichever way it was assigned. A deleted project is never assigned. An absent cluster has no projects. */ - put: operations['managementRequestClusterDeletion'] + get: operations['managementListClusterProjects'] + put?: never post?: never delete?: never options?: never @@ -3541,7 +3729,7 @@ export interface paths { patch?: never trace?: never } - '/unstable/management/clusters/{clusterID}/destroy-readiness': { + '/unstable/management/clusters/{clusterID}/deletion': { parameters: { query?: never header?: never @@ -3551,12 +3739,12 @@ export interface paths { } cookie?: never } + get?: never /** - * Check cluster destroy readiness. - * @description Checks whether the cluster has deletion protection turned on, or more than one team uses this exact cluster, either as an assigned team or as the owner of active templates or snapshots on it. One team's own templates and snapshots do not block this check, because deleting the cluster soft-deletes them. Soft-deleted history does not count. Returns success if the cluster is absent. This read does not change resources or prevent later assignments or template creation. + * Record that a cluster is being deleted. + * @description Records that the caller is deleting the cluster, for a caller that deletes the cluster's teams before the cluster itself. Refused while the cluster has deletion protection turned on; a protection change in flight commits before or after the check, never between. Once recorded, deletion protection cannot be turned on, so the cluster delete that follows is not refused for protection, and no team can be newly assigned to the cluster. An assignment either commits before this request returns, where the caller's next project listing finds it, or is refused with a conflict. Succeeds when the cluster is absent. Repeating the request succeeds. The local cluster's nil ID is rejected. */ - get: operations['managementClusterDestroyReadiness'] - put?: never + put: operations['managementRequestClusterDeletion'] post?: never delete?: never options?: never @@ -3564,29 +3752,24 @@ export interface paths { patch?: never trace?: never } - '/unstable/management/projects/{projectID}/cluster/{clusterID}': { + '/unstable/management/clusters/{clusterID}/destroy-readiness': { parameters: { query?: never header?: never path: { - projectID: string /** @description Identifier of the cluster */ clusterID: components['parameters']['clusterID'] } cookie?: never } - get?: never /** - * Assign a cluster to a project. - * @description Assigns the cluster when the project has no cluster assigned. Replaying the identical assignment succeeds; replacing a different assigned cluster returns a conflict. Answers 404 when the project is missing or deleted. + * Check cluster destroy readiness. + * @description Checks whether the cluster has deletion protection turned on, or more than one team uses this exact cluster, either as an assigned team or as the owner of active templates or snapshots on it. One team's own templates and snapshots do not block this check, because deleting the cluster soft-deletes them. Soft-deleted history does not count. Returns success if the cluster is absent. This read does not change resources or prevent later assignments or template creation. */ - put: operations['managementAssignProjectCluster'] + get: operations['managementClusterDestroyReadiness'] + put?: never post?: never - /** - * Detach a cluster assignment from a project. - * @description Answers 404 when the project is missing or deleted. - */ - delete: operations['managementDetachProjectCluster'] + delete?: never options?: never head?: never patch?: never @@ -3931,7 +4114,7 @@ export interface paths { patch?: never trace?: never } - '/unstable/admin/clusters': { + '/unstable/admin/clusters/team-counts': { parameters: { query?: never header?: never @@ -3939,53 +4122,18 @@ export interface paths { cookie?: never } /** - * List clusters as admin - * @description Lists the registered clusters with the number of teams assigned to each. Never returns a cluster's token. The local cluster is not a registered cluster and is not listed. + * Count each cluster's teams as admin + * @description Returns the number of live teams assigned to each remote cluster. A cluster no live team is assigned to is absent. It reads only the teams, so it answers without a cluster service. */ - get: operations['adminListClusters'] + get: operations['adminListClusterTeamCounts'] put?: never - /** - * Create a cluster as admin - * @description Creates a cluster whose configuration cannot be modified through this route. A new cluster starts with deletion protection turned on. Creating a cluster again with the same `cluster_id` and an identical configuration answers 201 with the stored cluster, whose deletionProtection is whatever is stored; a different configuration, or an auth organization another cluster uses, returns 409 with error_code cluster_registration_conflict. An invalid request returns 400 with error_code cluster_registration_invalid. - */ - post: operations['adminCreateCluster'] + post?: never delete?: never options?: never head?: never patch?: never trace?: never } - '/unstable/admin/clusters/{clusterID}': { - parameters: { - query?: never - header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - /** - * Cluster as admin - * @description Returns a cluster with the first page of its assigned teams, the number of teams assigned to it and the number of live templates on it. Never returns the cluster's token. - */ - get: operations['adminGetCluster'] - put?: never - post?: never - /** - * Delete a cluster and its environments as admin - * @description Deletes a cluster after all team assignments are detached. In the same transaction, soft-deletes every live template, snapshot template and paused sandbox snapshot on the cluster, releases their aliases, and releases all environment references while preserving environment and build history. A team assignment rejects the deletion and leaves the environments untouched, and so does deletion protection on the cluster. The local cluster's nil ID is rejected. Repeating a completed deletion succeeds. - */ - delete: operations['adminDeleteCluster'] - options?: never - head?: never - /** - * Update a cluster as admin - * @description Writes only the properties present in the body. `endpoint` and `endpointTls` change where orchestration traffic for every team on the cluster goes, `sandboxProxyDomain` changes the public URL of every sandbox on it, and `authOrgId` changes how the cluster authenticates. A body with no property returns 400. Another cluster using the auth organization returns 409, and so does turning deletion protection on after the cluster's deletion is recorded. The token is rotated through `PUT /unstable/admin/clusters/{clusterID}/token`. - */ - patch: operations['adminUpdateCluster'] - trace?: never - } '/unstable/admin/clusters/{clusterID}/teams': { parameters: { query?: never @@ -4009,29 +4157,6 @@ export interface paths { patch?: never trace?: never } - '/unstable/admin/clusters/{clusterID}/token': { - parameters: { - query?: never - header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - get?: never - /** - * Rotate a cluster's token as admin - * @description Replaces the token used to reach the cluster. The previous token stops working at once. No route returns a cluster's token. - */ - put: operations['adminRotateClusterToken'] - post?: never - delete?: never - options?: never - head?: never - patch?: never - trace?: never - } '/unstable/admin/templates/aliases': { parameters: { query?: never @@ -4669,12 +4794,31 @@ export interface paths { put?: never /** * Create a secret - * @description Create a secret by storing a runtime marker as its first version. The response carries metadata only. + * @description Create a secret by storing a runtime marker as its first version. The response carries metadata only. The value is not part of the Idempotency-Key comparison: reusing a key with a different value replays the first result. */ post: { parameters: { query?: never - header?: never + header?: { + /** + * @description Optional team-scoped key for retrying the request. Use 1 to 255 lowercase ASCII letters, + * digits, or hyphens (a-z, 0-9, -), such as a lowercase UUID. The HTTP method, path, query, + * and request content identify the request. When idempotency is enabled, a matching retry of + * a completed request replays its status and body, including the IDs of any resources it + * created, without repeating the operation. A failure explicitly classified as safe to retry + * (Should-Retry: true) permits a fresh attempt with the same key and request. Only one + * attempt can run at a time. A different request returns 409 with error_code + * idempotency_request_mismatch. A matching request whose original has no recorded response + * yet and is within its expected response window returns 409 with error_code + * idempotency_in_progress. A matching request whose original has no recorded response and + * whose expected response deadline has passed or is unknown returns 422 with error_code + * idempotency_outcome_unknown. These conflicts and unknown outcomes do not execute the + * request again. If the key's record is unavailable or idempotency is misconfigured, the + * request returns 503; Should-Retry tells whether to retry with the same key. After the + * retention period expires, the key can start a new operation. + */ + 'Idempotency-Key'?: components['parameters']['idempotencyKey'] + } path?: never cookie?: never } @@ -4693,13 +4837,59 @@ export interface paths { 'application/json': components['schemas']['Secret'] } } - 400: components['responses']['400'] + /** @description Invalid request or value too large */ + 400: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } 401: components['responses']['401'] - 403: components['responses']['403'] - 404: components['responses']['404'] - /** @description Secret name conflict or project live-secret limit reached. A quota response has error_code secret_limit_reached and, when reported by the backend, the effective cap in message. */ + /** @description Forbidden, blocked team, or secrets unavailable */ + 403: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Backend secret not found; creation may have partially committed */ + 404: { + headers: { + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Secret name conflict or project live-secret limit reached. A quota response has error_code secret_limit_reached and, when reported by the backend, the effective cap in message. With an Idempotency-Key, also returned when the key conflicts with a different request (error_code idempotency_request_mismatch), or the matching original request has no recorded response yet and is within its expected response window (error_code idempotency_in_progress); this request was not executed again. */ 409: { headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Request body exceeds the size limit */ + 413: { + headers: { + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description The matching original request has no recorded response and its expected response deadline has passed or is unknown (error_code idempotency_outcome_unknown); this request was not executed again */ + 422: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] [name: string]: unknown } content: { @@ -4707,9 +4897,46 @@ export interface paths { } } 429: components['responses']['429'] - 500: components['responses']['500'] - 502: components['responses']['502'] - 504: components['responses']['504'] + /** @description Server error */ + 500: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Backend error */ + 502: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description With an Idempotency-Key, the request result is unavailable because the idempotency record could not be reserved or read, or idempotency is misconfigured; this request was not executed. Should-Retry true means a retry with the same Idempotency-Key may succeed; false means configuration must be corrected. */ + 503: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } + /** @description Deadline exceeded */ + 504: { + headers: { + 'Should-Retry': components['headers']['ShouldRetry'] + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['Error'] + } + } } } delete?: never @@ -5453,6 +5680,23 @@ export interface paths { export type webhooks = Record export interface components { schemas: { + TelemetryNames: { + teams: { + [key: string]: components['schemas']['TelemetryTeamName'] + } + clusters: components['schemas']['TelemetryClusterName'][] + } + TelemetryTeamName: { + name: string + /** Format: uuid */ + clusterId?: string + } + TelemetryClusterName: { + /** Format: uuid */ + id: string + name: string + clientId?: string + } /** @description An orchestrator node pool backed by one cloud scaling group */ Rig: { /** @description Rig identifier (e.g. "default") */ @@ -5520,16 +5764,6 @@ export interface components { /** @description Action being performed when the error occurred (e.g. CREATING) */ action?: string } - Team: { - /** @description Identifier of the team */ - teamID: string - /** @description Name of the team */ - name: string - /** @description API key for the team */ - apiKey: string - /** @description Whether the team is the default team */ - isDefault: boolean - } TeamUser: { /** * Format: uuid @@ -6186,52 +6420,6 @@ export interface components { TeamLimitsResponse: { limits: components['schemas']['TeamLimits'] } - /** @description A cluster's configuration. The cluster's token is never returned. */ - ClusterDetail: { - /** Format: uuid */ - id: string - name: string - endpoint: string - endpointTls: boolean - sandboxProxyDomain?: string | null - authOrgId?: string | null - /** @description While true, deleting the cluster is refused. */ - deletionProtection: boolean - } - ClusterDetailWithTeams: { - cluster: components['schemas']['ClusterDetail'] - teams: components['schemas']['ClusterTeamListResponse'] - /** - * Format: int64 - * @description Teams assigned to the cluster. Must be 0 before the cluster can be deleted. - */ - teamCount: number - /** - * Format: int64 - * @description Live templates on the cluster. Deleting the cluster deletes them. - */ - templateCount: number - } - ClusterListItem: { - /** Format: uuid */ - id: string - name: string - endpoint: string - sandboxProxyDomain?: string | null - /** - * Format: int64 - * @description Number of teams assigned to the cluster. - */ - teamCount: number - } - ClusterListResponse: { - items: components['schemas']['ClusterListItem'][] - /** - * Format: int64 - * @description Number of clusters matching the search, ignoring limit and offset - */ - total: number - } ClusterTeamListItem: { /** Format: uuid */ id: string @@ -6242,6 +6430,18 @@ export interface components { /** Format: date-time */ createdAt: string } + ClusterTeamCount: { + /** Format: uuid */ + clusterId: string + /** + * Format: int64 + * @description Number of live teams assigned to the cluster + */ + teamCount: number + } + ClusterTeamCountList: { + items: components['schemas']['ClusterTeamCount'][] + } ClusterTeamListResponse: { items: components['schemas']['ClusterTeamListItem'][] /** @@ -6250,35 +6450,6 @@ export interface components { */ total: number } - AdminClusterCreateRequest: { - /** - * Format: uuid - * @description Optional stable identifier for idempotent creation. Reuse succeeds only when the immutable configuration is identical. - */ - cluster_id?: string - name: string - endpoint: string - endpoint_tls: boolean - token: string - sandbox_proxy_domain?: string | null - auth_org_id?: string | null - } - /** @description Partial update; only the properties present are written. An explicit null or an empty string clears `sandboxProxyDomain` or `authOrgId`. */ - ClusterUpdateRequest: { - name?: string - endpoint?: string - endpointTls?: boolean - sandboxProxyDomain?: string | null - authOrgId?: string | null - deletionProtection?: boolean - } - ClusterTokenRotateRequest: { - /** - * Format: password - * @description New cluster access token. Write-only. - */ - token: string - } AdminSandboxKillResult: { /** @description Number of sandboxes successfully killed */ killedCount: number @@ -6318,7 +6489,10 @@ export interface components { templateID: string /** @description Tag the build is assigned under */ tag: string - /** @description Build status as stored, for example ready, snapshotting or waiting */ + /** + * @deprecated + * @description Same value as statusGroup + */ status: string statusGroup: components['schemas']['AdminSandboxBuildStatusGroup'] /** @description Node that produced the build, null when it was not recorded */ @@ -6449,7 +6623,10 @@ export interface components { templateId: string /** @description Tag the build is assigned under */ tag: string - /** @description Build status as stored, for example ready, snapshotting or waiting */ + /** + * @deprecated + * @description Same value as statusGroup + */ status: string /** @description Coarse build state, null when the stored group is not one of the known values */ statusGroup: components['schemas']['AdminSandboxBuildStatusGroup'] | null @@ -6725,7 +6902,10 @@ export interface components { cpuCount: components['schemas']['CPUCount'] /** @description Maximum CPU count for resizable templates; absent for fixed-size templates. */ maxCpuCount?: components['schemas']['CPUCount'] + /** @description Memory in MiB a sandbox created from this template starts with: the build's memory, or for a snapshot template of a grown sandbox the size it was taken at. A create that names no memoryMB starts at this size. */ memoryMB: components['schemas']['MemoryMB'] + /** @description Memory the template's sandboxes can grow to, in MiB; absent for templates whose memory cannot grow. */ + maxMemoryMB?: components['schemas']['MemoryMB'] diskSizeMB: components['schemas']['DiskSizeMB'] /** @description Whether the template is public or only accessible by the team */ public: boolean @@ -6903,10 +7083,58 @@ export interface components { cpuCount: components['schemas']['CPUCount'] /** @description Maximum CPU count for resizable templates; absent for fixed-size templates. */ maxCpuCount?: components['schemas']['CPUCount'] + /** @description Memory in MiB a sandbox created from this build starts with: the build's memory, or for a snapshot of a grown sandbox the size it was taken at. A create that names no memoryMB starts at this size. */ memoryMB: components['schemas']['MemoryMB'] + /** @description Memory the template's sandboxes can grow to, in MiB; absent for templates whose memory cannot grow. */ + maxMemoryMB?: components['schemas']['MemoryMB'] diskSizeMB?: components['schemas']['DiskSizeMB'] envdVersion?: components['schemas']['EnvdVersion'] } + TemplateBuildWithTags: components['schemas']['TemplateBuild'] & { + /** @description Tags of the template that point at this build. A tag points at the latest ready build it was assigned to, the build a sandbox created with that tag starts from. */ + tags: string[] + } + /** @description A template with its default build. `defaultBuild` is the build a sandbox created without a tag starts from, the latest ready build tagged default; it is absent until such a build is ready. `buildStatus` is the status of the latest build tagged default in any state: it is `building` while a rebuild runs, although sandboxes still start from the default build. */ + TemplateV2: { + /** @description Identifier of the template */ + templateID: string + /** @description Names of the template (namespace/alias format when namespaced) */ + names: string[] + /** @description Whether the template is public or only accessible by the team */ + public: boolean + /** + * Format: date-time + * @description Time when the template was created + */ + createdAt: string + /** + * Format: date-time + * @description Time when the template was last updated + */ + updatedAt: string + createdBy: components['schemas']['TeamUser'] | null + /** + * Format: date-time + * @description Time when the template was last used + */ + lastSpawnedAt: string | null + /** + * Format: int64 + * @description Number of times the template was used + */ + spawnCount: number + /** + * Format: int32 + * @description Number of times the template was built + */ + buildCount: number + /** @description Whether the template is one of the platform's default templates */ + isDefault: boolean + /** @description Description of the template */ + description?: string + buildStatus: components['schemas']['TemplateBuildStatus'] + defaultBuild?: components['schemas']['TemplateBuild'] + } TemplateWithBuilds: components['schemas']['Template'] & { /** @description List of builds for the template */ builds: components['schemas']['TemplateBuild'][] @@ -6953,6 +7181,8 @@ export interface components { /** @description Maximum CPU count the template's sandboxes can be resized to; makes the template resizable. Must be at least cpuCount. */ maxCpuCount?: components['schemas']['CPUCount'] memoryMB?: components['schemas']['MemoryMB'] + /** @description Memory the template's sandboxes can grow to, in MiB. memoryMB is what they boot with; the rest is added when a sandbox asks for it. Must be at least memoryMB, and the difference a multiple of 128 MiB. */ + maxMemoryMB?: components['schemas']['MemoryMB'] minFreeDiskMb?: components['schemas']['MinFreeDiskMb'] } FromImageRegistry: @@ -6967,7 +7197,10 @@ export interface components { type: 'aws' /** @description AWS Access Key ID for ECR authentication */ awsAccessKeyId: string - /** @description AWS Secret Access Key for ECR authentication */ + /** + * Format: password + * @description AWS Secret Access Key for ECR authentication + */ awsSecretAccessKey: string /** @description AWS Region where the ECR registry is located */ awsRegion: string @@ -6978,7 +7211,10 @@ export interface components { * @enum {string} */ type: 'gcp' - /** @description Service Account JSON for GCP authentication */ + /** + * Format: password + * @description Service Account JSON for GCP authentication + */ serviceAccountJson: string } GeneralRegistry: { @@ -6989,7 +7225,10 @@ export interface components { type: 'registry' /** @description Username to use for the registry */ username: string - /** @description Password to use for the registry */ + /** + * Format: password + * @description Password to use for the registry + */ password: string } /** @description Exactly one of fromImage or fromTemplate must be given and non-empty. */ @@ -7285,6 +7524,10 @@ export interface components { * @description Deadline of the operation holding the sandbox's lifecycle, absent when it is not held */ lifecycleHoldUntil?: string + /** @description Network the execution runs on, legacy, egress-router or full-router */ + networkMode: string + /** @description Whether the sandbox runs with managed volumes attached */ + volumesAttached: boolean } NodeDetail: { /** @description Identifier of the cluster */ @@ -7487,7 +7730,7 @@ export interface components { * @description Error code */ code: number - /** @description Machine-readable semantic error code. Not a closed set; initial values: sandbox_capacity_unavailable, sandbox_placement_timeout, sandbox_no_compatible_node, sandbox_create_failed (a node could not create the sandbox this time; retry), sandbox_create_refused (a node refused the sandbox for a reason no retry changes, such as a vcpu count out of bounds in the stored build; a server error, since no request field reaches that check), internal_server_error, secret_limit_reached, idempotency_request_mismatch, idempotency_in_progress, idempotency_outcome_unknown, cluster_registration_invalid, cluster_registration_conflict, cluster_assignment_invalid, cluster_assignment_project_not_found, cluster_assignment_cluster_not_found, cluster_assignment_already_assigned, cluster_assignment_cluster_deleting, sandbox_snapshot_guest_agent_unresponsive (a plain resume of a snapshot taken while the sandbox guest agent was not responding; resume it with memory: false). */ + /** @description Machine-readable semantic error code. Not a closed set; initial values: sandbox_capacity_unavailable, sandbox_placement_timeout, sandbox_no_compatible_node, sandbox_create_failed (a node could not create the sandbox this time; retry), sandbox_create_refused (a node refused the sandbox for a reason no retry changes, such as a vcpu count out of bounds in the stored build; a server error, since no request field reaches that check), internal_server_error, secret_limit_reached, idempotency_request_mismatch, idempotency_in_progress, idempotency_outcome_unknown, sandbox_snapshot_guest_agent_unresponsive (a plain resume of a snapshot taken while the sandbox guest agent was not responding; resume it with memory: false). */ error_code?: string /** @description Error */ message: string @@ -7557,12 +7800,18 @@ export interface components { NewSecret: { /** @description Name of the secret, unique within the project. Names are lower-cased before storage and returned in that canonical form; the sec_ prefix is reserved for secret identifiers. */ name: string - /** @description Runtime marker stored as the secret's first version. The runtime resolves it to a value at sandbox egress. */ + /** + * Format: password + * @description Runtime marker stored as the secret's first version. The runtime resolves it to a value at sandbox egress. + */ value: string metadata?: components['schemas']['SecretMetadata'] } SecretUpdate: { - /** @description Runtime marker stored as the secret's new version. The runtime resolves it to a value at sandbox egress. */ + /** + * Format: password + * @description Runtime marker stored as the secret's new version. The runtime resolves it to a value at sandbox egress. + */ value: string metadata?: components['schemas']['SecretMetadata'] } @@ -7628,7 +7877,10 @@ export interface components { events: string[] /** @default true */ enabled: boolean - /** @description Secret used to sign the webhook payloads */ + /** + * Format: password + * @description Secret used to sign the webhook payloads + */ signatureSecret: string } /** @description Webhook creation response */ @@ -7675,7 +7927,10 @@ export interface components { /** Format: uri */ url?: string events?: string[] - /** @description Secret used to sign the webhook payloads */ + /** + * Format: password + * @description Secret used to sign the webhook payloads + */ signatureSecret?: string } /** @description Webhook delivery attempt */ @@ -7795,14 +8050,6 @@ export interface components { /** @description Cursor to pass to the next list request, or null when there is no next page. */ nextCursor: string | null } - ManagementClusterRegistrationRequest: { - name: string - endpoint: string - endpoint_tls: boolean - token: string - sandbox_proxy_domain?: string | null - auth_org_id?: string | null - } ManagementClusterProjects: { project_ids: string[] } @@ -7823,14 +8070,14 @@ export interface components { defaultAllowPublicTraffic?: boolean } /** - * @description The properties of a project this side stores. Name, slug and email are synchronized on every push. The optional cluster assignment is preserved when omitted. + * @description The properties of a project this side stores. Name, slug and email are synchronized on every accepted push. The cluster is fixed at creation. * * A project's tier is not among them, and this side assigns none. Limits arrive separately and in full through managementUpsertProjectLimits. */ ManagementProjectUpsertRequest: { /** * Format: uuid - * @description Cluster assignment to synchronize. Omission preserves the existing assignment. + * @description Remote cluster fixed at creation. Omit to create a local project or to preserve an existing project's cluster. A different cluster returns 409. The response reports the stored cluster; local projects omit it. */ cluster_id?: string name: string @@ -7856,6 +8103,11 @@ export interface components { * @default false */ is_default: boolean + /** + * @description The member's effective role on the project. A viewer may only read. An omitted role keeps the stored one, and a new member without one is stored as member. + * @enum {string} + */ + role?: 'owner' | 'member' | 'viewer' identities?: components['schemas']['ManagementProjectMemberIdentity'][] } /** @description Desired project block state. A newer revision replaces the state, including any intervening manual block or unblock. */ @@ -8112,6 +8364,10 @@ export interface components { buildIDOrTemplate: string /** @description Comma-separated list of build statuses to include. */ buildStatuses: components['schemas']['BuildStatus'][] + /** @description Comma-separated list of build statuses to include. Every status when omitted. */ + templateBuildStatuses: components['schemas']['TemplateBuildStatus'][] + /** @description Comma-separated list of tags. Only the builds these tags point at are returned. Every build when omitted. */ + templateBuildTags: string[] /** @description Cursor returned by the previous list response in `created_at|build_id` format. */ buildsCursor: string /** @description Maximum number of builds to return per page. */ @@ -8152,7 +8408,29 @@ export interface components { } export type $defs = Record export interface operations { - managementRegisterCluster: { + managementTelemetryNames: { + parameters: { + query?: never + header?: never + path?: never + cookie?: never + } + requestBody?: never + responses: { + /** @description Current regional names. */ + 200: { + headers: { + [name: string]: unknown + } + content: { + 'application/json': components['schemas']['TelemetryNames'] + } + } + 401: components['responses']['401'] + 500: components['responses']['500'] + } + } + managementDeleteCluster: { parameters: { query?: never header?: never @@ -8162,13 +8440,9 @@ export interface operations { } cookie?: never } - requestBody: { - content: { - 'application/json': components['schemas']['ManagementClusterRegistrationRequest'] - } - } + requestBody?: never responses: { - /** @description Cluster registration is present. */ + /** @description Cluster is absent. */ 204: { headers: { [name: string]: unknown @@ -8179,9 +8453,10 @@ export interface operations { 401: components['responses']['401'] 409: components['responses']['409'] 500: components['responses']['500'] + 503: components['responses']['503'] } } - managementDeleteCluster: { + managementRemoveClusterRegistration: { parameters: { query?: never header?: never @@ -8193,15 +8468,13 @@ export interface operations { } requestBody?: never responses: { - /** @description Cluster is absent. */ + /** @description Surviving projects keep their original cluster and lose runtime access. To run on another cluster, create a project with a new ID. Deleting the old project releases its slug but does not transfer its templates or API keys. */ 204: { headers: { [name: string]: unknown } content?: never } - 400: components['responses']['400'] - 401: components['responses']['401'] 409: components['responses']['409'] 500: components['responses']['500'] } @@ -8263,6 +8536,7 @@ export interface operations { } } 500: components['responses']['500'] + 503: components['responses']['503'] } } managementClusterDestroyReadiness: { @@ -8286,7 +8560,7 @@ export interface operations { } 400: components['responses']['400'] 401: components['responses']['401'] - /** @description The cluster has deletion protection turned on, or more than one team uses it and the other teams and their templates must move off it before destroying the cluster. */ + /** @description The cluster has deletion protection turned on, or more than one team still uses it. */ 409: { headers: { [name: string]: unknown @@ -8296,59 +8570,7 @@ export interface operations { } } 500: components['responses']['500'] - } - } - managementAssignProjectCluster: { - parameters: { - query?: never - header?: never - path: { - projectID: string - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - requestBody?: never - responses: { - /** @description Cluster is assigned to the project. */ - 204: { - headers: { - [name: string]: unknown - } - content?: never - } - 400: components['responses']['400'] - 401: components['responses']['401'] - 404: components['responses']['404'] - 409: components['responses']['409'] - 500: components['responses']['500'] - } - } - managementDetachProjectCluster: { - parameters: { - query?: never - header?: never - path: { - projectID: string - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - requestBody?: never - responses: { - /** @description The matching assignment is absent. */ - 204: { - headers: { - [name: string]: unknown - } - content?: never - } - 401: components['responses']['401'] - 404: components['responses']['404'] - 409: components['responses']['409'] - 500: components['responses']['500'] + 503: components['responses']['503'] } } managementUpsertProject: { @@ -8389,6 +8611,7 @@ export interface operations { 404: components['responses']['404'] 409: components['responses']['409'] 500: components['responses']['500'] + 503: components['responses']['503'] } } managementDeleteProject: { @@ -8639,153 +8862,25 @@ export interface operations { 500: components['responses']['500'] } } - adminListClusters: { - parameters: { - query?: { - /** @description Maximum number of clusters to return */ - limit?: number - /** @description Number of matching clusters to skip */ - offset?: number - /** @description Case-insensitive substring match on the cluster name or endpoint */ - search?: string - /** @description Column to order by */ - sortBy?: 'endpoint' | 'name' | 'teamCount' - sortOrder?: 'asc' | 'desc' - } - header?: never - path?: never - cookie?: never - } - requestBody?: never - responses: { - /** @description The page of matching clusters and the number of all matching clusters */ - 200: { - headers: { - [name: string]: unknown - } - content: { - 'application/json': components['schemas']['ClusterListResponse'] - } - } - 400: components['responses']['400'] - 401: components['responses']['401'] - 500: components['responses']['500'] - } - } - adminCreateCluster: { + adminListClusterTeamCounts: { parameters: { query?: never header?: never path?: never cookie?: never } - requestBody: { - content: { - 'application/json': components['schemas']['AdminClusterCreateRequest'] - } - } - responses: { - /** @description Cluster created. */ - 201: { - headers: { - [name: string]: unknown - } - content: { - 'application/json': components['schemas']['ClusterDetail'] - } - } - 400: components['responses']['400'] - 401: components['responses']['401'] - 409: components['responses']['409'] - 500: components['responses']['500'] - } - } - adminGetCluster: { - parameters: { - query?: { - /** @description Page size for the embedded teams page */ - teamsLimit?: number - /** @description Offset for the embedded teams page */ - teamsOffset?: number - } - header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } requestBody?: never responses: { - /** @description The cluster */ + /** @description The team count of every cluster a live team is assigned to */ 200: { headers: { [name: string]: unknown } content: { - 'application/json': components['schemas']['ClusterDetailWithTeams'] + 'application/json': components['schemas']['ClusterTeamCountList'] } } - 400: components['responses']['400'] 401: components['responses']['401'] - 404: components['responses']['404'] - 500: components['responses']['500'] - } - } - adminDeleteCluster: { - parameters: { - query?: never - header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - requestBody?: never - responses: { - /** @description Cluster deleted or already absent. */ - 204: { - headers: { - [name: string]: unknown - } - content?: never - } - 400: components['responses']['400'] - 401: components['responses']['401'] - 409: components['responses']['409'] - 500: components['responses']['500'] - } - } - adminUpdateCluster: { - parameters: { - query?: never - header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - requestBody: { - content: { - 'application/json': components['schemas']['ClusterUpdateRequest'] - } - } - responses: { - /** @description The cluster as updated */ - 200: { - headers: { - [name: string]: unknown - } - content: { - 'application/json': components['schemas']['ClusterDetail'] - } - } - 400: components['responses']['400'] - 401: components['responses']['401'] - 404: components['responses']['404'] - 409: components['responses']['409'] 500: components['responses']['500'] } } @@ -8822,35 +8917,7 @@ export interface operations { 401: components['responses']['401'] 404: components['responses']['404'] 500: components['responses']['500'] - } - } - adminRotateClusterToken: { - parameters: { - query?: never - header?: never - path: { - /** @description Identifier of the cluster */ - clusterID: components['parameters']['clusterID'] - } - cookie?: never - } - requestBody: { - content: { - 'application/json': components['schemas']['ClusterTokenRotateRequest'] - } - } - responses: { - /** @description Token rotated. */ - 204: { - headers: { - [name: string]: unknown - } - content?: never - } - 400: components['responses']['400'] - 401: components['responses']['401'] - 404: components['responses']['404'] - 500: components['responses']['500'] + 503: components['responses']['503'] } } }