Environments

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.

Request Parameters

• continuationToken string query optional
  Continuation token for paginated results
• includeReferrerMetadata boolean query optional
  Whether to include referrer metadata. Defaults to false.
• maxResults integer query optional
  Maximum number of results for pagination
• organization string query optional
  Filter results to this organization name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• continuationToken string query optional
  Continuation token for paginated results
• includeReferrerMetadata boolean query optional
  Whether to include referrer metadata. Defaults to false.
• maxResults integer query optional
  Maximum number of results for pagination
• roleID string query optional
  The custom role to use for listing environments

Responses

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.

Request Parameters

• orgName string path required
  The organization name

Request Body

• project string required
  The project name for the environment.
• name string required
  The name of the environment.

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• showSecrets boolean query optional
  Whether to show secret values in plaintext

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• project string optional
  Target project for the cloned environment. If omitted, uses the source project.
• name string required
  Name for the newly cloned environment.
• version integer optional
  Specific version of the source environment to clone. If omitted, clones the latest version.
• preserveHistory boolean optional
  Whether to copy the revision history from the source environment.
• preserveAccess boolean optional
  Whether to copy access control settings from the source environment.
• preserveEnvironmentTags boolean optional
  Whether to copy environment-level tags from the source environment.
• preserveRevisionTags boolean optional
  Whether to copy revision-level tags from the source environment.

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• ciphertexts array[string] required
  The list of encrypted ciphertext values to decrypt.

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• changeRequestID string path required
  The change request ID
• revision integer query optional
  The environment revision number to target

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• changeRequestID string path required
  The change request ID

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• changeRequestID string path required
  The change request ID
• duration string query optional
  The session duration, using Go time units: ns, us, ms, s, m, h (e.g. ‘2h’)
• revision integer query optional
  The environment revision number to target

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• plaintexts array[string] required
  The list of plaintext values to encrypt.

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

Creates a new webhook for a Pulumi ESC environment. Webhooks allow external services to be notified when environment events occur, such as updates or opens. The request body specifies the webhook configuration including the destination URL, event filters, and format. Returns 400 if the organization name in the request body does not match the URL path parameter. Returns 409 if a webhook with the same name already exists.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• organizationName string required
  The organization that owns this webhook.
• projectName string optional
  The project name. Set when the webhook is scoped to a specific stack.
• stackName string optional
  The stack name. Set when the webhook is scoped to a specific stack.
• envName string optional
  The environment name. Set when the webhook is scoped to a specific environment.
• name string required
  The unique identifier name for the webhook within its scope.
• displayName string required
  The human-readable display name shown in the UI.
• payloadUrl string required
  The URL to which webhook payloads are delivered.
• secret string optional
  Secret will be omitted when returned from the service.
• active boolean required
  Whether the webhook is active and will receive deliveries.
• format string optional
  The format of the webhook payload (e.g., ‘raw’, ‘slack’, ‘ms_teams’).
• filters array[string] optional
  Specific event types this webhook subscribes to. If empty, all events are delivered.
• groups array[string] optional
  Event groups this webhook subscribes to (e.g., ‘stacks’, ‘deployments’).

Responses

Returns the configuration and status of a single webhook for a Pulumi ESC environment. The webhook is identified by its name in the URL path. The response includes the webhook’s destination URL, event filters, format, and active status. Returns 404 if the webhook does not exist.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• hookName string path required
  The webhook name

Responses

Updates the configuration of an existing webhook on a Pulumi ESC environment. The webhook is identified by its name in the URL path. The request body contains the updated webhook configuration including destination URL, event filters, format, and active status. Returns the updated WebhookResponse on success. Returns 400 if an invalid format is specified.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• hookName string path required
  The webhook name

Request Body

• organizationName string required
  The organization that owns this webhook.
• projectName string optional
  The project name. Set when the webhook is scoped to a specific stack.
• stackName string optional
  The stack name. Set when the webhook is scoped to a specific stack.
• envName string optional
  The environment name. Set when the webhook is scoped to a specific environment.
• name string required
  The unique identifier name for the webhook within its scope.
• displayName string required
  The human-readable display name shown in the UI.
• payloadUrl string required
  The URL to which webhook payloads are delivered.
• secret string optional
  Secret will be omitted when returned from the service.
• active boolean required
  Whether the webhook is active and will receive deliveries.
• format string optional
  The format of the webhook payload (e.g., ‘raw’, ‘slack’, ‘ms_teams’).
• filters array[string] optional
  Specific event types this webhook subscribes to. If empty, all events are delivered.
• groups array[string] optional
  Event groups this webhook subscribes to (e.g., ‘stacks’, ‘deployments’).

Responses

Deletes a webhook from a Pulumi ESC environment. The webhook is identified by its name in the URL path. After deletion, the external service will no longer receive notifications for environment events. Returns 204 on success with no response body.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• hookName string path required
  The webhook name

Responses

Returns a list of recent delivery attempts for a specific webhook on a Pulumi ESC environment. Each delivery record includes the HTTP status code, response body, timestamp, and whether the delivery was successful. This is useful for debugging webhook integration issues and verifying that events are being received.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• hookName string path required
  The webhook name

Responses

Triggers the Pulumi Service to redeliver a specific event to a webhook on a Pulumi ESC environment. This is useful for resending events that the webhook endpoint failed to process on the initial delivery attempt (e.g., due to temporary downtime or errors). The event is identified by its delivery event ID in the URL path. Returns the new WebhookDelivery record for the redelivery.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• hookName string path required
  The webhook name
• event string path required
  The webhook delivery event ID to redeliver

Responses

Sends a test ping event to a webhook on a Pulumi ESC environment to verify that the webhook endpoint is reachable and functioning correctly. This bypasses the normal message queue and issues the request directly to the webhook URL. Returns the WebhookDelivery record containing the HTTP status code and response from the target endpoint.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• hookName string path required
  The webhook name

Responses

Returns metadata for a Pulumi ESC environment, including the calling user’s effective permission level (read, open, write, admin), creation and modification timestamps, the environment’s project, and other administrative information. This is useful for determining what actions the current user can perform on the environment before attempting those operations.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

Opens a Pulumi ESC environment, fully resolving all dynamic values, provider integrations (fn::open), interpolation expressions, and secrets. This initiates an access session that evaluates the complete environment definition including all imports. The duration parameter specifies how long the session remains valid using Go duration format (e.g., ‘2h45m’, ‘300ms’). Returns an OpenEnvironmentResponse containing the session ID and any diagnostics. Use the session ID with ReadOpenEnvironment to retrieve the resolved values.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• duration string query optional
  The session duration, using Go time units: ns, us, ms, s, m, h (e.g. ‘2h’)

Responses

Reads the fully resolved values from an open environment session that was created via the OpenEnvironment 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 all resolved configuration values with secrets decrypted and provider-sourced values fully evaluated.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• openSessionID string path required
  The session ID returned from the open environment operation
• property string query optional
  A dot-separated path to a specific property to retrieve from the environment

Responses

Creates an open request for a Pulumi ESC environment that has gated opens enabled. When an environment has open gates configured, opening the environment requires an approval workflow. This endpoint initiates that process by creating an open request, and also creates corresponding open requests for each imported environment that has open gates. Requires the Approvals feature to be enabled for the organization. Returns 400 if the environment does not have gated opens.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• grantExpirationSeconds integer required
  Time from application of the request until the resulting grant expires
• accessDurationSeconds integer required
  Total duration that the resulting grant can be used to access the environment open endpoint (after first open)

Responses

Reads the details of an open environment request that was created as part of the gated opens approval workflow. The request is identified by the changeRequestID path parameter. The response includes the request’s status, the requesting user, and approval details. An optional revision query parameter can target a specific environment revision. Requires the Approvals feature to be enabled.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• changeRequestID string path required
  The change request ID
• revision integer query optional
  The environment revision number to target

Responses

Updates an existing open environment request that was created as part of the gated opens approval workflow. The request is identified by the changeRequestID path parameter. The request body contains the updated open request details, such as approval status. Returns a ChangeRequestRef on success. Requires the Approvals feature to be enabled for the organization.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• changeRequestID string path required
  The change request ID

Request Body

• grantExpirationSeconds integer required
  Time from application of the request until the resulting grant expires
• accessDurationSeconds integer required
  Total duration that the resulting grant can be used to access the environment open endpoint (after first open)

Responses

Changes the ownership of the specified environment to the provided user. Returns the identity of the previous owner.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• name string required
  The user’s display name.
• githubLogin string required
  The user’s login name.
• avatarUrl string required
  The URL of the user’s avatar image.
• email string optional
  IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.

Responses

Returns a paginated list of entities that reference a Pulumi ESC environment, including other environments that import it and Pulumi stacks that use it in their configuration. The count parameter limits results (range 1-500). Set allRevisions to true to include references across all revisions, and latestStackVersionOnly to true to return only the latest stack version for each referring stack. Use continuationToken for pagination.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• allRevisions boolean query optional
  Whether to include all revisions
• continuationToken string query optional
  Continuation token for paginated results
• count integer query optional
  Maximum number of results to return
• latestStackVersionOnly boolean query optional
  Whether to return only the latest stack version

Responses

Triggers secret rotation for a Pulumi ESC environment. This evaluates all fn::rotate declarations in the environment definition and rotates the corresponding secrets in their external systems (e.g., rotating database passwords, API keys, or cloud credentials). Requires the secret rotation feature to be enabled for the organization. Returns 409 if the environment has been modified since it was last read.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• paths array[string] required
  The paths of the secrets to rotate.

Responses

Returns the secret rotation history for a Pulumi ESC environment. Each entry represents a rotation event where secrets defined with fn::rotate were cycled to new values in their external systems. The response includes timestamps, outcomes, and the rotators involved. Requires the secret rotation feature to be enabled for the organization.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

Returns all scheduled actions configured for a Pulumi ESC environment. Schedules automate recurring operations such as secret rotation. The response includes each schedule’s timing configuration, action type, and current status (active or paused).

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

Creates a new scheduled action for a Pulumi ESC environment. Schedules can be used to automate recurring operations on environments, such as secret rotation. The request body specifies the schedule timing and the action to perform. Returns the created ScheduledAction on success. Requires the secret rotation feature to be enabled for the organization.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• scheduleCron string optional
  The schedule cron
• scheduleOnce string optional
  The schedule once
• secretRotationRequest CreateEnvironmentSecretRotationScheduleRequest optional
  The secret rotation request
• ↳ environmentPath string required
  Environment Path specifies a path to a rotated secret to be updated Leave the field blank to rotate ALL rotated secrets in an environment

Responses

Returns the details of a specific scheduled action for a Pulumi ESC environment. The schedule is identified by the scheduleID path parameter. The response includes the schedule’s timing configuration (cron expression or one-time), the action to perform, and the current status (active or paused).

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• scheduleID string path required
  The schedule ID

Responses

Updates the configuration of a scheduled action for a Pulumi ESC environment. The schedule is identified by the scheduleID path parameter. The request body specifies the updated timing and action configuration. Changes take effect for future executions only; any currently running execution is not affected. Returns the updated ScheduledAction on success.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• scheduleID string path required
  The schedule ID

Request Body

• scheduleCron string optional
  The schedule cron
• scheduleOnce string optional
  The schedule once
• secretRotationRequest CreateEnvironmentSecretRotationScheduleRequest optional
  The secret rotation request
• ↳ environmentPath string required
  Environment Path specifies a path to a rotated secret to be updated Leave the field blank to rotate ALL rotated secrets in an environment

Responses

Permanently deletes a scheduled action from a Pulumi ESC environment. This removes the schedule and cancels any future executions. The schedule is identified by its scheduleID. Requires the secret rotation feature to be enabled for the organization.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• scheduleID string path required
  The schedule ID

Responses

Returns the execution history for a specific scheduled action on a Pulumi ESC environment. Each history entry includes the execution timestamp, outcome (success or failure), and any error details. This is useful for monitoring the reliability of automated operations like secret rotation.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• scheduleID string path required
  The schedule ID

Responses

Pauses a scheduled action on a Pulumi ESC environment, preventing any future executions until the schedule is resumed. The schedule’s configuration is preserved and can be reactivated via the ResumeEnvironmentSchedule endpoint. This is useful for temporarily disabling automated operations like secret rotation without deleting the schedule.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• scheduleID string path required
  The schedule ID

Responses

Resumes a previously paused scheduled action on a Pulumi ESC environment, re-enabling future executions. The schedule will continue from its next scheduled time according to its configured timing (cron expression or one-time schedule). The schedule is identified by the scheduleID path parameter.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• scheduleID string path required
  The schedule ID

Responses

Returns the current settings for a Pulumi ESC environment, including whether deletion protection is enabled. Deletion protection prevents the environment from being deleted until the setting is explicitly disabled. Settings can be modified via the PatchEnvironmentSettings endpoint.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Responses

Updates settings for a Pulumi ESC environment using a partial update (patch) approach. Currently supports toggling deletion protection via the deletionProtected field. When deletionProtected is set to true, the environment cannot be deleted until the setting is explicitly disabled. Only the fields included in the request body are modified; omitted fields retain their current values.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• deletionProtected boolean optional
  DeletionProtected indicates whether deletion protection should be enabled for this environment. Null means no change.

Responses

Returns a paginated list of user-defined tags for a Pulumi ESC environment. Tags are key-value pairs used for organizing and categorizing environments. Use the after parameter for cursor-based pagination and count to limit the number of results returned.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• after integer query optional
  Only return results after this value
• count integer query optional
  Maximum number of results to return

Responses

Adds a new user-defined tag to a Pulumi ESC environment. Tags are key-value pairs that provide contextual metadata for organizing and searching environments (e.g., region=us-east-1, team=platform). The tag name and value are provided in the request body. Returns the created EnvironmentTag on success. Returns 409 if a tag with the same name already exists on the environment.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• name string required
  The name
• value string required
  The value

Responses

Returns a single user-defined tag for a Pulumi ESC environment, identified by the tag name in the URL path. The response includes the tag name, value, and metadata. Returns 404 if the tag does not exist on the environment.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• tagName string path required
  The environment tag name

Responses

Modifies the value of an existing user-defined tag on a Pulumi ESC environment. The tag is identified by its name in the URL path. The request body contains the new value for the tag. Returns the updated EnvironmentTag on success. Returns 404 if the tag does not exist on the environment.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• tagName string path required
  The environment tag name

Request Body

• currentTag UpdateEnvironmentTagRequestCurrentTag required
  The current tag value to match for optimistic concurrency control.
• ↳ value string required
  The current tag value.
• newTag UpdateEnvironmentTagRequestNewTag required
  The new tag name and value to set.
• ↳ name string optional
  The new tag name.
• ↳ value string optional
  The new tag value.

Responses

Removes a user-defined tag from a Pulumi ESC environment. The tag is identified by its name in the URL path. Returns 204 on success with no response body. Returns 404 if the tag does not exist on the environment.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• tagName string path required
  The environment tag name

Responses

Returns a paginated list of revisions for a Pulumi ESC environment. Each revision represents an immutable snapshot of the environment definition created when the environment is updated. The response includes revision numbers, timestamps, and the identity of the user who made each change. Use the before parameter to fetch revisions before a specific revision number, and count to limit the number of results returned.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• before integer query optional
  Only return results before this revision
• count integer query optional
  Maximum number of results to return

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number
• showSecrets boolean query optional
  Whether to show secret values in plaintext

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number

Responses

Opens a Pulumi ESC environment, fully resolving all dynamic values, provider integrations (fn::open), interpolation expressions, and secrets. This initiates an access session that evaluates the complete environment definition including all imports. The duration parameter specifies how long the session remains valid using Go duration format (e.g., ‘2h45m’, ‘300ms’). Returns an OpenEnvironmentResponse containing the session ID and any diagnostics. Use the session ID with ReadOpenEnvironment to retrieve the resolved values.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number
• duration string query optional
  The session duration, using Go time units: ns, us, ms, s, m, h (e.g. ‘2h’)

Responses

Returns a paginated list of entities that reference a Pulumi ESC environment, including other environments that import it and Pulumi stacks that use it in their configuration. The count parameter limits results (range 1-500). Set allRevisions to true to include references across all revisions, and latestStackVersionOnly to true to return only the latest stack version for each referring stack. Use continuationToken for pagination.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number
• allRevisions boolean query optional
  Whether to include all revisions
• continuationToken string query optional
  Continuation token for paginated results
• count integer query optional
  Maximum number of results to return
• latestStackVersionOnly boolean query optional
  Whether to return only the latest stack version

Responses

Retracts a specific revision of a Pulumi ESC environment, marking it as withdrawn. A retracted revision remains in the history but is no longer considered a valid version for use. The request body may include a reason for the retraction. The revision is identified by the version path parameter. Returns 204 on success with no response body.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number

Request Body

• replacement integer optional
  The revision number to use as a replacement, if any.
• reason string optional
  The reason for retracting the revision.

Responses

Returns a paginated list of revision tags for a Pulumi ESC environment. Revision tags are named references pointing to specific revision numbers (e.g., ’latest’, ‘prod’, ‘stable’). They can be used in environment imports and Pulumi stack configuration to pin to a specific version. Use the after parameter for cursor-based pagination and count to limit results.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• version string path required
  The revision version number
• after string query optional
  Only return results after this value
• count integer query optional
  Maximum number of results to return

Responses

Returns a paginated list of revision tags for a Pulumi ESC environment. Revision tags are named references pointing to specific revision numbers (e.g., ’latest’, ‘prod’, ‘stable’). They can be used in environment imports and Pulumi stack configuration to pin to a specific version. Use the after parameter for cursor-based pagination and count to limit results.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• after string query optional
  Only return results after this value
• count integer query optional
  Maximum number of results to return

Responses

Creates a new revision tag for a Pulumi ESC environment. Revision tags are named references that point to specific revision numbers, similar to Git tags. They allow pinning a stable reference to a known-good version of an environment. Tagged versions can be used in imports and Pulumi stack configuration (e.g., myproject/env@prod) to ensure stable references unaffected by subsequent changes. The built-in ’latest’ tag always points to the most recent revision.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name

Request Body

• name string required
  The name
• revision integer optional
  The revision

Responses

Returns the details of a specific revision tag for a Pulumi ESC environment. The tag is identified by its name in the URL path. The response includes the tag name and the revision number it points to. Returns 404 if the tag does not exist.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• tagName string path required
  The revision tag name

Responses

Updates an existing revision tag for a Pulumi ESC environment to point to a different revision number. The tag is identified by its name in the URL path. The request body specifies the new revision number. This allows advancing or rolling back a named reference (e.g., moving the ‘prod’ tag to a newer or older revision). Returns 204 on success with no response body.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• tagName string path required
  The revision tag name

Request Body

• revision integer optional
  The revision number to associate with the tag.

Responses

Deletes a named revision tag from a Pulumi ESC environment. The tag is identified by its name in the URL path. After deletion, any imports or stack configurations referencing this tag will fail to resolve. The built-in ’latest’ tag cannot be deleted. Returns 204 on success with no response body.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• envName string path required
  The environment name
• tagName string path required
  The revision tag name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• continuationToken string query optional
  Continuation token for paginated results

Responses

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.

Request Parameters

• orgName string path required
  The organization name

Request Body

• deletionTimestamp string required
  The ISO 8601 timestamp of the environment’s deletion, used to identify which deleted version to restore.
• project string required
  The project name for the environment.
• name string required
  The name of the environment.

Responses

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.

Request Parameters

• orgName string path required
  The organization name

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• showSecrets boolean query optional
  Whether to show secret values in plaintext

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• duration string query optional
  The session duration, using Go time units: ns, us, ms, s, m, h (e.g. ‘2h’)

Responses

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.

Request Parameters

• orgName string path required
  The organization name
• openSessionID string path required
  The session ID returned from the open environment operation
• property string query optional
  A dot-separated path to a specific property to retrieve from the environment

Responses

Returns a list of all available Pulumi ESC providers. Providers are integrations that dynamically retrieve configuration and secrets from external sources (e.g., AWS, Azure, Google Cloud, HashiCorp Vault, 1Password) via the fn::open function in environment definitions. Optionally filter by organization using the orgName query parameter to see only providers available to that organization.

Request Parameters

• orgName string query optional
  Filter providers available to this organization

Responses

Returns the JSON schema for a Pulumi ESC provider. Providers are integrations that dynamically retrieve configuration and secrets from external sources such as AWS, Azure, Google Cloud, HashiCorp Vault, and others via fn::open. The schema describes the provider’s input parameters, output structure, and configuration options. The provider is identified by name in the URL path.

Request Parameters

• providerName string path required
  The provider name

Responses

Returns a list of all available Pulumi ESC secret rotators. Rotators are integrations that automatically rotate secrets in external systems via the fn::rotate function in environment definitions. Optionally filter by organization using the orgName query parameter to see only rotators available to that organization.

Request Parameters

• orgName string query optional
  Filter rotators available to this organization

Responses

Returns the JSON schema for a Pulumi ESC secret rotator. Rotators are integrations that automatically rotate secrets in external systems via fn::rotate. The schema describes the rotator’s input parameters, output structure, and configuration options. The rotator is identified by name in the URL path.

Request Parameters

• rotatorName string path required
  The rotator name

Responses