Pulumi Stacks API

openapi: 3.0.3
info:
  description: APIs and Definitions for the Pulumi Cloud product.
  title: Pulumi APIs AccessTokens Stacks API
  version: 1.0.0
tags:
- name: Stacks
paths:
  /api/console/orgs/{orgName}/members/{userLogin}/stacks/{projectName}/{stackName}:
    get:
      description: Lists all permissions granted to a specific organization member for a given stack. The response provides a comprehensive view of the user's access, including permissions inherited from the organization's default role, permissions granted through team memberships, and permissions explicitly assigned to the user. Returns 404 if the user does not exist.
      operationId: ListMemberStackPermissions
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The user login
        in: path
        name: userLogin
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMemberStackPermissionsResponse'
          description: OK
        '404':
          description: User
      summary: ListMemberStackPermissions
      tags:
      - Stacks
  /api/console/stacks/{orgName}/{projectName}/{stackName}/overview:
    get:
      description: Returns aggregated stack overview data optimized for display in the Pulumi Cloud web console. The response combines information from multiple sources including the stack's current state, recent activity, resource counts, and configuration into a single response to minimize round trips.
      operationId: GetStackOverview
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StackOverviewResponse'
          description: OK
      summary: GetStackOverview
      tags:
      - Stacks
  /api/console/stacks/{orgName}/{projectName}/{stackName}/teams/{teamName}:
    patch:
      description: Modifies the permissions that a specific team has for the referenced stack. This allows setting the team's permission level (read, write, admin) for a single stack without affecting the team's permissions on other stacks. Returns 400 if the permission level is invalid or the team does not have the required base permissions. Returns 403 if the caller lacks permission to update the team. Returns 404 if the team does not exist.
      operationId: UpdateTeamStackPermissions
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The team name
        in: path
        name: teamName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamStackPermissionsRequest'
        x-originalParamName: body
      responses:
        '204':
          description: No Content
        '400':
          description: Invalid stack permission or team does not have permissions for the program
        '403':
          description: You do not have permission to update this team.
        '404':
          description: Team
      summary: UpdateTeamStackPermissions
      tags:
      - Stacks
  /api/console/stacks/{orgName}/{projectName}/{stackName}/updates/latest/summary:
    get:
      description: Returns a human-readable summary of the most recent update to the stack, without requiring a specific update ID. The summary is formatted identically to the UpdateSummary endpoint, including a tree view of resource changes. This is a convenience endpoint that automatically resolves the latest update version. Returns 404 if the stack has no updates.
      operationId: UpdateSummaryHandlerLatest
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsoleUpdateSummary'
          description: OK
        '404':
          description: Update
      summary: UpdateSummaryHandlerLatest
      tags:
      - Stacks
  /api/console/stacks/{orgName}/{projectName}/{stackName}/updates/{updateID}/summary:
    get:
      description: Returns a human-readable summary of a specific update, identified by its update ID. The summary is formatted in the same manner as generated by the CLI on 'pulumi up', including a tree view of resource changes, create/update/delete counts, and the overall result. This endpoint is optimized for display in the Pulumi Cloud web console. Returns 404 if the update does not exist.
      operationId: UpdateSummary
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The update ID
        in: path
        name: updateID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsoleUpdateSummary'
          description: OK
        '404':
          description: Update
      summary: UpdateSummary
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}:
    delete:
      description: Removes a stack from Pulumi Cloud. By default, the stack must have no resources remaining; attempting to delete a stack that still manages resources will fail. Use the 'force' query parameter set to true to override this check and force deletion even when resources remain. The deletion is a soft-delete that hides the stack from normal queries. Returns 204 with no content on success.
      operationId: DeleteStack
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: When true, forces deletion even if the stack still has resources
        in: query
        name: force
        schema:
          type: boolean
      responses:
        '204':
          description: No Content
        '400':
          description: invalid query parameter
      summary: DeleteStack
      tags:
      - Stacks
    get:
      description: Retrieves detailed information about a specific stack, including its organization, project, and stack name, the current version number, all associated tags, any active update operations (with the operation kind, author, and start time), and the active update UUID. This is the primary endpoint for inspecting the current state and metadata of a stack.
      operationId: GetStack
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                activeUpdate: d333a711-4aa0-402f-be6d-72af9665fc37
                currentOperation:
                  author: jane@acme-corp.com
                  kind: update
                  started: 1720000000
                id: acme-corp/website/production
                orgName: acme-corp
                projectName: website
                stackName: production
                version: 42
              schema:
                $ref: '#/components/schemas/AppStack'
          description: OK
      summary: GetStack
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/activity:
    get:
      description: Returns the activity history for a stack, including updates, configuration changes, and other operations. Supports pagination via page and pageSize parameters (page 0 returns all results). Returns 400 if the page parameter is invalid.
      operationId: GetStackActivity
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: Page number for paginated results (0-indexed, where 0 returns all results)
        in: query
        name: page
        schema:
          format: int64
          type: integer
      - description: Number of results per page (must be >= 1 when page > 0)
        in: query
        name: pageSize
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStackActivityResponse'
          description: OK
        '400':
          description: Invalid 'page' value.
      summary: GetStackActivity
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/annotations/{kind}:
    get:
      description: Retrieves an annotation for a stack, identified by the annotation kind. Annotations are structured metadata that can be attached to stacks for purposes such as compliance tracking, custom metadata, or integration data. The optional 'source' and 'version' query parameters allow filtering by annotation source and specific version. Returns 404 if the annotation does not exist.
      operationId: GetStacksAnnotation
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The annotation kind
        in: path
        name: kind
        required: true
        schema:
          type: string
      - description: The annotation source
        in: query
        name: source
        schema:
          type: string
      - description: The annotation version number, used for filtering by a specific version
        in: query
        name: version
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: OK
        '404':
          description: Annotation
      summary: GetStacksAnnotation
      tags:
      - Stacks
    patch:
      description: 'Creates or updates an annotation for a stack, identified by the annotation kind. Annotations are structured metadata that can be attached to stacks. The ''version'' query parameter supports optimistic concurrency control: if provided, the update only succeeds if the current annotation version matches. Returns 409 if the annotation has changed since it was read (version conflict).'
      operationId: UpsertStacksAnnotations
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The annotation kind
        in: path
        name: kind
        required: true
        schema:
          type: string
      - description: The annotation source
        in: query
        name: source
        schema:
          type: string
      - description: The expected annotation version for optimistic concurrency control
        in: query
        name: version
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
        x-originalParamName: body
      responses:
        '204':
          description: No Content
        '409':
          description: the annotation has changed since it was read
      summary: UpsertStacksAnnotations
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/batch-decrypt:
    post:
      description: Decrypts a set of secret values in a single request using the stack's encryption key. The request body contains an array of base64-encoded ciphertexts. The response maps each ciphertext to its decrypted plaintext value. This is a more efficient alternative to calling the single-value decrypt endpoint multiple times. Returns 400 if the request body is invalid or if message authentication fails. Returns 413 if the request body exceeds the maximum allowed content size.
      operationId: BatchDecryptValue
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppBatchDecryptRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppBatchDecryptResponse'
          description: OK
        '400':
          description: body must be a JSON object or only "ciphertexts" valid within request body or ciphertexts was not an array or invalid base64 encoding or Message authentication failed
        '404':
          description: Not found
        '413':
          description: Content Too Large
      summary: BatchDecryptValue
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/batch-encrypt:
    post:
      description: Encrypts a set of plaintext values in a single request using the stack's encryption key. This is a more efficient alternative to calling the single-value encrypt endpoint multiple times. The response contains a map of the original plaintext values to their corresponding base64-encoded ciphertexts. Returns 413 if the request body exceeds the maximum allowed content size.
      operationId: BatchEncryptValue
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppBatchEncryptRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppBatchEncryptResponse'
          description: OK
        '413':
          description: Request Content Too Large
      summary: BatchEncryptValue
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/collaborators:
    get:
      deprecated: true
      description: Lists all collaborators for a stack, including their permission levels. This includes collaborators who have been invited but have not yet accepted their invitations. The response includes each collaborator's username and their permission level for the stack. This endpoint is deprecated.
      operationId: ListStackPermissions
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListStackCollaboratorsResponse'
          description: OK
      summary: ListStackPermissions
      tags:
      - Stacks
      x-pulumi-route-property:
        Deprecated: true
        Visibility: Public
  /api/stacks/{orgName}/{projectName}/{stackName}/collaborators/{userName}:
    delete:
      description: Removes a specific user's direct permission to access a stack. This only removes permissions explicitly granted to the user; permissions inherited from team membership or organization-level defaults are not affected. Returns 404 if the user does not exist.
      operationId: DeleteStackPermission
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The user name
        in: path
        name: userName
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '404':
          description: User
      summary: DeleteStackPermission
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/config:
    delete:
      description: Removes the service-managed configuration for a stack, including the secrets provider settings, encrypted key, encryption salt, and ESC environment reference. If stack configuration is returned by the API, it is used in place of the local stack config file (e.g. Pulumi.[stack].yaml). Deleting the config causes the CLI to fall back to the local config file. Returns 204 with no content on success.
      operationId: DeleteStackConfig
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      summary: DeleteStackConfig
      tags:
      - Stacks
    get:
      description: Retrieves the service-managed configuration for a stack. The response includes the ESC environment reference, secrets provider type, encrypted key, and encryption salt. If stack configuration is returned by the API, it is used in place of the local stack config file (e.g. Pulumi.[stack].yaml). Returns 404 if no service-managed configuration exists for the stack.
      operationId: GetStackConfig
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppStackConfig'
          description: OK
        '404':
          description: Stack Config
      summary: GetStackConfig
      tags:
      - Stacks
    put:
      description: Updates the service-managed configuration for a stack. The request body may include the ESC environment reference, secrets provider type, encrypted key, and encryption salt. If stack configuration is returned by the API, it is used in place of the local stack config file (e.g. Pulumi.[stack].yaml). Returns the updated configuration object. Returns 400 if the environment reference is invalid or not found.
      operationId: UpdateStackConfig
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppStackConfig'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppStackConfig'
          description: OK
        '400':
          description: invalid environment or invalid environment version or environment not found
      summary: UpdateStackConfig
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/decrypt:
    post:
      description: Decrypts a single secret value using the stack's encryption key. The request body contains the base64-encoded ciphertext. The response contains the decrypted plaintext value. For decrypting multiple values in a single request, use the BatchDecryptValue endpoint instead. Returns 413 if the request body exceeds the maximum allowed content size.
      operationId: DecryptValue
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppDecryptValueRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppDecryptValueResponse'
          description: OK
        '413':
          description: Request Content Too Large
      summary: DecryptValue
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/decrypt/log-batch-decryption:
    post:
      description: Records an audit log entry for a batch decryption event performed by a third-party secrets provider. When stacks use external secrets providers (such as AWS KMS, Azure Key Vault, or HashiCorp Vault), decryption happens client-side; this endpoint allows the CLI to report that decryption occurred for audit tracking purposes.
      operationId: LogOnlyBatchDecryptValue
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppLog3rdPartyDecryptionEvent'
        x-originalParamName: body
      responses:
        '204':
          description: No Content
      summary: LogOnlyBatchDecryptValue
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/decrypt/log-decryption:
    post:
      description: Records an audit log entry for a single-value decryption event performed by a third-party secrets provider. When stacks use external secrets providers (such as AWS KMS, Azure Key Vault, or HashiCorp Vault), decryption happens client-side; this endpoint allows the CLI to report that decryption occurred for audit tracking.
      operationId: LogOnlyDecryptValue
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppLog3rdPartyDecryptionEvent'
        x-originalParamName: body
      responses:
        '204':
          description: No Content
      summary: LogOnlyDecryptValue
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/destroy:
    post:
      description: Creates a new destroy update for the given stack. A destroy update tears down all resources managed by the stack. This only creates the update record; the update must subsequently be started via the StartUpdateForDestroy endpoint. Enforces stack update concurrency checks to prevent conflicting simultaneous operations.
      operationId: CreateUpdateForDestroy
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppUpdateProgramRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppUpdateProgramResponse'
          description: OK
      summary: CreateUpdateForDestroy
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/destroy/{updateID}:
    get:
      description: Returns the current status and results of a destroy update, including whether it is still in progress, succeeded, or failed. Supports pagination of results via the continuationToken query parameter.
      operationId: GetUpdateStatusForDestroy
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The update ID
        in: path
        name: updateID
        required: true
        schema:
          type: string
      - description: Continuation token for paginated results
        in: query
        name: continuationToken
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppUpdateResults'
          description: OK
        '400':
          description: invalid query parameter
      summary: GetUpdateStatusForDestroy
      tags:
      - Stacks
    post:
      description: Starts execution of a previously created destroy update. The update must have been created via CreateUpdateForDestroy first. Returns a lease token and version number for tracking the update. Returns 404 if the update does not exist, or 409 if another update is already in progress on the stack.
      operationId: StartUpdateForDestroy
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The project name
        in: path
        name: projectName
        required: true
        schema:
          type: string
      - description: The stack name
        in: path
        name: stackName
        required: true
        schema:
          type: string
      - description: The update ID
        in: path
        name: updateID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppStartUpdateRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppStartUpdateResponse'
          description: OK
        '404':
          description: Update
        '409':
          description: Another update is currently in progress.
      summary: StartUpdateForDestroy
      tags:
      - Stacks
  /api/stacks/{orgName}/{projectName}/{stackName}/destroy/{updateID}/cancel:
    post:
      description: Requests cancellation of a service-managed update that is currently in progress. The update must have been started (returns 409 if it has not). Returns 404 if the specified update does not exist. The cancellation is processed asynchronously and the update will transition to a cancelled state.
      operationId: CancelUpdate_destroy
      parameters:
 

# --- truncated at 32 KB (327 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pulumi/refs/heads/main/openapi/pulumi-stacks-api-openapi.yml