Pulumi Environments API

openapi: 3.0.3
info:
  description: APIs and Definitions for the Pulumi Cloud product.
  title: Pulumi APIs AccessTokens Environments API
  version: 1.0.0
tags:
- name: Environments
paths:
  /api/esc/environments:
    get:
      description: Returns a paginated list of all Pulumi ESC environments accessible to the authenticated user across all organizations they belong to. Each entry includes the organization, project, environment name, and creation/modification timestamps. Use the organization query parameter to filter results to a specific organization. Use continuationToken for pagination through large result sets.
      operationId: ListEnvironments_esc
      parameters:
      - description: Continuation token for paginated results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: Whether to include referrer metadata. Defaults to false.
        in: query
        name: includeReferrerMetadata
        schema:
          type: boolean
      - description: Maximum number of results for pagination
        in: query
        name: maxResults
        schema:
          format: int64
          type: integer
      - description: Filter results to this organization name
        in: query
        name: organization
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnvironmentsResponse'
          description: OK
        '400':
          description: Invalid continuation token
      summary: ListEnvironments
      tags:
      - Environments
  /api/esc/environments/{orgName}:
    get:
      description: Returns a paginated list of all Pulumi ESC environments within a specific organization. Each entry includes the project, environment name, and creation/modification timestamps. Results are scoped to the organization specified in the URL path. Use continuationToken for pagination through large result sets.
      operationId: ListOrgEnvironments_esc
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: Continuation token for paginated results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: Whether to include referrer metadata. Defaults to false.
        in: query
        name: includeReferrerMetadata
        schema:
          type: boolean
      - description: Maximum number of results for pagination
        in: query
        name: maxResults
        schema:
          format: int64
          type: integer
      - description: The custom role to use for listing environments
        in: query
        name: roleID
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnvironmentsResponse'
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: ListOrgEnvironments
      tags:
      - Environments
    post:
      description: Creates a new Pulumi ESC (Environments, Secrets, and Configuration) environment within the specified organization. The request body must include the project name and the environment name. Environment names must be unique within a project and may only contain alphanumeric characters, hyphens, underscores, and periods. The newly created environment starts with an empty YAML definition that can be updated via the UpdateEnvironment endpoint.
      operationId: CreateEnvironment_esc_environments
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentRequest'
        x-originalParamName: body
      responses:
        '200':
          description: OK
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: CreateEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/restore:
    get:
      description: Returns a paginated list of soft-deleted Pulumi ESC environments within an organization that are still within the retention window and eligible for restoration. Use the continuationToken query parameter for pagination. Deleted environments can be restored via the RestoreEnvironment endpoint.
      operationId: ListDeletedEnvironments
      parameters:
      - description: The organization name
        in: path
        name: orgName
        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/ListEnvironmentsResponse'
          description: OK
        '400':
          description: Invalid continuation token
        '404':
          description: not found
      summary: ListDeletedEnvironments
      tags:
      - Environments
    put:
      description: Restores a previously deleted Pulumi ESC environment within an organization. The request body specifies the environment to restore by its project and name. The environment must have been deleted within the retention window and not yet permanently purged. Returns 204 on success with no response body. Returns 404 if the deleted environment cannot be found.
      operationId: RestoreEnvironment
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreEnvironmentRequest'
        x-originalParamName: body
      responses:
        '204':
          description: No Content
        '404':
          description: not found
      summary: RestoreEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/tags:
    get:
      description: Returns a map of all unique tag names and their distinct values across all Pulumi ESC environments in the organization. The response is a map where each key is a tag name and the value is a list of all distinct values for that tag across all environments. This is useful for building tag-based filtering or discovery UIs.
      operationId: ListAllEnvironmentTags_esc
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  items:
                    type: string
                  type: array
                type: object
          description: successful operation
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: ListAllEnvironmentTags
      tags:
      - Environments
  /api/esc/environments/{orgName}/yaml/check:
    post:
      description: Checks a raw YAML environment definition for errors without creating or modifying any environment. The YAML definition is provided in the request body and validated for correctness, including imports, provider configurations, function invocations, and interpolation expressions. When the showSecrets query parameter is set to true, secret values are returned in plaintext in the response. This is useful for validating environment definitions before applying them.
      operationId: CheckYAML_esc
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: Whether to show secret values in plaintext
        in: query
        name: showSecrets
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: CheckYAML
      tags:
      - Environments
  /api/esc/environments/{orgName}/yaml/open:
    post:
      description: Opens an anonymous Pulumi ESC environment from a raw YAML definition provided in the request body, fully resolving all dynamic values, provider integrations, and secrets. Unlike OpenEnvironment, this does not require a pre-existing environment to be stored. The duration parameter specifies how long the session remains valid using Go duration format. Returns an OpenEnvironmentResponse containing the session ID. Use the session ID with ReadAnonymousOpenEnvironment to retrieve the resolved values.
      operationId: OpenYAML_esc
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: 'The session duration, using Go time units: ns, us, ms, s, m, h (e.g. ''2h'')'
        in: query
        name: duration
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenEnvironmentResponse'
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: OpenYAML
      tags:
      - Environments
  /api/esc/environments/{orgName}/yaml/open/{openSessionID}:
    get:
      description: Reads the fully resolved values from an anonymous open environment session that was created via the OpenYAML endpoint. The openSessionID path parameter must match a valid, non-expired session. The optional property query parameter accepts a dot-separated path to retrieve a specific nested value instead of the entire resolved environment (e.g., 'aws.credentials.accessKeyId'). The response contains the resolved configuration values with secrets decrypted.
      operationId: ReadAnonymousOpenEnvironment_esc
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The session ID returned from the open environment operation
        in: path
        name: openSessionID
        required: true
        schema:
          type: string
      - description: A dot-separated path to a specific property to retrieve from the environment
        in: query
        name: property
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: path
        '409':
          description: the environment has changed since it was read
      summary: ReadAnonymousOpenEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}:
    delete:
      description: Permanently deletes a Pulumi ESC environment and all of its revision history, tags, and associated configuration. This operation is blocked if deletion protection is enabled on the environment (see PatchEnvironmentSettings). Enterprise and Business Critical edition organizations may be able to restore deleted environments within a retention window. Returns 409 if the environment is deletion-protected or has been modified since it was last read.
      operationId: DeleteEnvironment_esc_environments
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read, or it's deletion-protected
      summary: DeleteEnvironment
      tags:
      - Environments
    get:
      description: Returns the YAML definition of a Pulumi ESC environment. The response is in application/x-yaml format and includes the environment's imports, values, provider configurations, and function invocations. Secrets remain in their encrypted form (use DecryptEnvironment to see plaintext secrets, or OpenEnvironment to fully resolve all dynamic values). When a version path parameter is provided, returns the definition for that specific revision.
      operationId: ReadEnvironment_esc_environments
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/x-yaml:
              schema:
                type: string
          description: OK
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: ReadEnvironment
      tags:
      - Environments
    head:
      description: Returns the ETag header for a Pulumi ESC environment without returning the full definition body. This is used for lightweight existence checks and for obtaining the current ETag value for optimistic concurrency control. The ETag should be included in subsequent update requests via the If-Match header to prevent concurrent modification conflicts. Returns 404 if the environment does not exist.
      operationId: HeadEnvironment_esc_environments
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: OK
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: HeadEnvironment
      tags:
      - Environments
    patch:
      description: Validates and updates the YAML definition of a Pulumi ESC environment. The request body must contain the complete environment definition in application/x-yaml format, including imports, values, provider configurations, and function invocations. Each successful update creates a new immutable revision in the environment's version history. Supports optimistic concurrency control via ETag/If-Match headers; returns 409 if the environment has been modified since it was last read.
      operationId: UpdateEnvironment_esc_environments
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-yaml:
            schema:
              type: string
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEnvironmentResponse'
          description: OK
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: UpdateEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/check:
    post:
      description: Checks a Pulumi ESC environment definition for errors without applying changes. This validates the YAML definition including imports, provider configurations, function invocations (fn::open, fn::secret, etc.), and interpolation expressions. When the showSecrets query parameter is set to true, secret values are returned in plaintext in the response. The response includes any diagnostics or validation errors found in the environment definition. Supports optimistic concurrency control via ETag headers.
      operationId: CheckEnvironment_esc_environments
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      - description: Whether to show secret values in plaintext
        in: query
        name: showSecrets
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckEnvironmentResponse'
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: revision tag
        '409':
          description: the environment has changed since it was read
      summary: CheckEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/clone:
    post:
      description: 'Creates a duplicate of a Pulumi ESC environment in a new project and/or under a new name. The request body specifies the destination project and environment name, along with options to control what is preserved during the clone: preserveAccess retains permission settings, preserveHistory retains the full revision history, preserveEnvironmentTags retains environment-level tags, and preserveRevisionTags retains version-specific tags. Environments cannot be renamed directly, so cloning is the mechanism for moving or renaming environments.'
      operationId: CloneEnvironment
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneEnvironmentRequest'
        x-originalParamName: body
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: CloneEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/decrypt:
    get:
      description: Reads the YAML definition for a Pulumi ESC environment with all static secrets decrypted and shown in plaintext. Unlike the standard ReadEnvironment endpoint which returns secrets in their encrypted form, this endpoint resolves fn::secret values to their plaintext representations. The response is returned in application/x-yaml format. This does not resolve dynamic provider values (fn::open); use OpenEnvironment for full resolution. Requires environment open permission.
      operationId: DecryptEnvironment_esc_environments
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/x-yaml:
              schema:
                type: string
          description: OK
        '400':
          description: Bad request
        '404':
          description: environment
        '409':
          description: the environment has changed since it was read
      summary: DecryptEnvironment
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/decrypt-secrets:
    post:
      description: Decrypts encrypted secret values in a Pulumi ESC environment definition. Takes an environment definition containing encrypted secrets and returns the same definition with those values decrypted to plaintext. This is useful for inspecting or migrating environment definitions that contain fn::secret values. Requires environment open permission. Returns 413 if the request content exceeds the maximum allowed size.
      operationId: DecryptEnvironmentSecrets
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecryptEnvironmentSecretsRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecryptEnvironmentSecretsResponse'
          description: OK
        '400':
          description: Invalid input
        '404':
          description: Organization or Environment not found
        '413':
          description: Request Content Too Large
      summary: DecryptEnvironmentSecrets
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/drafts:
    post:
      description: Creates a new draft change request for a Pulumi ESC environment. Drafts allow proposing changes to an environment definition that can be reviewed and approved before being applied. This is part of the approvals workflow for environments. Returns a ChangeRequestRef containing the draft identifier. Requires the Approvals feature to be enabled for the organization.
      operationId: CreateEnvironmentDraft
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeRequestRef'
          description: OK
        '400':
          description: Bad request
        '404':
          description: draft
        '409':
          description: the environment has changed since it was read
      summary: CreateEnvironmentDraft
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/drafts/{changeRequestID}:
    get:
      description: Reads the YAML definition for a draft version of a Pulumi ESC environment. Drafts are proposed changes created as part of the approvals workflow. The draft is identified by the changeRequestID path parameter. An optional revision query parameter can target a specific base revision. The response is returned in application/x-yaml format. Requires the Approvals feature to be enabled.
      operationId: ReadEnvironmentDraft
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      - description: The change request ID
        in: path
        name: changeRequestID
        required: true
        schema:
          type: string
      - description: The environment revision number to target
        in: query
        name: revision
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/x-yaml:
              schema:
                type: string
          description: OK
        '400':
          description: Invalid input
      summary: ReadEnvironmentDraft
      tags:
      - Environments
    patch:
      description: Updates the YAML definition of an existing draft change request for a Pulumi ESC environment. The draft is identified by the changeRequestID path parameter. The request body contains the updated YAML definition. Returns a ChangeRequestRef on success. Requires the Approvals feature to be enabled for the organization.
      operationId: UpdateEnvironmentDraft
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      - description: The change request ID
        in: path
        name: changeRequestID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeRequestRef'
          description: OK
        '400':
          description: Bad request
        '404':
          description: draft
        '409':
          description: the environment has changed since it was read
      summary: UpdateEnvironmentDraft
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/drafts/{changeRequestID}/open:
    post:
      description: Opens a draft version of a Pulumi ESC environment, fully resolving all dynamic values, provider integrations, and secrets for the proposed changes. The duration parameter specifies how long the open session remains valid using Go duration format (e.g., '2h', '30m'). An optional revision parameter can target a specific base revision. Returns an OpenEnvironmentResponse containing the session ID for subsequent reads. Requires the Approvals feature.
      operationId: OpenEnvironmentDraft
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      - description: The change request ID
        in: path
        name: changeRequestID
        required: true
        schema:
          type: string
      - description: 'The session duration, using Go time units: ns, us, ms, s, m, h (e.g. ''2h'')'
        in: query
        name: duration
        schema:
          type: string
      - description: The environment revision number to target
        in: query
        name: revision
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenEnvironmentResponse'
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: Change Request
        '409':
          description: the environment has changed since it was read
      summary: OpenEnvironmentDraft
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/encrypt-secrets:
    post:
      description: Encrypts plaintext secret values in a Pulumi ESC environment definition. Takes an environment definition containing plaintext secrets and returns the same definition with those values encrypted using the environment's encryption key. This is useful for preparing environment definitions that contain sensitive values before storing or updating them. Returns 413 if the request content exceeds the maximum allowed size.
      operationId: EncryptEnvironmentSecrets
      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 environment name
        in: path
        name: envName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptEnvironmentSecretsRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptEnvironmentSecretsResponse'
          description: OK
        '400':
          description: Invalid input
        '404':
          description: Organization or Environment not found
        '413':
          description: Request Content Too Large
      summary: EncryptEnvironmentSecrets
      tags:
      - Environments
  /api/esc/environments/{orgName}/{projectName}/{envName}/hooks:
    get:
      description: Returns a list of all webhooks configured for a Pulumi ESC environment. Each webhook entry includes its name, destination URL, event filters, format, and active status. Webhooks enable external services to be notified of environment events such as updates and opens.
      operationId: ListWebhooks_esc_environments
      parameters:
      - description: The organization n

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