openapi: 3.2.0 info: title: Prisma Postgres Management [Experimental] API description: REST API for managing Prisma Postgres projects, databases, backups, and workspaces. version: v1 servers: - url: https://api.prisma.io security: - OAuth2: - workspace:admin - offline_access - Bearer: [] tags: - name: '[Experimental]' description: Experimental endpoints are in active development and may change at any time without notice. paths: /v1/apps: get: responses: '200': description: Returns the list of apps. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed projectId filter). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Apps tags: - '[Experimental]' parameters: - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination - in: query name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: branchId schema: anyOf: - type: string const: unassigned - type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: branchGitName schema: type: string minLength: 1 summary: List apps description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `GET /v1/services` instead. Returns all apps the token has access to, ordered by creation time (oldest first). Optionally filter by project ID. Supports cursor-based pagination.' deprecated: true x-prisma-stability: experimental post: responses: '201': description: App created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: An app with the same `displayName` already exists on the resolved branch. The body includes the existing app's id, name, and branch git name. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: app:already_exists message: type: string existingAppId: type: string name: type: string branchGitName: type: string required: - code - message - existingAppId - name - branchGitName required: - error '422': description: Validation failed (e.g. missing projectId, empty display name, or invalid region). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1Apps tags: - '[Experimental]' parameters: [] summary: Create app description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `POST /v1/services` instead. Creates a new app under the specified project. The `projectId` is required in the request body. The app is placed in the given region, or the project''s default region if omitted (falling back to us-east-1). Returns `409 Conflict` with the existing app''s id, name, and branch if an app with the same name already exists on the resolved branch.' deprecated: true x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: displayName: type: string minLength: 1 maxLength: 256 regionId: type: string enum: - us-east-1 - us-west-1 - eu-west-3 - eu-central-1 - ap-northeast-1 - ap-southeast-1 default: us-east-1 branchId: type: - string - 'null' pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ branchGitName: type: - string - 'null' minLength: 1 projectId: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: - displayName - projectId /v1/apps/{appId}: get: responses: '200': description: App retrieved. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1AppsByAppId tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get app description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `GET /v1/services/{serviceId}` instead. Returns an app by ID, including its region and active promoted deployment reference.' deprecated: true x-prisma-stability: experimental patch: responses: '200': description: App updated. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. empty display name). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: patchV1AppsByAppId tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Update app description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `PATCH /v1/services/{serviceId}` instead. Updates the display name of an app.' deprecated: true x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: displayName: type: string minLength: 1 maxLength: 256 branchId: type: - string - 'null' pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ branchGitName: type: - string - 'null' minLength: 1 delete: responses: '204': description: App deleted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: A deployment could not be deleted, or a concurrent deployment was created while deleting the app. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1AppsByAppId tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Delete app description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `DELETE /v1/services/{serviceId}` instead. Deletes an app. Deployments under the app are deleted before the app is deleted.' deprecated: true x-prisma-stability: experimental /v1/apps/{appId}/promote: post: responses: '200': description: Deployment promoted to app endpoint. The `reassignedDomains` field indicates how many custom domains were moved from the previously-promoted deployment to the new one. content: application/json: schema: type: object properties: data: type: object properties: appEndpointDomain: type: string reassignedDomains: type: number required: - appEndpointDomain - reassignedDomains required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App or deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment is not running. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed app ID or missing deployment ID). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit or Compute resource limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1AppsByAppIdPromote tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Promote deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `POST /v1/services/{serviceId}/promote` instead. Promotes a deployment to be the active deployment behind the app''s stable endpoint. The deployment must be running. Returns the app endpoint domain.' deprecated: true x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: deploymentId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ versionId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ deprecated: true description: 'Deprecated: use `deploymentId` instead. Ignored when `deploymentId` is also present.' /v1/apps/{appId}/rollback: post: responses: '200': description: Deployment made live behind the app endpoint. The `reassignedDomains` field indicates how many custom domains were moved from the previously-live deployment to the new one. content: application/json: schema: type: object properties: data: type: object properties: appEndpointDomain: type: string reassignedDomains: type: number required: - appEndpointDomain - reassignedDomains required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App or deployment not found, or the deployment's Foundry artifact no longer exists. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment cannot be made live (e.g. it has no runnable artifact or is mid-teardown and cannot reach a running state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed app ID or missing deployment ID). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit or Compute resource limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1AppsByAppIdRollback tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Roll an app back to an existing deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `POST /v1/services/{serviceId}/rollback` instead. Makes any eligible existing deployment live behind the app''s stable endpoint (rollback or roll-forward). Unlike promote, a stopped target is started and waited until it is running before the endpoint is switched, so the currently-live deployment keeps serving with zero downtime. Returns the app endpoint domain.' deprecated: true x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: deploymentId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ versionId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ deprecated: true description: 'Deprecated: use `deploymentId` instead. Ignored when `deploymentId` is also present.' /v1/apps/{appId}/domains: get: responses: '200': description: List of custom domains. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords pagination: type: object properties: hasMore: type: boolean const: false nextCursor: type: 'null' required: - hasMore - nextCursor required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1AppsByAppIdDomains tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: List custom domains for an app description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `GET /v1/services/{serviceId}/domains` instead. Returns all custom domains attached to any deployment of the app. Domains are aggregated across all deployments since Foundry lists per deployment.' deprecated: true x-prisma-stability: experimental post: responses: '200': description: Custom domain already registered on this app. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords required: - data '201': description: Custom domain created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords required: - data '400': description: Invalid hostname or DNS verification failed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: Hostname already registered. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: App has no promoted deployment. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Domain quota exceeded or rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1AppsByAppIdDomains tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Create a custom domain description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `POST /v1/services/{serviceId}/domains` instead. Registers a custom hostname for the app. The hostname must CNAME to the regional switchboard target before DNS verification can succeed. Returns 429 if the app has reached its domain quota (default: 3).' deprecated: true x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: hostname: type: string pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z]{2,}$ minLength: 1 maxLength: 253 required: - hostname /v1/apps/{appId}/deployments: get: responses: '200': description: Returns the list of deployments. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: deployment url: type: string format: uri serviceId: type: string foundryVersionId: type: string createdAt: type: string format: date-time required: - id - type - url - serviceId - foundryVersionId - createdAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1AppsByAppIdDeployments tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination summary: List deployments description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `GET /v1/services/{serviceId}/deployments` instead. Returns all deployments belonging to an app, ordered by creation time (newest first). Supports cursor-based pagination.' deprecated: true x-prisma-stability: experimental post: responses: '201': description: Deployment created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: deployment url: type: string format: uri foundryVersionId: type: string uploadUrl: type: - string - 'null' required: - id - type - url - foundryVersionId - uploadUrl required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: App not found, or the app's attached Branch has been deleted. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. `skipCodeUpload` without an active promoted deployment, or the app is not attached to a Branch — env-var resolution requires a Branch). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '500': description: Internal error while resolving the deploy-time env vars (e.g., a master-key rotation or storage corruption prevents the project's wrapped DEK or a per-value envelope from being decrypted). Not a client-fixable condition. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1AppsByAppIdDeployments tags: - '[Experimental]' parameters: - in: path name: appId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Create deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deprecated: use `POST /v1/services/{serviceId}/deployments` instead. Creates a new deployment under the specified app. Returns a pre-signed upload URL for the artifact unless `skipCodeUpload` is set (which forks the active promoted deployment''s artifact). Environment variables are resolved automatically from the app''s attached Branch (production-class templates for the production Branch; preview-class templates for preview Branches). Manage env vars via the `/v1/environment-variables` endpoints, not as part of the deploy payload.' deprecated: true x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: portMapping: type: object properties: http: anyOf: - type: integer minimum: 1 maximum: 65535 - type: 'null' skipCodeUpload: type: boolean additionalProperties: false /v1/services: get: responses: '200': description: Returns the list of services. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed projectId filter). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Services tags: - '[Experimental]' parameters: - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination - in: query name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: branchId schema: anyOf: - type: string const: unassigned - type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: branchGitName schema: type: string minLength: 1 summary: List services description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns all services the token has access to, ordered by creation time (oldest first). Optionally filter by project ID. Supports cursor-based pagination.' x-prisma-stability: experimental post: responses: '201': description: Service created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: A service with the same `displayName` already exists on the resolved branch. The body includes the existing service's id, name, and branch git name. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: app:already_exists message: type: string existingAppId: type: string name: type: string branchGitName: type: string required: - code - message - existingAppId - name - branchGitName required: - error '422': description: Validation failed (e.g. missing projectId, empty display name, or invalid region). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1Services tags: - '[Experimental]' parameters: [] summary: Create service description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Creates a new service under the specified project. The `projectId` is required in the request body. The service is placed in the given region, or the project''s default region if omitted (falling back to us-east-1). Returns `409 Conflict` with the existing service''s id, name, and branch if a service with the same name already exists on the resolved branch.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: displayName: type: string minLength: 1 maxLength: 256 regionId: type: string enum: - us-east-1 - us-west-1 - eu-west-3 - eu-central-1 - ap-northeast-1 - ap-southeast-1 default: us-east-1 branchId: type: - string - 'null' pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ branchGitName: type: - string - 'null' minLength: 1 projectId: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: - displayName - projectId /v1/services/{serviceId}: get: responses: '200': description: Service retrieved. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ServicesByServiceId tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get service description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns a service by ID, including its region and active promoted deployment reference.' x-prisma-stability: experimental patch: responses: '200': description: Service updated. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: app url: type: string format: uri name: type: string region: type: object properties: id: type: string name: type: string required: - id - name projectId: type: string branchId: type: - string - 'null' latestDeploymentId: type: - string - 'null' appEndpointDomain: type: string createdAt: type: string format: date-time required: - id - type - url - name - region - projectId - branchId - latestDeploymentId - appEndpointDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. empty display name). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: patchV1ServicesByServiceId tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Update service description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Updates the display name of a service.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: displayName: type: string minLength: 1 maxLength: 256 branchId: type: - string - 'null' pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ branchGitName: type: - string - 'null' minLength: 1 delete: responses: '204': description: Service deleted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: A deployment could not be deleted, or a concurrent deployment was created while deleting the service. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1ServicesByServiceId tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Delete service description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deletes a service. Deployments under the service are deleted before the service is deleted.' x-prisma-stability: experimental /v1/services/{serviceId}/promote: post: responses: '200': description: Deployment promoted to service endpoint. The `reassignedDomains` field indicates how many custom domains were moved from the previously-promoted deployment to the new one. content: application/json: schema: type: object properties: data: type: object properties: appEndpointDomain: type: string reassignedDomains: type: number required: - appEndpointDomain - reassignedDomains required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service or deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment is not running. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed service ID or missing deployment ID). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit or Compute resource limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1ServicesByServiceIdPromote tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Promote deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Promotes a deployment to be the active deployment behind the service''s stable endpoint. The deployment must be running. Returns the service endpoint domain.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: deploymentId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ versionId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ deprecated: true description: 'Deprecated: use `deploymentId` instead. Ignored when `deploymentId` is also present.' /v1/services/{serviceId}/rollback: post: responses: '200': description: Deployment made live behind the service endpoint. The `reassignedDomains` field indicates how many custom domains were moved from the previously-live deployment to the new one. content: application/json: schema: type: object properties: data: type: object properties: appEndpointDomain: type: string reassignedDomains: type: number required: - appEndpointDomain - reassignedDomains required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service or deployment not found, or the deployment's Foundry artifact no longer exists. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment cannot be made live (e.g. it has no runnable artifact or is mid-teardown and cannot reach a running state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed service ID or missing deployment ID). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit or Compute resource limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1ServicesByServiceIdRollback tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Roll a service back to an existing deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Makes any eligible existing deployment live behind the service''s stable endpoint (rollback or roll-forward). Unlike promote, a stopped target is started and waited until it is running before the endpoint is switched, so the currently-live deployment keeps serving with zero downtime. Returns the service endpoint domain.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: deploymentId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ versionId: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ deprecated: true description: 'Deprecated: use `deploymentId` instead. Ignored when `deploymentId` is also present.' /v1/services/{serviceId}/domains: get: responses: '200': description: List of custom domains. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords pagination: type: object properties: hasMore: type: boolean const: false nextCursor: type: 'null' required: - hasMore - nextCursor required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ServicesByServiceIdDomains tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: List custom domains for a service description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns all custom domains attached to any deployment of the service. Domains are aggregated across all deployments since Foundry lists per deployment.' x-prisma-stability: experimental post: responses: '200': description: Custom domain already registered on this service. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords required: - data '201': description: Custom domain created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords required: - data '400': description: Invalid hostname or DNS verification failed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: Hostname already registered. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Service has no promoted deployment. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Domain quota exceeded or rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1ServicesByServiceIdDomains tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Create a custom domain description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Registers a custom hostname for the service. The hostname must CNAME to the regional switchboard target before DNS verification can succeed. Returns 429 if the service has reached its domain quota (default: 3).' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: hostname: type: string pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z]{2,}$ minLength: 1 maxLength: 253 required: - hostname /v1/services/{serviceId}/deployments: get: responses: '200': description: Returns the list of deployments. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: deployment url: type: string format: uri serviceId: type: string foundryVersionId: type: string createdAt: type: string format: date-time required: - id - type - url - serviceId - foundryVersionId - createdAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ServicesByServiceIdDeployments tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination summary: List deployments description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns all deployments belonging to a service, ordered by creation time (newest first). Supports cursor-based pagination.' x-prisma-stability: experimental post: responses: '201': description: Deployment created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: deployment url: type: string format: uri foundryVersionId: type: string uploadUrl: type: - string - 'null' required: - id - type - url - foundryVersionId - uploadUrl required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Service not found, or the service's attached Branch has been deleted. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. `skipCodeUpload` without an active promoted deployment, or the service is not attached to a Branch — env-var resolution requires a Branch). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '500': description: Internal error while resolving the deploy-time env vars (e.g., a master-key rotation or storage corruption prevents the project's wrapped DEK or a per-value envelope from being decrypted). Not a client-fixable condition. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1ServicesByServiceIdDeployments tags: - '[Experimental]' parameters: - in: path name: serviceId schema: type: string pattern: ^(cps_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Create deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Creates a new deployment under the specified service. Returns a pre-signed upload URL for the artifact unless `skipCodeUpload` is set (which forks the active promoted deployment''s artifact). Environment variables are resolved automatically from the service''s attached Branch (production-class templates for the production Branch; preview-class templates for preview Branches). Manage env vars via the `/v1/environment-variables` endpoints, not as part of the deploy payload.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: portMapping: type: object properties: http: anyOf: - type: integer minimum: 1 maximum: 65535 - type: 'null' skipCodeUpload: type: boolean additionalProperties: false /v1/projects/{projectId}/branches: post: responses: '201': description: Created the Branch. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: branch url: type: string format: uri gitName: type: string isDefault: type: boolean role: type: string enum: - production - preview createdAt: type: string format: date-time updatedAt: type: string format: date-time project: type: object properties: id: type: string url: type: string format: uri name: type: string required: - id - url - name description: Thin reference to the parent Project. Member resources are intentionally NOT inlined — list /v1/databases?branchId= or /v1/apps?branchId= instead (see API design principles "Flat and Hierarchical Coexistence"). required: - id - type - url - gitName - isDefault - role - createdAt - updatedAt - project required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: A live Branch with the same gitName already exists. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid gitName. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1ProjectsByProjectIdBranches tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Create a branch description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Creates a Branch under the specified Project. The first Branch in a Project is always created with isDefault=true and role=production regardless of the body value. Later Branches are created with role=preview. Setting isDefault=true while another Branch already holds the default atomically swaps the default flag only.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: gitName: type: string minLength: 1 isDefault: type: boolean required: - gitName additionalProperties: false get: responses: '200': description: Returned the list of Branches. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: branch url: type: string format: uri gitName: type: string isDefault: type: boolean role: type: string enum: - production - preview createdAt: type: string format: date-time updatedAt: type: string format: date-time project: type: object properties: id: type: string url: type: string format: uri name: type: string required: - id - url - name description: Thin reference to the parent Project. Member resources are intentionally NOT inlined — list /v1/databases?branchId= or /v1/apps?branchId= instead (see API design principles "Flat and Hierarchical Coexistence"). required: - id - type - url - gitName - isDefault - role - createdAt - updatedAt - project pagination: type: object properties: nextCursor: type: - string - 'null' hasMore: type: boolean required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Mutually exclusive filters specified together. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranches tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination - in: query name: gitName schema: type: string minLength: 1 - in: query name: gitNameContains schema: type: string minLength: 1 summary: List branches in a project description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns the live Branches of a Project. Supports two mutually exclusive filters: ?gitName= (exact match — at most one row), ?gitNameContains= (case-sensitive substring). Soft-deleted Branches are not returned. Ordered by createdAt ascending.' x-prisma-stability: experimental /v1/branches/{branchId}: get: responses: '200': description: Returned the Branch. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: branch url: type: string format: uri gitName: type: string isDefault: type: boolean role: type: string enum: - production - preview createdAt: type: string format: date-time updatedAt: type: string format: date-time project: type: object properties: id: type: string url: type: string format: uri name: type: string required: - id - url - name description: Thin reference to the parent Project. Member resources are intentionally NOT inlined — list /v1/databases?branchId= or /v1/apps?branchId= instead (see API design principles "Flat and Hierarchical Coexistence"). required: - id - type - url - gitName - isDefault - role - createdAt - updatedAt - project required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1BranchesByBranchId tags: - '[Experimental]' parameters: - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get a branch description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns a single Branch by ID. Member resources are not inlined — list them via /v1/databases?branchId= and /v1/apps?branchId=.' x-prisma-stability: experimental patch: responses: '200': description: Branch updated. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: branch url: type: string format: uri gitName: type: string isDefault: type: boolean role: type: string enum: - production - preview createdAt: type: string format: date-time updatedAt: type: string format: date-time project: type: object properties: id: type: string url: type: string format: uri name: type: string required: - id - url - name description: Thin reference to the parent Project. Member resources are intentionally NOT inlined — list /v1/databases?branchId= or /v1/apps?branchId= instead (see API design principles "Flat and Hierarchical Coexistence"). required: - id - type - url - gitName - isDefault - role - createdAt - updatedAt - project required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: gitName rename, role change, demote-default, or unknown field rejected. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: patchV1BranchesByBranchId tags: - '[Experimental]' parameters: - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Update a branch description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Promotes a Branch to be the Project''s default. Only isDefault is mutable — gitName rename and role changes are rejected.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: isDefault: type: - boolean - 'null' additionalProperties: false delete: responses: '204': description: Branch soft-deleted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: Branch still has live member resources. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Branch is the Project's current default or production Branch. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1BranchesByBranchId tags: - '[Experimental]' parameters: - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Soft-delete a branch description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Soft-deletes a Branch (sets deletedAt). Refuses if the Branch is the Project''s current default, the Project''s production Branch, or has live members.' x-prisma-stability: experimental /v1/builds: post: responses: '201': description: The build. Returned whether this call created it or an earlier report of the same run did. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(bld_)([cC][^\s-]{8,}|[a-z0-9]+)$ source: type: string enum: - webhook - setup - manual - ci - cli state: type: string enum: - pending - running - succeeded - failed - cancelled phase: type: - string - 'null' enum: - queued - build - deploy - null description: Null when nothing reported a phase; the platform never invents an observation it did not receive. commitSha: type: string branchName: type: string gitRepoId: type: - string - 'null' description: Repository the build ran against. Set only when the workspace has a live link to it; a reported repository the platform does not know stays null. projectId: type: - string - 'null' pattern: ^(proj_)([cC][^\s-]{8,}|[a-z0-9]+)$ branchId: type: - string - 'null' pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ externalLogUrl: type: - string - 'null' deployedUrl: type: - string - 'null' applicationTopologyContentHash: type: - string - 'null' errorMessage: type: - string - 'null' failingStep: type: - string - 'null' createdAt: type: string startedAt: type: - string - 'null' finishedAt: type: - string - 'null' required: - id - source - state - phase - commitSha - branchName - gitRepoId - projectId - branchId - externalLogUrl - deployedUrl - applicationTopologyContentHash - errorMessage - failingStep - createdAt - startedAt - finishedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Build not found, or the caller's workspace does not own it (indistinguishable). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1Builds tags: - '[Experimental]' parameters: [] summary: Report a build description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Records a build any deploy tool is running — a CI workflow, a deploy script, or Composer from a laptop. The workspace comes from the token, never from the body, which is what lets a build be reported before the project it will create exists. Supplying `runIdentity` makes the call idempotent: a repeat for the same run returns the build already recorded rather than a second one. The response is the same either way; a caller cannot tell whether it created the build or joined one. A build reported with no `runIdentity` has no dedup key, so a client that retries a lost response creates a second build. Supply a `runIdentity` whenever the run has one.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: source: type: string enum: - ci - cli description: '`ci` for a build reported from a CI run, `cli` for a deploy run directly by a human or agent.' commitSha: type: string minLength: 1 maxLength: 200 description: Commit the build ran on. branchName: type: string minLength: 1 maxLength: 500 description: Git branch name. runIdentity: type: object properties: provider: type: string const: github description: CI provider the run identity belongs to. repositoryId: type: string pattern: ^[0-9]+$ maxLength: 20 description: Provider's repository id (for GitHub, the numeric repo id). runId: type: string pattern: ^[0-9]+$ maxLength: 20 description: Provider's workflow-run id. runAttempt: type: integer exclusiveMinimum: 0 description: Attempt number of the run; a re-run is a separate build. required: - provider - repositoryId - runId - runAttempt description: Identifies the CI run. Supplying it makes creation idempotent — a repeat call for the same run returns the build that already exists. Omit it for builds with no run to name, such as a deploy from a laptop, where every call creates a new build. externalLogUrl: type: string format: uri maxLength: 2000 description: Link to the run's logs in the reporter's own system. projectId: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Project the build targets, when it exists. A build may be reported before its project does. branchId: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ applicationTopologyContentHash: type: string minLength: 1 maxLength: 200 description: 'Content hash of the application topology this run deploys, as submitted to the application-topology endpoint. A value match, never a reference: equal hashes identify the same graph.' required: - source - commitSha - branchName get: responses: '200': description: Builds, newest first. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string pattern: ^(bld_)([cC][^\s-]{8,}|[a-z0-9]+)$ source: type: string enum: - webhook - setup - manual - ci - cli state: type: string enum: - pending - running - succeeded - failed - cancelled phase: type: - string - 'null' enum: - queued - build - deploy - null description: Null when nothing reported a phase; the platform never invents an observation it did not receive. commitSha: type: string branchName: type: string gitRepoId: type: - string - 'null' description: Repository the build ran against. Set only when the workspace has a live link to it; a reported repository the platform does not know stays null. projectId: type: - string - 'null' pattern: ^(proj_)([cC][^\s-]{8,}|[a-z0-9]+)$ branchId: type: - string - 'null' pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ externalLogUrl: type: - string - 'null' deployedUrl: type: - string - 'null' applicationTopologyContentHash: type: - string - 'null' errorMessage: type: - string - 'null' failingStep: type: - string - 'null' createdAt: type: string startedAt: type: - string - 'null' finishedAt: type: - string - 'null' required: - id - source - state - phase - commitSha - branchName - gitRepoId - projectId - branchId - externalLogUrl - deployedUrl - applicationTopologyContentHash - errorMessage - failingStep - createdAt - startedAt - finishedAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Build not found, or the caller's workspace does not own it (indistinguishable). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Builds tags: - '[Experimental]' parameters: - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination - in: query name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: state schema: type: string enum: - pending - running - succeeded - failed - cancelled summary: List builds description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Lists the builds of the caller''s workspace, newest first, filtered by project, branch, or state. `cursor` is opaque: pass back the `nextCursor` the previous page returned.' x-prisma-stability: experimental /v1/builds/{buildId}: patch: responses: '200': description: The updated build. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(bld_)([cC][^\s-]{8,}|[a-z0-9]+)$ source: type: string enum: - webhook - setup - manual - ci - cli state: type: string enum: - pending - running - succeeded - failed - cancelled phase: type: - string - 'null' enum: - queued - build - deploy - null description: Null when nothing reported a phase; the platform never invents an observation it did not receive. commitSha: type: string branchName: type: string gitRepoId: type: - string - 'null' description: Repository the build ran against. Set only when the workspace has a live link to it; a reported repository the platform does not know stays null. projectId: type: - string - 'null' pattern: ^(proj_)([cC][^\s-]{8,}|[a-z0-9]+)$ branchId: type: - string - 'null' pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ externalLogUrl: type: - string - 'null' deployedUrl: type: - string - 'null' applicationTopologyContentHash: type: - string - 'null' errorMessage: type: - string - 'null' failingStep: type: - string - 'null' createdAt: type: string startedAt: type: - string - 'null' finishedAt: type: - string - 'null' required: - id - source - state - phase - commitSha - branchName - gitRepoId - projectId - branchId - externalLogUrl - deployedUrl - applicationTopologyContentHash - errorMessage - failingStep - createdAt - startedAt - finishedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Build not found, or the caller's workspace does not own it (indistinguishable). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: A fill-only field already holds a different value. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: patchV1BuildsByBuildId tags: - '[Experimental]' parameters: - in: path name: buildId schema: type: string pattern: ^(bld_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Update a build description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Records progress on a build. Any holder of the workspace token may patch any field — the webhook, the CI run and Composer each report the part of a deploy they can see, and the token is the boundary. Reaching `running` stamps `startedAt` and reaching a terminal state stamps `finishedAt`, both only if unset, so re-reporting the same state does not move the clock. Once a build has finished, its state no longer changes: a later report updates the other fields and leaves the state as the finishing report set it. `projectId`, `branchId`, `deployedUrl` and `applicationTopologyContentHash` are fill-only: a reporter that resolves them partway through a deploy sets them here, but a value already recorded cannot be changed and the attempt is a conflict. Sending the value already recorded is accepted and changes nothing. An anchor must belong to the caller''s workspace and agree with the anchors the build already carries, so a branch from another project is refused.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: phase: type: string enum: - queued - build - deploy description: How far the run has got. state: type: string enum: - pending - running - succeeded - failed - cancelled failingStep: type: string minLength: 1 maxLength: 500 description: Name of the step that failed, free text — step names come from build tooling the platform cannot validate. errorMessage: type: string minLength: 1 maxLength: 5000 externalLogUrl: type: string format: uri maxLength: 2000 projectId: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: 'Project the build targets. Fill-only: a reporter that learns the project partway through a deploy may set it, but a value already recorded cannot be changed.' branchId: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Branch the build targets. Fill-only, like `projectId`. deployedUrl: type: string format: uri maxLength: 2000 description: Where the deployed app can be reached. Fill-only, like the anchors. applicationTopologyContentHash: type: string minLength: 1 maxLength: 200 description: 'Content hash of the application topology this run deploys, as submitted to the application-topology endpoint. A value match, never a reference: equal hashes identify the same graph. Fill-only, like the anchors.' get: responses: '200': description: The build, with its reported resources. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(bld_)([cC][^\s-]{8,}|[a-z0-9]+)$ source: type: string enum: - webhook - setup - manual - ci - cli state: type: string enum: - pending - running - succeeded - failed - cancelled phase: type: - string - 'null' enum: - queued - build - deploy - null description: Null when nothing reported a phase; the platform never invents an observation it did not receive. commitSha: type: string branchName: type: string gitRepoId: type: - string - 'null' description: Repository the build ran against. Set only when the workspace has a live link to it; a reported repository the platform does not know stays null. projectId: type: - string - 'null' pattern: ^(proj_)([cC][^\s-]{8,}|[a-z0-9]+)$ branchId: type: - string - 'null' pattern: ^(br_)([cC][^\s-]{8,}|[a-z0-9]+)$ externalLogUrl: type: - string - 'null' deployedUrl: type: - string - 'null' applicationTopologyContentHash: type: - string - 'null' errorMessage: type: - string - 'null' failingStep: type: - string - 'null' createdAt: type: string startedAt: type: - string - 'null' finishedAt: type: - string - 'null' resources: type: array items: type: object properties: resourceType: type: string enum: - project - branch - database - app - deployment - bucket - service_key - config_variable resourceId: type: string description: Prefixed id of the reported resource. action: type: string enum: - created - acted_on - deleted createdAt: type: string required: - resourceType - resourceId - action - createdAt required: - id - source - state - phase - commitSha - branchName - gitRepoId - projectId - branchId - externalLogUrl - deployedUrl - applicationTopologyContentHash - errorMessage - failingStep - createdAt - startedAt - finishedAt - resources required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Build not found, or the caller's workspace does not own it (indistinguishable). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1BuildsByBuildId tags: - '[Experimental]' parameters: - in: path name: buildId schema: type: string pattern: ^(bld_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get a build description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns one build with the resources it reported acting on.' x-prisma-stability: experimental /v1/builds/{buildId}/resources/{resourceType}/{resourceId}: put: responses: '204': description: Recorded. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Build or resource not found, or the caller's workspace does not own it (indistinguishable). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: putV1BuildsByBuildIdResourcesByResourceTypeByResourceId tags: - '[Experimental]' parameters: - in: path name: buildId schema: type: string pattern: ^(bld_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: resourceType schema: type: string enum: - project - branch - database - app - deployment - bucket - service_key - config_variable required: true - in: path name: resourceId schema: type: string minLength: 1 maxLength: 200 required: true summary: Report a resource a build acted on description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Records that the build created, acted on, or deleted a platform resource — the provenance a deploy run leaves behind. Idempotent: re-reporting the same resource updates the row rather than adding one, and never weakens the recorded action. The resource must belong to the caller''s workspace, and must still be findable: a soft-deleted resource can be reported, but `project`, `database`, `service_key` and `config_variable` leave no row behind, so a build that deletes one must report it before deleting it. Reporting a deployment as `created` also attaches the deployment to the build and records the app it deployed into, both in the same transaction, because a deployment relates its build to that app whether or not the reporter says so.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: action: type: string enum: - created - acted_on - deleted description: 'The strongest effect the build had on the resource. Re-reporting is safe: a weaker action never overwrites a stronger one, so `created` survives a later `acted_on`.' required: - action /v1/builds/{buildId}/logs: get: responses: '200': description: Build log stream (newline-delimited JSON; one `BuildLogNdjsonLine` per line). content: application/x-ndjson: schema: oneOf: - type: object properties: type: type: string const: log text: type: string level: type: string enum: - info - error source: type: string enum: - runner - stdout - stderr step: type: string cursor: type: string required: - type - text - level - source - cursor - type: object properties: type: type: string const: terminal kind: type: string enum: - end - error code: type: string message: type: string retryable: type: boolean cursor: type: - string - 'null' required: - type - kind - code - message - retryable - cursor '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Build not found, or the caller's workspace does not own it (indistinguishable). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1BuildsByBuildIdLogs tags: - '[Experimental]' parameters: - in: path name: buildId schema: type: string minLength: 1 required: true - in: query name: follow schema: type: string enum: - 'true' - 'false' - in: query name: cursor schema: type: string summary: Stream build logs description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Streams the full build log for a build as newline-delimited JSON (`application/x-ndjson`). Each line is a JSON object discriminated by `type`: `log` (a build output line) or `terminal` (end-of-stream marker with a `cursor` for resumption). The default is a finite dump that ends once the stream is drained; pass `follow=true` to keep the connection open for an in-flight build, and `cursor` to resume from a prior terminal cursor.' x-prisma-stability: experimental /v1/domains/{domainId}: get: responses: '200': description: Custom domain details. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Custom domain not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1DomainsByDomainId tags: - '[Experimental]' parameters: - in: path name: domainId schema: type: string pattern: ^(dom_)?[A-Za-z0-9]+$ required: true summary: Get a custom domain description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns details for a custom domain by id. Authorization is derived from the parent compute service''s workspace.' x-prisma-stability: experimental delete: responses: '204': description: Custom domain deleted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Custom domain not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1DomainsByDomainId tags: - '[Experimental]' parameters: - in: path name: domainId schema: type: string pattern: ^(dom_)?[A-Za-z0-9]+$ required: true summary: Delete a custom domain description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Removes a custom domain binding. Authorization is derived from the parent compute service''s workspace.' x-prisma-stability: experimental /v1/domains/{domainId}/retry: post: responses: '200': description: Retry initiated, domain state returned. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: custom-domain url: type: string format: uri hostname: type: string appId: type: string computeServiceId: type: string deprecated: true description: 'Deprecated: use `appId` instead.' status: type: string enum: - pending_dns - verifying - verified_routing_blocked - provisioning_tls - active - failed - removing foundryStatus: type: string failureReason: type: - string - 'null' failureCategory: type: - string - 'null' enum: - dns - acme - storage - unknown - null certExpiresAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time dnsRecords: type: array items: type: object properties: type: type: string const: CNAME name: type: string value: type: string ttl: type: - number - 'null' required: - type - name - value - ttl required: - id - type - url - hostname - appId - computeServiceId - status - foundryStatus - failureReason - failureCategory - certExpiresAt - createdAt - updatedAt - dnsRecords required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Custom domain not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: Domain is not yet eligible for retry (e.g. still provisioning). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1DomainsByDomainIdRetry tags: - '[Experimental]' parameters: - in: path name: domainId schema: type: string pattern: ^(dom_)?[A-Za-z0-9]+$ required: true summary: Retry custom domain provisioning description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Retries DNS verification and certificate issuance for a failed or pending domain. Returns 409 if the domain is not yet eligible for retry (e.g. still provisioning).' x-prisma-stability: experimental /v1/deployments/{deploymentId}: get: responses: '200': description: Deployment retrieved. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: deployment url: type: string format: uri serviceId: type: string foundryVersionId: type: string status: type: string previewDomain: type: - string - 'null' envVars: type: object additionalProperties: type: string description: Always "[redacted]". Compute version inspection endpoints expose env var names only; values are never returned. example: '[redacted]' description: Environment variable names present on this compute version. Values are always redacted as "[redacted]" and must not be treated as deployed secret values. portMapping: type: object properties: http: type: number createdAt: type: string format: date-time required: - id - type - url - serviceId - foundryVersionId - status - previewDomain - createdAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1DeploymentsByDeploymentId tags: - '[Experimental]' parameters: - in: path name: deploymentId schema: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns a deployment by ID, including its current status derived from the underlying VM state.' x-prisma-stability: experimental delete: responses: '204': description: Deployment deleted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment must be stopped before it can be deleted. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1DeploymentsByDeploymentId tags: - '[Experimental]' parameters: - in: path name: deploymentId schema: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Delete deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Permanently deletes the deployment, its metadata, and any associated VM. The deployment must be stopped or in the `new` state before it can be deleted.' x-prisma-stability: experimental /v1/deployments/{deploymentId}/start: post: responses: '200': description: Start request accepted. The preview domain is returned immediately. content: application/json: schema: type: object properties: data: type: object properties: previewDomain: type: string required: - previewDomain required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment is in a state that does not allow starting (e.g. artifact not uploaded, or already running). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit or Compute resource limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1DeploymentsByDeploymentIdStart tags: - '[Experimental]' parameters: - in: path name: deploymentId schema: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Start deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Requests VM creation and startup for the deployment. The artifact must be uploaded before calling this endpoint. Returns a preview domain that becomes reachable once the VM is running. Poll the status endpoint until `running` is reached.' x-prisma-stability: experimental /v1/deployments/{deploymentId}/stop: post: responses: '204': description: Stop request accepted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions to access this resource. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deployment must be running or provisioning to be stopped. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1DeploymentsByDeploymentIdStop tags: - '[Experimental]' parameters: - in: path name: deploymentId schema: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Stop deployment description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Requests VM shutdown for the deployment. The deployment record and metadata are retained. Poll the status endpoint until `stopped` is reached.' x-prisma-stability: experimental /v1/deployments/{deploymentId}/logs: get: responses: '101': description: 'WebSocket connection established (requests with an `Upgrade: websocket` header). Each message is a JSON object discriminated by `type`.' '200': description: One page of deployment logs (newline-delimited JSON; one record per line, ending with a terminal record). content: application/x-ndjson: schema: oneOf: - type: object properties: type: type: string const: log text: type: string byteStart: type: integer byteEnd: type: integer required: - type - text - byteStart - byteEnd - type: object properties: type: type: string const: terminal kind: type: string enum: - end - error code: type: string message: type: string retryable: type: boolean cursor: type: - string - 'null' details: type: object additionalProperties: {} required: - type - kind - code - message - retryable - cursor '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Insufficient permissions. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Deployment not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1DeploymentsByDeploymentIdLogs tags: - '[Experimental]' parameters: - in: path name: deploymentId schema: type: string pattern: ^(cpv_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: query name: tail schema: type: integer minimum: 1 maximum: 10000 - in: query name: from_start schema: type: string enum: - 'true' - 'false' - in: query name: cursor schema: type: string pattern: ^\d+$ summary: Get deployment logs description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns log output for the specified deployment. Each record is a JSON object with `type: "log"` (log text + byte metadata) or `type: "terminal"` (end-of-page signal with a resume cursor). A plain GET responds with newline-delimited JSON (`application/x-ndjson`): it drains the requested window (`tail`, `from_start`, or `cursor`), ends with a terminal record carrying the cursor for the next page, and closes. Send an `Upgrade: websocket` header to follow the log live instead; a live segment ends after 10 minutes with the same terminal/cursor mechanism.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/lease: post: responses: '201': description: Acquired the deploy lease. content: application/json: schema: type: object properties: data: type: object properties: leaseId: type: string description: Capability token for the deploy lease. Send it in the Alchemy-State-Lease-Id header with every state operation; do not log it. expiresAt: type: string description: Lease expiry as an ISO-8601 timestamp. required: - leaseId - expiresAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: The deploy lease is held by another deploy. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateLease tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Acquire Alchemy deploy lease description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Acquires the deploy lease for a (branch, stack, stage). An expired lease is replaced atomically; a live lease fails fast with 409 naming the current holder — there is no queueing. Every Alchemy state operation requires a live deploy lease.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: stack: type: string minLength: 1 maxLength: 200 description: Alchemy stack name (opaque wire value). stage: type: string minLength: 1 maxLength: 200 description: Alchemy stage name (opaque wire value). ttlSeconds: type: integer exclusiveMinimum: 0 description: Requested lease TTL in seconds. Default 60, clamped to [30, 300]. holderDescription: type: string minLength: 1 maxLength: 500 description: Free-form description of the acquiring deploy, echoed in the contention error so a blocked deploy can name who holds the lease. required: - stack - stage patch: responses: '200': description: Extended the deploy lease. content: application/json: schema: type: object properties: data: type: object properties: leaseId: type: string description: Capability token for the deploy lease. Send it in the Alchemy-State-Lease-Id header with every state operation; do not log it. expiresAt: type: string description: Lease expiry as an ISO-8601 timestamp. required: - leaseId - expiresAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project, branch, or unexpired lease not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: patchV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateLease tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Heartbeat Alchemy deploy lease description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Extends the unexpired deploy lease addressed by the Alchemy-State-Lease-Id header from now. A missing, replaced, or expired lease returns 404 — the lost-lease signal; an expired lease can never be revived.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: ttlSeconds: type: integer exclusiveMinimum: 0 description: Requested lease TTL in seconds. Default 60, clamped to [30, 300]. delete: responses: '204': description: Released the deploy lease. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project, branch, or unexpired lease not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateLease tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Release Alchemy deploy lease description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Releases the deploy lease addressed by the Alchemy-State-Lease-Id header on clean deploy exit. A missing, replaced, or expired lease returns 404 — a lost lease at release time is surfaced, not idempotently swallowed.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/version: get: responses: '200': description: The state-store contract version. content: application/json: schema: type: object properties: version: type: number required: - version operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateVersion tags: - '[Experimental]' parameters: - schema: type: string in: path name: projectId required: true - schema: type: string in: path name: branchId required: true summary: Alchemy state store version description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Unauthenticated contract-version probe served verbatim from the pinned alchemy HttpStateApi contract. Returns the constant only and never inspects the addressed project or branch.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks: get: responses: '200': description: Stack names, sorted. content: application/json: schema: type: array items: type: string '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacks tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: List Alchemy stacks description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Lists the distinct stack names with state or output rows on the branch. Requires no deploy lease: the stock client''s auth probe (checkHttpStateStoreAuth) calls this endpoint bare, and it exposes stack names only.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks/{stack}/stages: get: responses: '200': description: Stage names, sorted. content: application/json: schema: type: array items: type: string '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStages tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: List Alchemy stages description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Lists the distinct stage names with state or output rows for the stack. Accepts a live deploy lease on any stage of the stack.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks/{stack}/stages/{stage}/resources: get: responses: '200': description: Resource FQNs, ordered. content: application/json: schema: type: array items: type: string '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageResources tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: List Alchemy resources description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Lists the resource FQNs stored for the stage, ordered by FQN.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks/{stack}/stages/{stage}/resources/{fqn}: get: responses: '200': description: The stored value, or null when absent. content: application/json: schema: {} '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageResourcesByFqn tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: fqn schema: type: string minLength: 1 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Get Alchemy resource state description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns the stored resource state, or a JSON null body when absent (the stock client maps null to undefined).' x-prisma-stability: experimental put: responses: '200': description: Echo of the stored value. content: application/json: schema: {} '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: putV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageResourcesByFqn tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: fqn schema: type: string minLength: 1 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Set Alchemy resource state description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Stores the resource state encrypted at rest and echoes the stored value.' x-prisma-stability: experimental requestBody: content: application/json: schema: {} delete: responses: '204': description: Deleted (or already absent). '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageResourcesByFqn tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: fqn schema: type: string minLength: 1 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Delete Alchemy resource state description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deletes the resource state row. Idempotent: deleting an absent row also returns 204.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks/{stack}/stages/{stage}/replaced-resources: get: responses: '200': description: Replaced resource states. content: application/json: schema: type: array items: {} '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageReplaced-resources tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: List replaced Alchemy resources description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns the decrypted resource states of the stage whose status is "replaced".' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks/{stack}/stages/{stage}/output: get: responses: '200': description: The stored output, or null when absent. content: application/json: schema: {} '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageOutput tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Get Alchemy stack output description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns the stored stack output for the stage, or a JSON null body when absent (the stock client maps null to undefined).' x-prisma-stability: experimental put: responses: '200': description: Echo of the stored value. content: application/json: schema: {} '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: putV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStackStagesByStageOutput tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: path name: stage schema: type: string minLength: 1 maxLength: 200 required: true - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Set Alchemy stack output description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Overwrites the stack output for the stage, encrypted at rest, and echoes the stored value.' x-prisma-stability: experimental requestBody: content: application/json: schema: {} /v1/projects/{projectId}/branches/{branchId}/alchemy-state/state/stacks/{stack}: delete: responses: '204': description: Deleted (or already absent). '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: No live deploy lease held for this stack and stage. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1ProjectsByProjectIdBranchesByBranchIdAlchemy-stateStateStacksByStack tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: stack schema: type: string minLength: 1 maxLength: 200 required: true - in: query name: stage schema: type: string minLength: 1 maxLength: 200 - in: header name: alchemy-state-lease-id schema: type: string pattern: ^(aslease_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Deploy-lease id returned by the lease acquire endpoint. Addresses the lease on heartbeat and release, and authorizes every state operation. required: true summary: Delete Alchemy stack state description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Deletes every resource-state and output row of the stack, or only the given stage''s rows when the stage query parameter is set. Requires a live deploy lease on the affected stage; without a stage it additionally requires that no other stage of the stack holds a live lease, so one stage''s deploy can never delete state another stage''s deploy is using. Idempotent.' x-prisma-stability: experimental /v1/projects/{projectId}/branches/{branchId}/application-topology: put: responses: '200': description: ApplicationTopology replaced. content: application/json: schema: type: object properties: data: type: object properties: nodes: type: array items: type: object properties: logicalId: type: string minLength: 1 parentLogicalId: type: - string - 'null' minLength: 1 kind: type: string enum: - module - service - resource type: type: string required: - logicalId - parentLogicalId - kind ports: type: array items: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 contractKind: type: string contractHash: type: string required: - logicalId - direction - name edges: type: array items: type: object properties: from: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 required: - logicalId - direction - name to: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 required: - logicalId - direction - name family: type: string enum: - communication - data style: type: string required: - from - to - family contentHash: type: string writtenAt: type: string format: date-time required: - nodes - ports - edges required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '413': description: Request body exceeds this endpoint's size cap. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid topology shape. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: putV1ProjectsByProjectIdBranchesByBranchIdApplication-topology tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Replace branch topology description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Atomically replaces the entire topology for a branch. Composer calls this after Load, before the apply. On error, Composer warns and continues — the previous topology is preserved.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: contentHash: type: string nodes: type: array items: type: object properties: logicalId: type: string minLength: 1 parentLogicalId: type: - string - 'null' minLength: 1 kind: type: string enum: - module - service - resource type: type: string required: - logicalId - parentLogicalId - kind ports: type: array items: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 contractKind: type: string contractHash: type: string required: - logicalId - direction - name edges: type: array items: type: object properties: from: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 required: - logicalId - direction - name to: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 required: - logicalId - direction - name family: type: string enum: - communication - data style: type: string required: - from - to - family required: - nodes - ports - edges get: responses: '200': description: The branch topology. content: application/json: schema: type: object properties: data: type: object properties: nodes: type: array items: type: object properties: logicalId: type: string minLength: 1 parentLogicalId: type: - string - 'null' minLength: 1 kind: type: string enum: - module - service - resource type: type: string required: - logicalId - parentLogicalId - kind ports: type: array items: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 contractKind: type: string contractHash: type: string required: - logicalId - direction - name edges: type: array items: type: object properties: from: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 required: - logicalId - direction - name to: type: object properties: logicalId: type: string minLength: 1 direction: type: string enum: - in - out name: type: string minLength: 1 required: - logicalId - direction - name family: type: string enum: - communication - data style: type: string required: - from - to - family contentHash: type: string writtenAt: type: string format: date-time required: - nodes - ports - edges required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or branch not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1ProjectsByProjectIdBranchesByBranchIdApplication-topology tags: - '[Experimental]' parameters: - in: path name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: path name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get branch topology description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns the stored topology graph for the branch — the same shape Composer submitted. Nodes, ports, and edges are returned in deterministic order.' x-prisma-stability: experimental /v1/environment-variables: post: responses: '201': description: Variable created. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: environment-variable url: type: string format: uri projectId: type: string branchId: type: - string - 'null' class: type: string enum: - production - preview key: type: string valueKid: type: string isManagedBySystem: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - projectId - branchId - class - key - valueKid - isManagedBySystem - createdAt - updatedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project not found, or token does not have access to it. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: A variable with this key already exists in this environment. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '500': description: Internal error while processing the encrypted variable (e.g., a master-key rotation or deploy issue prevents the project's wrapped DEK from being decrypted). Not a client-fixable condition. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1Environment-variables tags: - '[Experimental]' parameters: [] summary: Create an environment variable description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Creates a new environment variable in a project''s `production` or `preview` environment, or a preview branch override when `branchId` is supplied. Returns 409 if a variable with the same key already exists in that scope — use PATCH to replace its value. Values are stored encrypted and are not returned by subsequent reads.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: projectId: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ branchId: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ class: type: string enum: - production - preview key: type: string pattern: ^[A-Z_][A-Z0-9_]*$ minLength: 1 maxLength: 256 value: type: string minLength: 1 required: - projectId - class - key - value additionalProperties: false get: responses: '200': description: Returned the page of environment variables. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string const: environment-variable url: type: string format: uri projectId: type: string branchId: type: - string - 'null' class: type: string enum: - production - preview key: type: string valueKid: type: string isManagedBySystem: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - projectId - branchId - class - key - valueKid - isManagedBySystem - createdAt - updatedAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Environment-variables tags: - '[Experimental]' parameters: - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination - in: query name: limit schema: type: number default: 100 description: Limit for pagination - in: query name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ - in: query name: class schema: type: string enum: - production - preview - in: query name: key schema: type: string pattern: ^[A-Z_][A-Z0-9_]*$ minLength: 1 maxLength: 256 - in: query name: branchId schema: type: string pattern: ^(br_)?([cC][^\s-]{8,}|[a-z0-9]+)$ summary: List environment variables description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns a paginated list of environment variables. All filters are optional; combine `projectId`, `class`, and `key` to look up a specific variable by name.' x-prisma-stability: experimental /v1/environment-variables/{envVarId}: patch: responses: '200': description: Variable updated. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: environment-variable url: type: string format: uri projectId: type: string branchId: type: - string - 'null' class: type: string enum: - production - preview key: type: string valueKid: type: string isManagedBySystem: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - projectId - branchId - class - key - valueKid - isManagedBySystem - createdAt - updatedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Variable not found, or token does not have access to it. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '500': description: Internal error while processing the encrypted variable (e.g., a master-key rotation or deploy issue prevents the project's wrapped DEK from being decrypted). Not a client-fixable condition. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: patchV1Environment-variablesByEnvVarId tags: - '[Experimental]' parameters: - in: path name: envVarId schema: type: string pattern: ^(envvar_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Update an environment variable's value description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Replaces the value of an existing environment variable. Only the value is mutable — the project, environment, key, and branch are fixed at create-time.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: value: type: string minLength: 1 required: - value additionalProperties: false get: responses: '200': description: Returned the environment variable. content: application/json: schema: type: object properties: data: type: object properties: id: type: string type: type: string const: environment-variable url: type: string format: uri projectId: type: string branchId: type: - string - 'null' class: type: string enum: - production - preview key: type: string valueKid: type: string isManagedBySystem: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - projectId - branchId - class - key - valueKid - isManagedBySystem - createdAt - updatedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Variable not found, or token does not have access to it. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Environment-variablesByEnvVarId tags: - '[Experimental]' parameters: - in: path name: envVarId schema: type: string pattern: ^(envvar_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get an environment variable description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns a single environment variable''s metadata. The value is not returned.' x-prisma-stability: experimental delete: responses: '204': description: Variable deleted. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Variable not found, or token does not have access to it. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Invalid request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1Environment-variablesByEnvVarId tags: - '[Experimental]' parameters: - in: path name: envVarId schema: type: string pattern: ^(envvar_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Delete an environment variable description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Removes an environment variable. A second delete of the same variable returns 404.' x-prisma-stability: experimental /v1/auth/github-actions/token: post: responses: '201': description: Minted a short-lived workspace service token. content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: Prefixed integration token ID (`itgr_` prefix). type: type: string const: serviceToken value: type: string description: The minted integration token. Returned once — copy it immediately. expiresAt: type: string format: date-time description: ISO 8601 instant after which the token is invalid. workspaceId: type: string description: Prefixed workspace ID the token is scoped to. required: - id - type - value - expiresAt - workspaceId required: - data '401': description: Missing, expired, or invalid OIDC token, or no active repository link. content: application/json: schema: type: object properties: error: type: string const: unauthorized errorDescription: type: string required: - error - errorDescription '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1AuthGithub-actionsToken tags: - '[Experimental]' parameters: [] summary: Exchange a GitHub Actions OIDC token for a workspace service token description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Verifies the GitHub Actions OIDC token and mints a short-lived workspace service token. The caller must request the token with audience `prisma-cloud`. Any verification failure returns a generic 401 — the response never reveals whether a repository is connected.' security: [] x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: token: type: string minLength: 1 description: The GitHub Actions OIDC token with audience `prisma-cloud`. expiresInSeconds: type: integer minimum: 60 maximum: 3600 default: 1800 description: Requested token lifetime in seconds. Defaults to 1800 (30 min); capped at 3600 (60 min). required: - token /v1/scm-installations: get: responses: '200': description: SCM installations the caller can access in the workspace. May be empty. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string pattern: ^(scminstall_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: scm-installation url: type: string format: uri provider: type: string enum: - github installationId: type: integer description: Numeric installation ID assigned by the SCM provider accountId: type: integer description: Numeric account ID assigned by the SCM provider accountLogin: type: string accountType: type: string enum: - user - organization suspended: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - provider - installationId - accountId - accountLogin - accountType - suspended - createdAt - updatedAt pagination: type: object properties: nextCursor: type: - string - 'null' description: Next cursor to continue pagination hasMore: type: boolean description: Whether there are more items to paginate required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Scm-installations tags: - '[Experimental]' parameters: - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination required: false - in: query name: limit schema: type: number default: 100 description: Limit for pagination required: false - in: query name: workspaceId schema: type: string pattern: ^(wksp_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: List SCM installations for a workspace description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Lists active SCM installations connected to the given workspace.' x-prisma-stability: experimental /v1/scm-installations/install-intents: post: responses: '201': description: Installation intent created. The `installUrl` is single-use and time-limited. content: application/json: schema: type: object properties: data: type: object properties: type: type: string const: install-intent provider: type: string enum: - github workspaceId: type: string pattern: ^(wksp_)([cC][^\s-]{8,}|[a-z0-9]+)$ installUrl: type: string format: uri required: - type - provider - workspaceId - installUrl required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: Workspace integration tokens cannot create install intents; a user-authenticated request is required. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Workspace not found or not accessible. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Validation failed (e.g. malformed workspaceId or unsupported provider). content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '429': description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1Scm-installationsInstall-intents tags: - '[Experimental]' parameters: [] summary: Create an SCM App installation intent description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Creates an installation intent for the given workspace and returns a provider-specific URL that the user opens to install the SCM app. Currently only `github` is supported.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: provider: type: string enum: - github workspaceId: type: string pattern: ^(wksp_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: - provider - workspaceId /v1/scm-installations/{installationId}/repositories: get: responses: '200': description: Repositories accessible to the installation. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer description: Numeric repository ID assigned by the SCM provider type: type: string const: scm-repository fullName: type: string description: Full repository name, e.g. "octocat/hello" defaultBranch: type: string isPrivate: type: boolean required: - id - type - fullName - defaultBranch - isPrivate pagination: type: object properties: nextCursor: type: - string - 'null' hasMore: type: boolean required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Installation not found or not accessible. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: The SCM provider rejected the repository listing request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Scm-installationsByInstallationIdRepositories tags: - '[Experimental]' parameters: - in: path name: installationId schema: type: string pattern: ^(scminstall_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination (opaque, returned from previous response) - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 100 description: Maximum repositories to return (default and max 100). summary: List repositories accessible to an SCM installation description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Lists repositories accessible to the given SCM installation.' x-prisma-stability: experimental /v1/source-repositories: post: responses: '201': description: Source repository linked. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(srcrepo_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: source-repository url: type: string format: uri repoId: type: integer provider: type: string enum: - github repoFullName: type: string defaultBranch: type: string isPrivate: type: boolean status: type: string enum: - active - archived projectId: type: string installationId: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - repoId - provider - repoFullName - defaultBranch - isPrivate - status - projectId - installationId - createdAt - updatedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '403': description: SCM installation is suspended, uninstalled, or actor lacks access. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project or SCM installation not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '409': description: Repository or project already linked. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '422': description: Repository not accessible to the installation. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: postV1Source-repositories tags: - '[Experimental]' parameters: [] summary: Link a source repository to a project description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Links a GitHub repository to a Prisma project via an existing SCM installation.' x-prisma-stability: experimental requestBody: content: application/json: schema: type: object properties: projectId: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ provider: type: string const: github providerRepositoryId: type: integer exclusiveMinimum: 0 installationId: type: string pattern: ^(scminstall_)?([cC][^\s-]{8,}|[a-z0-9]+)$ description: Optional SCM installation ID to use for linking. When omitted, the API auto-picks the workspace's installation. required: - projectId - provider - providerRepositoryId get: responses: '200': description: Returned the list of source repositories. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string pattern: ^(srcrepo_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: source-repository url: type: string format: uri repoId: type: integer provider: type: string enum: - github repoFullName: type: string defaultBranch: type: string isPrivate: type: boolean status: type: string enum: - active - archived projectId: type: string installationId: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - repoId - provider - repoFullName - defaultBranch - isPrivate - status - projectId - installationId - createdAt - updatedAt pagination: type: object properties: nextCursor: type: - string - 'null' hasMore: type: boolean required: - nextCursor - hasMore required: - data - pagination '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Project not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Source-repositories tags: - '[Experimental]' parameters: - in: query name: cursor schema: type: - string - 'null' description: Cursor for pagination required: false - in: query name: limit schema: type: number default: 100 description: Limit for pagination required: false - in: query name: projectId schema: type: string pattern: ^(proj_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: List source repositories description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns source repositories linked to a project. Requires projectId query parameter.' x-prisma-stability: experimental /v1/source-repositories/{id}: delete: responses: '204': description: Source repository disconnected. '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Source repository not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: deleteV1Source-repositoriesById tags: - '[Experimental]' parameters: - in: path name: id schema: type: string pattern: ^(srcrepo_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Disconnect a source repository description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Disconnects the source repository link. Existing branches and their attached resources are preserved.' x-prisma-stability: experimental get: responses: '200': description: Returned the source repository. content: application/json: schema: type: object properties: data: type: object properties: id: type: string pattern: ^(srcrepo_)([cC][^\s-]{8,}|[a-z0-9]+)$ type: type: string const: source-repository url: type: string format: uri repoId: type: integer provider: type: string enum: - github repoFullName: type: string defaultBranch: type: string isPrivate: type: boolean status: type: string enum: - active - archived projectId: type: string installationId: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - type - url - repoId - provider - repoFullName - defaultBranch - isPrivate - status - projectId - installationId - createdAt - updatedAt required: - data '401': description: Missing or invalid authorization token. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error '404': description: Source repository not found. content: application/json: schema: type: object properties: error: type: object properties: code: type: string message: type: string hint: type: string required: - code - message required: - error operationId: getV1Source-repositoriesById tags: - '[Experimental]' parameters: - in: path name: id schema: type: string pattern: ^(srcrepo_)?([cC][^\s-]{8,}|[a-z0-9]+)$ required: true summary: Get a source repository description: '⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️ Returns a single source repository link by ID.' x-prisma-stability: experimental components: securitySchemes: OAuth2: type: oauth2 description: OAuth2 authentication flows: authorizationCode: authorizationUrl: https://auth.prisma.io/authorize tokenUrl: https://auth.prisma.io/token refreshUrl: https://auth.prisma.io/token scopes: workspace:admin: Full access to workspace resources offline_access: Offline access Bearer: type: http scheme: bearer bearerFormat: JWT description: OAuth2 token for API authentication