Pulumi Deployments API

openapi: 3.0.3
info:
  description: APIs and Definitions for the Pulumi Cloud product.
  title: Pulumi APIs AccessTokens Deployments API
  version: 1.0.0
tags:
- name: Deployments
paths:
  /api/deployments/executor:
    get:
      description: Streams the Linux/AMD64 Pulumi Deployments executor binary to the requester. The executor is the component that runs inside a deployment container and executes the actual Pulumi operations. The binary is retrieved from the Docker image/filesystem and proxied through the service to control access. This API is for internal use by workflow runners and requires valid credentials.
      operationId: GetPulumiDeployExecutor
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: OK
      summary: GetPulumiDeployExecutor
      tags:
      - Deployments
  /api/deployments/poll:
    get:
      description: Polls the Pulumi Deployments queue for available work to execute. This endpoint is used by self-hosted deployment agents running in agent pools to pick up queued deployment jobs. Returns 200 with the next available deployment's workflow definition if work is available, or 204 No Content if the queue is empty. Agents should poll this endpoint repeatedly. Authenticated using an agent pool secret rather than a user access token.
      operationId: PollDeploymentsQueue
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentWorkflowDefinition'
          description: OK
        '204':
          description: No Content
        '403':
          description: Forbidden
      summary: PollDeploymentsQueue
      tags:
      - Deployments
  /api/deployments/{deploymentId}/status:
    get:
      description: Returns the current execution status of a Pulumi Deployments run. This endpoint is used by self-hosted deployment agents running in agent pools to check whether a deployment is still active. Authenticated using an agent pool secret rather than a user access token.
      operationId: GetDeploymentsStatus
      parameters:
      - description: The deployment identifier
        in: path
        name: deploymentId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                enum:
                - not-started
                - accepted
                - running
                - failed
                - succeeded
                - skipped
                type: string
                x-pulumi-model-property:
                  enumComments: JobStatus describes the status of a job run.
                  enumFieldComments:
                  - JobStatusNotStarted indicates that a job has not yet started.
                  - JobStatusAccepted indicates that a job has been accepted for execution, but is not yet running.
                  - JobStatusRunning indicates that a job is running.
                  - JobStatusFailed indicates that a job has failed.
                  - JobStatusSucceeded indicates that a job has succeeded.
                  - JobStatusSkipped indicates that a job has skipped as there are fresher deployments to execute in the queue.
                  enumFieldNames:
                  - NotStarted
                  - Accepted
                  - Running
                  - Failed
                  - Succeeded
                  - Skipped
                  enumTypeName: JobStatus
          description: OK
      summary: GetDeploymentsStatus
      tags:
      - Deployments
  /api/orgs/{orgName}/deployments:
    get:
      description: Returns a paginated list of all Pulumi Deployments executions across an organization, filtered to only include deployments for stacks the requesting user has access to. The response includes each deployment's ID, status, version, creation time, the requesting user, project and stack names, Pulumi operation type, job details, and associated update results. Use 'page' (minimum 1, default 1) and 'pageSize' (1-100, default 10) for pagination, 'sort' to specify the sort field, and 'asc' to control sort direction (default descending). The response also includes the total count of matching deployments.
      operationId: ListOrgDeployments
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: Sort in ascending order when true (default false)
        in: query
        name: asc
        schema:
          type: boolean
      - description: Page number (min 1, default 1)
        in: query
        name: page
        schema:
          format: int64
          type: integer
      - description: Results per page (1-100, default 10)
        in: query
        name: pageSize
        schema:
          format: int64
          type: integer
      - description: Field to sort results by
        in: query
        name: sort
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeploymentResponseV2'
          description: OK
        '400':
          description: Invalid query parameter
        '404':
          description: Run
      summary: ListOrgDeployments
      tags:
      - Deployments
  /api/orgs/{orgName}/deployments/metadata:
    get:
      description: Returns metadata about the organization's Pulumi Deployments state. The response includes the overall pause status, a list of individually paused stacks (as stack references like `project/stack`), the configured concurrency limit (maximum number of concurrent deployments), and deployment counts broken down by status (`notStarted`, `accepted`, `running`, `failed`, `succeeded`, `skipped`, and `total`). This endpoint is useful for monitoring deployment health and capacity across an organization.
      operationId: OrgDeploymentsMetadata
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgDeploymentsMetadataResponse'
          description: OK
      summary: OrgDeploymentsMetadata
      tags:
      - Deployments
  /api/orgs/{orgName}/deployments/pause:
    post:
      description: Pauses all future Pulumi Deployments executions across an entire organization. While paused, new deployments can still be queued and currently executing deployments will continue to run to completion. However, queued deployments will not be picked up for execution until deployments are resumed. This provides a safety mechanism to temporarily halt all deployment activity across the organization, for example during maintenance windows or incident response. Requires organization administrator permissions. Use the ResumeOrgDeployments endpoint to resume processing.
      operationId: PauseOrgDeployments
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: PauseOrgDeployments
      tags:
      - Deployments
  /api/orgs/{orgName}/deployments/resume:
    post:
      description: Resumes Pulumi Deployments executions for an organization that was previously paused via PauseOrgDeployments. Any queued deployments that accumulated while the organization was paused will begin processing according to the organization's concurrency limits. Requires organization administrator permissions.
      operationId: ResumeOrgDeployments
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: ResumeOrgDeployments
      tags:
      - Deployments
  /api/orgs/{orgName}/deployments/summary:
    get:
      description: Retrieves a summary of Pulumi Deployments compute usage (deployment minutes) for an organization. The response provides aggregated deployment minute consumption over the specified time period. Use the 'granularity' parameter to control time bucketing (e.g. 'daily' or 'hourly'), and either 'lookbackDays' (number of days from the current date) or 'lookbackStart' (a Unix timestamp) to define the reporting window. Returns 204 No Content if no usage data is available for the specified period.
      operationId: GetUsageSummaryDeployCompute
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: Time granularity for the summary (e.g. 'daily', 'hourly')
        in: query
        name: granularity
        schema:
          type: string
      - description: Number of days to look back from the current date
        in: query
        name: lookbackDays
        schema:
          format: int64
          type: integer
      - description: Start of the lookback period (Unix timestamp)
        in: query
        name: lookbackStart
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResourceCountSummaryResponse'
          description: OK
        '204':
          description: No Content
        '400':
          description: Bad granularity value or invalid lookbackDays/lookbackStart parameter
      summary: GetUsageSummaryDeployCompute
      tags:
      - Deployments
  /api/orgs/{orgName}/deployments/usagereport:
    get:
      description: Retrieves raw deployment usage records for self-hosted Pulumi Cloud customers to self-report deployment consumption. Returns aggregated deployment usage records for the specified organization. The 'lookbackDays' query parameter controls how far back in time to retrieve records. This endpoint is primarily used by self-hosted customers for usage reporting and billing reconciliation purposes.
      operationId: GetDeployUsageReport
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: Number of days to look back
        in: query
        name: lookbackDays
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UsageRecord'
                type: array
          description: successful operation
        '400':
          description: Invalid query parameter
      summary: GetDeployUsageReport
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments:
    get:
      description: Returns a paginated list of Pulumi Deployments executions for a specific stack. The response includes each deployment's ID, status, version, creation and modification timestamps, the requesting user, Pulumi operation type, job details with step-level progress, and associated stack update results. Use 'page' (minimum 1, default 1) and 'pageSize' (1-100, default 10) for pagination, 'sort' to specify the sort field, and 'asc' to control sort direction (default descending). The response also includes the total count of deployments for the stack.
      operationId: ListStackDeploymentsHandlerV2
      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: Sort in ascending order when true (default false)
        in: query
        name: asc
        schema:
          type: boolean
      - description: Page number (min 1, default 1)
        in: query
        name: page
        schema:
          format: int64
          type: integer
      - description: Results per page (1-100, default 10)
        in: query
        name: pageSize
        schema:
          format: int64
          type: integer
      - description: Field to sort results by
        in: query
        name: sort
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeploymentResponseV2'
          description: OK
        '400':
          description: Invalid query parameter
        '404':
          description: Run
      summary: ListStackDeploymentsHandlerV2
      tags:
      - Deployments
    post:
      description: 'Initiates a new Pulumi Deployments execution for a stack. Pulumi Deployments is a managed service that executes Pulumi operations (update, preview, refresh, or destroy) in a secure, hosted environment.


        **Important:** The stack must already exist before a deployment can be created for it.


        The `operation` field is required and accepts: `update`, `preview`, `refresh`, or `destroy`. Three usage modes are supported:

        1. **Stack settings only:** Send `{"operation": "update"}` to use the stack''s saved deployment settings.

        2. **Merged settings:** Include partial settings in the request body alongside `operation`. When `inheritSettings` is true (the default), request settings are merged with saved stack settings, with request values taking precedence.

        3. **Request settings only:** Set `inheritSettings` to false and provide all settings in the request body.


        Settings include source context (git repo, branch, directory), operation context (environment variables, pre-run commands, OIDC configuration), executor context, GitHub integration settings, and cache options.


        This is v2 with breaking changes from CreateAPIDeploymentHandler: inheritSettings defaults to true, and operation is a required top-level field and no longer valid as part of operationContext.'
      operationId: CreateAPIDeploymentHandlerV2
      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/CreateDeploymentRequest'
        x-originalParamName: body
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDeploymentResponse'
          description: Accepted
        '400':
          description: Missing top level required field 'operation' or 'operation' must only be set at the top level or the agent pool specified in the deployment settings does not exist
        '402':
          description: Drift remediation requires Business Critical subscription
        '404':
          description: Stack
      summary: CreateAPIDeploymentHandlerV2
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/cache:
    delete:
      description: Clears all cached dependency and build artifacts associated with the project for Pulumi Deployments. The deployment cache stores dependencies and other artifacts between deployment runs to speed up execution. Use this endpoint to force a clean build on the next deployment, for example when cached dependencies become stale or corrupted.
      operationId: ClearProjectCache
      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':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: Stack
      summary: ClearProjectCache
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/cache/url:
    post:
      description: Returns a presigned URL for saving or restoring the Pulumi Deployments dependency cache. The cache stores build artifacts and dependencies between deployment runs to speed up execution. The request body must specify a method (PUT to upload a cache archive, or GET to download one) and a non-empty cache key identifying the cached content. The returned presigned URL can be used directly for the corresponding HTTP operation against the object store without additional authentication.
      operationId: GetPresignedCacheURL
      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/CacheURLRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CacheURLResponse'
          description: OK
        '400':
          description: Invalid method. Must be PUT or GET. or Invalid key. Must be non-empty.
        '403':
          description: Forbidden
        '404':
          description: Stack
      summary: GetPresignedCacheURL
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/drift/schedules:
    post:
      description: Creates a drift detection schedule for a stack using Pulumi Deployments. Drift detection identifies divergence between the declared infrastructure state in your Pulumi program and the actual state of resources in the cloud provider. The 'scheduleCron' field accepts a cron expression defining when drift detection should run (e.g. '0 */4 * * *' for every 4 hours). When 'autoRemediate' is set to true, a remediation update is automatically triggered to bring resources back into alignment with the declared state whenever drift is detected. Auto-remediation requires a Business Critical subscription. The stack must have deployment settings configured before a drift schedule can be created.
      operationId: CreateScheduledDriftDeployment
      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/CreateScheduledDriftDeploymentRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAction'
          description: OK
        '400':
          description: Stack does not have deployment settings configured
        '402':
          description: Drift remediation requires Business Critical subscription
        '404':
          description: ScheduledAction
      summary: CreateScheduledDriftDeployment
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/drift/schedules/{scheduleID}:
    post:
      description: Updates the configuration of an existing drift detection schedule. The request body can modify the cron expression controlling when drift detection runs and the autoRemediate flag that determines whether detected drift is automatically corrected by running an update operation. Auto-remediation requires a Business Critical subscription. Only future executions are affected; past drift detection runs are not modified.
      operationId: UpdateScheduledDriftDeployment
      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 schedule identifier
        in: path
        name: scheduleID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduledDriftDeploymentRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAction'
          description: OK
        '400':
          description: Invalid schedule
        '402':
          description: Drift remediation requires Business Critical subscription
        '404':
          description: ScheduledAction or ScheduledDeployment
      summary: UpdateScheduledDriftDeployment
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/metadata:
    get:
      description: 'Returns metadata about the Pulumi Deployments state for a specific stack. The response distinguishes the source of any pause:


        - `paused`: overall pause status (true if either stack or org is paused)

        - `stackPaused`: whether the stack itself is paused

        - `organizationPaused`: whether the containing organization is paused


        This is useful for determining whether new deployments will be processed or held in the queue.'
      operationId: StackDeploymentsMetadata
      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/StackDeploymentsMetadataResponse'
          description: OK
      summary: StackDeploymentsMetadata
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/pause:
    post:
      description: Pauses all future Pulumi Deployments executions for a specific stack. While paused, new deployments can still be queued and currently executing deployments will continue to run to completion. However, queued deployments will not be picked up for execution until deployments are resumed. The stack must have deployment settings configured before it can be paused. Requires stack deployment create permissions. Use the ResumeStackDeployments endpoint to resume processing.
      operationId: PauseStackDeployments
      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':
          description: OK
        '400':
          description: Attempted to pause or resume deployments on stack before it has been configured for deployments
      summary: PauseStackDeployments
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/resume:
    post:
      description: Resumes Pulumi Deployments executions for a stack that was previously paused via PauseStackDeployments. Any queued deployments that accumulated while the stack was paused will begin processing. The stack must have deployment settings configured. Requires stack deployment create permissions.
      operationId: ResumeStackDeployments
      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':
          description: OK
        '400':
          description: Attempted to pause or resume deployments on stack before it has been configured for deployments
      summary: ResumeStackDeployments
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/schedules:
    get:
      description: 'Returns all scheduled deployment actions configured for a stack. The response includes all schedule types: custom deployment schedules (cron-based recurring or one-time), drift detection schedules, and TTL (time-to-live) schedules. Each schedule in the response contains its ID, type, configuration (cron expression or timestamp), current status (active or paused), and the deployment request that will be executed on each run.'
      operationId: ListScheduledDeployment
      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/ListScheduledActionsResponse'
          description: OK
        '404':
          description: Organization
      summary: ListScheduledDeployment
      tags:
      - Deployments
    post:
      description: Creates a custom deployment schedule for a stack using Pulumi Deployments. Custom schedules allow you to automate recurring or one-time Pulumi operations on a stack. The request must include exactly one of 'scheduleCron' (a cron expression for recurring executions, e.g. '0 */4 * * *' for every 4 hours) or 'scheduleOnce' (an ISO 8601 timestamp for a one-time execution). The 'request' field contains the deployment configuration that will be executed on each scheduled run, including the Pulumi operation type and any settings overrides. The stack must have deployment settings configured before a schedule can be created.
      operationId: CreateScheduledDeployment
      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/CreateScheduledDeploymentRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAction'
          description: OK
        '400':
          description: Invalid definition for scheduled deployment or stack does not have deployment settings configured
      summary: CreateScheduledDeployment
      tags:
      - Deployments
  /api/stacks/{orgName}/{projectName}/{stackName}/deployments/schedules/{scheduleID}:
    delete:
      description: Permanently deletes a scheduled deployment action from a stack. This removes the schedule configuration entirely and cannot be undone. The schedule will no longer execute any future runs. This endpoint is used for all schedule types (custom, drift detection, and TTL). To temporarily stop a schedule without deleting it, use the pause endpoint instead.
      operationId: DeleteScheduledDeployment
      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 schedule identifier
        in: path
        name: scheduleID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '404':
          description: ScheduledDeployment
      summary: DeleteScheduledDeployment
      tags:
      - Deployments
    get:
      description: Retrieves the full configuration and metadata for a specific scheduled deployment action. The response includes the schedule's ID, type (custom, drift, or TTL), timing configuration (cron expression or one-time timestamp), current status (active or paused), the deployment request that will be executed, and any type-specific fields such as autoRemediate for drift schedules or deleteAfterDestroy for TTL schedules.
      operationId: ReadScheduledDeployment
      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 schedule identifier
        in: path
        name: scheduleID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledAction'
          description: OK
        '404':
          description: ScheduledAction
      summary: ReadScheduledDeployment
      tags:
      - Deployments
    post:
      description: Updates the configuration of an existing custom deployment schedule. The request body can modify the timing (cron expression for recurring schedules or ISO 8601 timestamp for one-time schedules) and the deployment request that will be executed on each future run, including the Pulumi operation type and settings overrides. Only future executions are affected; past executions are not modified. The stack must have deployment settings configured.
      operationId: UpdateScheduledDeployment
      parameters:
      - description: The organization 

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