# Docs

- Home
  - [Welcome](/): Getting started with your API portal
- API Reference
  - Approval Policy: Approval Policy endpoints
    - [Assign Approval Policy To Scope](/api/env-zero/approval-policy/templates-assign-approval-policy): Assigns an approval policy to a scope, so deployments there are evaluated against it after the plan and cost estimation steps. `blueprintId` identifies the policy and `scope` with `scopeId` identifies the target. Returns the created assignment.
    - [Get Approval Policy Assignments By Scope](/api/env-zero/approval-policy/templates-get-approval-policy-by-scope): Returns the approval policy assignments in force at the given scope, so a caller can tell whether a deployment it is about to trigger will require approval.
    - [List Approval Policies](/api/env-zero/approval-policy/templates-find-all-approval-policies): Returns all approval policies associated with an organization.
  - Bulk Operations: Bulk Operations
    - [Bulk add environment tags](/api/env-zero/bulk-operations/bulk-operations-bulk-add-tags): Applies the same tags to every selected environment - a key that already exists has its values replaced wholesale, and keys that are not listed are left untouched
    - [Bulk archive](/api/env-zero/bulk-operations/bulk-operations-bulk-archive): Marks each of the given environments as inactive. Returns an `operationId`; poll `GET /bulk-operations/{operationId}` for the per-environment outcome.
    - [Bulk deploy](/api/env-zero/bulk-operations/bulk-operations-bulk-deploy): Triggers a deployment on each of the given environments, using the shared deployment options in `data`. Returns an `operationId`; poll `GET /bulk-operations/{operationId}` for the per-environment outcome. Environments the caller cannot deploy are reported there rather than failing the request.
    - [Bulk destroy](/api/env-zero/bulk-operations/bulk-operations-bulk-destroy): Destroys each of the given environments, using the shared options in `data`. Returns an `operationId`; poll `GET /bulk-operations/{operationId}` for the per-environment outcome. This is destructive and affects every listed environment.
    - [Bulk lock](/api/env-zero/bulk-operations/bulk-operations-bulk-lock): Locks each of the given environments, using the shared lock options in `data`, preventing deploy, destroy, plan and drift detection from running on them. Returns an `operationId`; poll `GET /bulk-operations/{operationId}` for the per-environment outcome.
    - [Bulk remove environment tags](/api/env-zero/bulk-operations/bulk-operations-bulk-remove-tags): Removes the listed tag keys, values and all, from every selected environment - a key an environment does not carry is a no-op
    - [Bulk run task](/api/env-zero/bulk-operations/bulk-operations-bulk-run-task): Runs a task on each of the given environments, using the shared task options in `data`. Returns an `operationId`; poll `GET /bulk-operations/{operationId}` for the per-environment outcome.
    - [Bulk unlock](/api/env-zero/bulk-operations/bulk-operations-bulk-unlock): Unlocks each of the given environments. Returns an `operationId`; poll `GET /bulk-operations/{operationId}` for the per-environment outcome.
    - [Get bulk operation](/api/env-zero/bulk-operations/bulk-operations-get-bulk-operation): Returns the per-environment status of a bulk operation - only the user who triggered it may read it
  - Configuration: This API covers all deployment Configuration including: Variables, Tokens, SSH Keys and Deployment Credentials
    - [Find sets assigned to scope](/api/env-zero/configuration/configuration-find-set-assignments-by-scope): Returns the configuration sets assigned to the given scope.
    - [Assign sets to entity](/api/env-zero/configuration/configuration-assign-configuration-sets-to-scope): Assigns the configuration sets named in `setIds` to the given scope, so their variables apply to deployments there. Returns no content.
    - [List Sets created by Scope](/api/env-zero/configuration/configuration-find-sets-by-creation-scope): Returns the configuration sets created at the given scope. Set `includeHigherScopes` to also return sets created at scopes above it.
    - [Create a configuration set](/api/env-zero/configuration/configuration-create-configuration-set): Creates a configuration set - a reusable, named group of variables that can be assigned to templates, projects or environments. `name`, `scope` and `scopeId` are required. Returns the created set.
    - [List Variables by Scope](/api/env-zero/configuration/configuration-find-variables-by-scope): Lists all variables for the provided scope(s).
If more than one scope is given - variables will be overridden by lower level scopes - just like env zero does.
For example - Provided both organizationId and projectId,
if a variable exists on both scopes, a single instance of it will be returned, with its Project scope value
    - [Create or update variable](/api/env-zero/configuration/configuration-create-or-update-variable): Creates or updates configuration variables. Variables are resolved through env zero's scope hierarchy, so a variable set at a lower scope overrides the same variable set higher up. Returns the resulting variables.
    - [Query configuration variable by id](/api/env-zero/configuration/configuration-find-variable-by-id): Returns a single configuration variable by id, including its scope, type, value, and whether it is sensitive, read-only or required. The value of a sensitive variable is not returned.
    - [Delete a variable](/api/env-zero/configuration/configuration-delete-variable): Deletes a configuration variable by id.
  - Credentials: Authentication against the env zero API is done via API Keys.

An API Key is created by an organization administrator, but is not connected to any specific user when it's being used. 

More on https://docs.envzero.com/reference/authentication
    - [List Organization API Keys](/api/env-zero/credentials/credentials-find-all-api-keys): Returns the API keys of an organization, with their roles, creators and last-used times. Key secrets are not returned.
    - [Create API Key](/api/env-zero/credentials/credentials-create-api-key): Creates an API key for an organization. `name` and `organizationId` are required; `permissions` scopes the key below organization admin and `readOnly` restricts it to reads. The response contains `apiKeySecret`, which is returned only on creation and cannot be retrieved afterwards.
  - Deployment Logs: env zero deployment consists of steps such as Init Variables
using this API you can retrieve information about those steps
    - [Find all steps by Deployment Id](/api/env-zero/deployment-logs/deployment-logs-find-by-deployment-log-id): Returns the steps of a deployment, such as variable initialisation, plan and apply. Use the step names returned here to fetch an individual step's log.
    - [Get logs for specific step](/api/env-zero/deployment-logs/deployment-logs-find-step-log): Returns the log events of one deployment step. The response carries `nextStartTime` and `hasMoreLogs`, so a step that is still running, or whose log is long, is read by repeating the call until `hasMoreLogs` is false.
  - Drift: API for reading drift causes detected across an organization.
    - [Get Drift Causes](/api/env-zero/drift/drift-get-drift-causes): Returns the drift causes detected across an organization, grouped by root cause rather than by environment, so a single cause affecting many environments is reported once with the full list of environments it affects. Each group carries its `causeKind`, the `causeKeyParts` identifying what changed (the shape of which varies by kind), when it was first and last seen, and the affected environments. Narrow the result to specific projects with `projectIds`.
    - [Get Drift Fix Stats](/api/env-zero/drift/drift-get-drift-fix-stats): Returns how long drift causes have been taking to resolve across an organization: the median fix duration in milliseconds, the number of resolved causes the median was computed from, and the trailing window used. The window defaults to 90 days and is capped at 365. `medianFixDurationInMillis` is null when no causes closed within the window.
    - [Get Ignored Drift Causes](/api/env-zero/drift/drift-get-ignored-drift-causes): Returns the drift causes that have been marked as ignored for an organization, in the same grouped-by-cause form as `GET /drift-causes`. Ignoring is recorded per environment, so a cause appears here only for the environments where it was ignored.
    - [Ignore Drift Cause](/api/env-zero/drift/drift-ignore-drift-cause): Marks a drift cause as ignored on the given environments, so it stops being reported as outstanding. Ignoring applies per environment and does not expire: it does not silence the cause on environments not listed, and the cause returns if a new environment develops it. The response reports which environment ids were ignored and which were skipped, with a reason for each skip.
    - [Un-ignore Drift Cause](/api/env-zero/drift/drift-un-ignore-drift-cause): Reverses an ignore, so the drift cause is reported as outstanding again on the given environments. The cause reappears after the next drift detection run confirms the drift is still present. The response reports which environment ids were un-ignored and which were skipped, with a reason for each skip.
  - Environment Outputs: control environments state access configurations
    - [Get environment state access configuration](/api/env-zero/environment-outputs/environment-outputs-get-state-access-config): Describe which environments, or projects in the organization may access a given environment's state
  - Environments: An environment is an entity representing a deployment managed by env zero.

Your users manage their environments in env zero in Projects.
They can create, destroy, and redeploy environments.

More on https://docs.envzero.com/docs/environments
    - [Abort Deployment](/api/env-zero/environments/environments-abort): Aborts a deployment that is already running. Returns no content. Aborting a run mid-apply can leave cloud resources partially applied.
    - [Cancel Deployment](/api/env-zero/environments/environments-cancel): Cancels a deployment that is queued or waiting for approval, before it starts applying. Returns the deployment id.
    - [Count Environments](/api/env-zero/environments/environments-count-by-project): Returns the number of environments in a project as a bare number, optionally restricted by active state and status. Useful for checking a project against its environment limit without fetching the environments themselves.
    - [List Environments](/api/env-zero/environments/environments-find-all): Returns the environments the caller may view, filtered by any combination of the supported query parameters - organization, project, name, drift status, tags, active and destroyed state, workspace name, and free-text search. Results are paginated with `limit` (maximum and default 100) and `offset`, so a large fleet must be read page by page. Use `excludeFields` to omit expensive fields such as the latest deployment log.
    - [Create Environment](/api/env-zero/environments/environments-create): Creates an environment in a project and triggers its first deployment. `name`, `projectId` and `deployRequest` are required; the remaining fields set the environment's TTL, tags, variable and configuration-set changes, continuous deployment and pull-request behaviour, drift detection, and remote backend settings at creation time. Returns the created environment.
    - [List Deployments](/api/env-zero/environments/environments-find-deployment-logs-by-environment-id): Returns the deployment logs of an environment, most useful for distinguishing deploy, destroy and drift-detection runs and for finding the drift-detection deployment that a drift cause refers to. Filter by date range, deployment type, status and deploying user; paginate with `limit` (maximum and default 100) and `offset`.
    - [Deploy Environment](/api/env-zero/environments/environments-deploy): Triggers a deployment of an environment and returns the resulting deployment log. The request body selects what to deploy and how - the deployment type, the template revision or repository, variable and configuration-set changes, targeted resources, a TTL, an approval requirement, and the automatic drift remediation strategy. Deployment is asynchronous: poll `GET /environments/deployments/{id}` for the outcome.
    - [Destroy Environment](/api/env-zero/environments/environments-destroy): Destroys the cloud resources of an environment, returning the id of the destroy deployment. The query parameters control whether updated code is checked out, which revision is used, whether state refresh is skipped, whether the run counts as scheduled, and whether the destroy requires approval. This is destructive and is refused when destroy protection is enabled for the environment.
    - [Download Deployment Plan JSON](/api/env-zero/environments/environments-get-deployment-plan-json): Downloads the complete Terraform/OpenTofu plan JSON (the output of 'show -json') of the given deployment,
including resources with no changes - unlike the parsed plan returned by 'GET /environments/deployments/{id}?fields=plan',
which contains only changed resources. Intended for external policy evaluation (for example Checkov).

Responses:
  * 302 (default) - the 'Location' header holds a short-lived (5 minutes) signed download URL. Follow the
    redirect to download the file, for example with 'curl -L'.
  * 200 - only when 'redirect=false' is passed: the same signed URL is returned as a JSON body ({ "url": "..." })
    instead of a redirect. Browser clients should prefer this, since following the 302 with a cross-origin
    request that carries custom headers triggers a CORS preflight against the storage bucket.
  * 404 - the deployment does not exist, or no plan JSON is available for it (see below).
  * 403 - the caller is not allowed to view the deployment's environment.

NOTE: the generated schema below documents only the 200 response body; the default response of this endpoint
is the 302 described above.

Sensitive values are masked: anything Terraform marks as sensitive is replaced with '<sensitive>', and values
of sensitive env zero variables are redacted. Expect masked placeholders rather than real secrets in the file.

A plan JSON is available only when all of the following hold, otherwise the endpoint returns 404:
  * the deployment is a deploy, destroy, or dry run - drift detection, PR plan and remote plan deployments do not produce one
  * the template is Terraform, OpenTofu or Terragrunt (Terragrunt run-all is not supported)
  * the deployment reached and completed its plan step
  * the deployment ran on an agent version that supports the feature (self-hosted agents may need an upgrade)
  * the deployment is less than 30 days old - plan JSON files are retained for 30 days and then deleted
    - [Find deployment drift status](/api/env-zero/environments/environments-find-deployment-drift-status): Returns the drift status recorded for a drift-detection deployment, including the deployment log itself, the date of the cloud change events currently held for it, and the status of the event scan that produced them.
    - [Get a drifted resource's event details](/api/env-zero/environments/environments-get-drifted-resource-event-details): Returns the full detail of one cloud change event on a drifted resource, for inspecting exactly what changed outside of env zero.
    - [Get a drifted resource's events](/api/env-zero/environments/environments-get-drifted-resource-events): Returns the cloud change events recorded against a single drifted resource of a drift-detection deployment, together with the time window the events cover.
    - [Get Deployment](/api/env-zero/environments/environments-find-deployment-log-by-id): Returns a deployment log by id, including its type, status, timings, output, and any error and failed command. Use `fields` or `exclude_fields` to narrow the response - for example requesting only the plan. Poll this to follow an asynchronous deployment to completion.
    - [Resume Deployment](/api/env-zero/environments/environments-resume): Resumes a deployment that is waiting for user approval, letting the apply proceed. Returns the deployment id.
    - [Get Environment](/api/env-zero/environments/environments-find-by-id): Returns a single environment by id, including its status, drift status, lock state, tags, TTL, and latest deployment log. Use `fields` or `exclude_fields` to narrow the response.
    - [Update Environment](/api/env-zero/environments/environments-update): Updates an environment's settings - its name, approval requirement, archived state, continuous deployment and pull-request plan behaviour, and remote backend and remote apply flags. Fields left out are unchanged. Returns the updated environment.
    - [Get Environments Outputs](/api/env-zero/environments/environments-get-environments-outputs): Returns the deployment outputs of the environments in a project, keyed by environment, so that one environment's outputs can be consumed as another's inputs.
    - [Get Plan Impact For Deployments](/api/env-zero/environments/environments-get-plan-impact): Returns, per deployment id, how many resources its stored plan would create, update, delete,
recreate or only change in state, plus the destructive changes it would make. Reads the plan already
stored for the deployment; it runs no new plan.

A recreate is destructive and is also counted under 'recreate'. 'metadata' counts resources whose
state changes but whose infrastructure does not (a move or an import), and never appears in
'destructive'.

'destructive' is capped at 50 entries; 'destructiveTotal' is the true count and
'destructiveTypeCounts' covers every destructive change, not just the returned ones.

'planReadable' is false when no readable plan is stored, in which case every count is absent rather
than zero. A legacy deployment that stored only a plan summary is readable but partial: it carries
'create', 'update', 'delete' and 'destructiveTotal' and omits 'recreate', 'metadata', 'destructive'
and 'destructiveTypeCounts', so read each field for presence rather than inferring it from
'planReadable'. Deployments the caller may not view are absent from the response.

At most 200 ids per request.
    - [List Deployment Resources](/api/env-zero/environments/environments-find-resources): Returns the resources recorded for a deployment, as parsed from its plan or state.
    - [List Environment Tags](/api/env-zero/environments/environments-find-tags-by-organization-id): Returns every tag key on the organization's environments that the caller may view, mapped to its distinct values
    - [Lock or Unlock Environment](/api/env-zero/environments/environments-update-environment-lock): Locks or unlocks an environment. `isLocked` is required and `reason` records why, shown to project members. While locked, deploy, destroy, plan and drift detection will not run for the environment. Returns the resulting lock status.
    - [Remediate Drift Deployment](/api/env-zero/environments/environments-remediate-drift): Remediate a drifted environment, using a drift detection deployment ID
    - [Scan for Drift Events](/api/env-zero/environments/environments-drift-scan): Starts a scan for the cloud change events behind a drift-detection deployment, which is what makes per-resource drift events available for that deployment. The scan runs asynchronously and the call returns no content; poll `GET /environments/deployments/{id}/drift-status` for the scan status.
    - [Update Environment Tags](/api/env-zero/environments/environments-update-tags): Applies a JSON merge-patch (RFC 7396) to the environment's tags - a non-empty array replaces that key's values wholesale, null removes the key, and keys that are not mentioned are left untouched
    - [Update Environment TTL](/api/env-zero/environments/environments-ttl): Sets an environment's time-to-live, after which env zero destroys it automatically. `type` is required and selects whether the environment has a finite or infinite lifespan, with `value` giving the deadline. Maximum TTL is constrained by the organization's and project's TTL policy and is measured from the environment's creation time. Returns the updated environment.
  - Notifications: env zero can send notifications for deployment events to your Slack or Microsoft Teams workspace.
You can define several Notification Targets, corresponding to different channels.
You can also associate these Notification Targets to different env zero projects, controlling which events go to which channel.
More on https://docs.envzero.com/docs/notifications
    - [List Notification Endpoints](/api/env-zero/notifications/notifications-find-notification-endpoints): Returns the notification endpoints configured for an organization - the Slack, Microsoft Teams, email and webhook targets that deployment and drift events can be sent to. Webhook secrets are not returned.
    - [Create Notification Endpoint](/api/env-zero/notifications/notifications-create-notification-endpoint): Creates a notification endpoint for an organization. `name`, `organizationId`, `type` and `value` are required, where `value` is the target address such as a webhook URL. Supply `webhookSecret` to have env zero sign webhook payloads. The secret is not returned.
    - [Get Notification Endpoint settings](/api/env-zero/notifications/notifications-find-project-notification-settings): Returns the notification settings for a project - which endpoints receive which events, including the drift detected, no drift detected and drift failed events.
    - [Update Notification Settings](/api/env-zero/notifications/notifications-update-project-notification-settings): Sets which events a notification endpoint receives for a project, replacing the endpoint's current `eventNames` for that project. Returns the resulting setting.
  - Organization: An Organization is the highest level logical entity in env zero.

All Projects, Templates, Variable, Policies, and Environments, are defined for a specific organization. Organizations are logically separate from each other, and do not share any entities.
More on https://docs.envzero.com/docs/organizations
    - [Get Organization Limits](/api/env-zero/organization/organization-get-organization-limits): Returns the organization's limits, such as the maximum number of environments. Useful for checking headroom before creating environments.
    - [Get Organization](/api/env-zero/organization/organization-find-organization-by-id): Returns an organization by id, including its default and maximum TTL, secrets and OIDC policies, pull-request and approval settings, and IP allowlist.
    - [List Organizations](/api/env-zero/organization/organization-find-organizations): Returns the organizations the authenticated API key can access. Use this to resolve the organization id that most other operations require.
    - [List Users](/api/env-zero/organization/organization-get-users): Returns the users in an organization, with their roles. Set `includeApiKeys` to include API keys, which behave as users, and `query` to search.
  - Projects: Projects are used in env zero to provide granular access control to Environments.
Every environment in env zero exists under a project, and users are given access on a per-project basis.
Projects are also useful for managing multiple cloud accounts within a single Organization.
We recommend using projects to separate dev environments from production environments, each with its own access rights and policies.
More on https://docs.envzero.com/docs/projects
    - [List Projects](/api/env-zero/projects/projects-find-by-organization-id): Returns the projects in an organization that the caller may view. Set `isArchived` to include or exclude archived projects.
    - [Create a new Project](/api/env-zero/projects/projects-create-project): Creates a project in an organization. `name` and `organizationId` are required; supply `parentProjectId` to create it as a sub-project. Returns the created project.
    - [Get a Project By ID](/api/env-zero/projects/projects-find-by-id): Returns a project by id, including its tags, parent project and position in the project hierarchy.
    - [Get Policy](/api/env-zero/projects/environments-get-policies): Returns the policy in force for a project - its environment limits, default and maximum TTL, approval and cost-estimation defaults, destroy protection, drift detection schedule and automatic drift remediation strategy, and the other deployment controls that apply to its environments.
    - [Update Policy](/api/env-zero/projects/environments-update-policies): Updates the policy for a project, identified by the required `projectId`. Fields left out are unchanged. This is where a project's drift detection schedule, automatic drift remediation strategy, environment limits, TTL bounds and destroy protection are set for its environments. Returns the updated policy.
    - [Get Users With Access to Project](/api/env-zero/projects/projects-get-project-users): Returns all users who have access to a project, including organization admins, users with direct project assignments, and users who have access through team assignments. Currently supports organizations with up to approximately 1000 users due to our limits.
  - Scheduling: Scheduling allows you to automatically trigger destroys and deploys of your environments on a scheduled basis.
Scheduling is configured based on cron expressions, and can be attached to an already deployed environment only.

More on https://docs.envzero.com/docs/scheduling
    - [Get Drift Detection Environment Scheduling](/api/env-zero/scheduling/scheduling-get-drift-detection-by-environment-id): Returns the drift detection schedule for an environment: whether detection is enabled, its cron expression, the next scheduled run, the automatic drift remediation strategy in force, and, when detection is disabled, the reason. An environment with detection disabled or broken is a monitoring blind spot.
    - [Set Drift Detection Environment Scheduling](/api/env-zero/scheduling/scheduling-set-drift-detection): Enables, disables or reschedules drift detection for an environment, and sets its automatic drift remediation strategy. `enabled` is required; supply `cron` to set the detection interval. Note that the scheduler runs hourly, so the exact minute within the hour cannot be controlled, and the minimum interval depends on the organization's plan.
    - [Get Environment Scheduling](/api/env-zero/scheduling/scheduling-get-schedule-by-environment-id): Returns the scheduled deploy and destroy cron expressions configured for an environment.
    - [Set Environment Scheduling](/api/env-zero/scheduling/scheduling-set-environment-schedule): Sets the scheduled deploy and destroy cron expressions for an environment. Returns the resulting schedule.
    - [Get Project Scheduling](/api/env-zero/scheduling/scheduling-get-schedule-by-project-id): Returns the scheduled deploy and destroy configuration for every environment in a project.
  - Templates: A template in env zero defines a type of environment that can be deployed.
Click Run Now on a template to create a new environment.
A template consists of a name, a description, a valid set of configuration files describing the deployment, and a set of Variables and Secrets.
More on https://docs.envzero.com/docs/templates
    - [Add Template to Project](/api/env-zero/templates/templates-add-blueprint-to-project): Assigns a template to a project, making it available for creating environments there. Returns the updated template.
    - [List Templates](/api/env-zero/templates/templates-find-all): Returns all Templates associated with either an Organization or Project. At least one of these must be set.
    - [Create Template](/api/env-zero/templates/templates-create-blueprint): Please note, you can only have 1 ssh key per template
    - [Get Assignable Templates](/api/env-zero/templates/templates-get-assignable-templates): Returns a list of templates that can be assigned to the specified project, including those from parent projects and the organization.
    - [Get Template by ID](/api/env-zero/templates/templates-get-blueprint-by-id): Returns a template by id, including its repository, revision, path, IaC type and version, retry configuration, and the projects it is assigned to.
    - [Update Template](/api/env-zero/templates/templates-update-blueprint): Please note, you can only have 1 ssh key per template
- SDKs
  - [SDKs](/sdks): Client libraries for this API.
  - [C# SDK](/sdks/csharp): Install and start using the C# SDK.
  - [Python SDK](/sdks/python): Install and start using the Python SDK.
  - [TypeScript SDK](/sdks/typescript): Install and start using the TypeScript SDK.
- Context Plugin
  - [Context Plugin](/context-plugin): Give your AI coding assistant working knowledge of this API's SDKs.