API Changelog

Keep track of changes to the API for HCP Terraform and Terraform Enterprise.

2025-05-1

• Addagent-pool relationship to therun task API, which you can use to assign a run task to an agent pool.
• You can now revoke, and revert the revocation of, module versions. Learn more aboutManaging module versions.

2025-4-17

• Document inherited-from link associated with effective tag bindings.

2025-03-20

• Add API documentation for multipleteam tokens, and update documentation aroundlegacy team tokens.
• Update existing API documentation forteam tokens to distinguish multiple team tokens fromlegacy team tokens.

2025-3-10

• Document unique pagination metadata given in the response ofOrganization Runs Index API.

2024-11-19

• Clarifytag-bindings andeffective-tag-bindings onworkspaces andprojects
• Adds new documentation forPATCHing tag bindings onprojects andworkspaces

2024-10-15

• Add new documentation for the ability to deprecate, and revert the deprecation of, module versions. Learn more aboutManaging module versions.

2024-10-14

• Update theOrganizations API to support thespeculative-plan-management-enabled attribute, which controlsautomatic cancellation of plan-only runs triggered by outdated commits.

2024-10-11

• Add documentation for new timeframe filter on List endpoints forRuns API

2024-09-02

• Add warning about the deprecation and future removal of thePolicy Checks API.

2024-08-16

• Fixes Workspace API responses to be consistent and contain all attributes and relationships.

2024-08-14

• Add documentation for a new API endpoint that lists anorganization's team tokens.

2024-08-01

• Update theadmin settings API andadmin organizations API to indicate that theterraform-build-worker-plan-timeout andterraform-build-worker-apply-timeout attributes are deprecated and will be replaced byplan-timeout andapply-timeout, respectively.

2024-07-15

• Update theTeam API to includeallow-member-token-management.

2024-06-25

• Add API documentation for newteam token management setting.
• Update API documentation for themanage teams permission.

2024-05-29

• Add API documentation for the newaudit trails token.

2024-05-23

• Update theregistry modules API for publishing new versions of branch based modules.

2024-05-10

• Add API documentation for newmanage agent pools permission.

2024-04-25

• Project names can now be up to 40 characters.

2024-04-08

• Add API documentation for newteam management permissions.

2024-04-04

• Add asort parameter to theProjects list API to allow sorting projects by name.
• Add adescription attribute to theProjects API.
• Addproject-count andworkspace-count attributes to sampleProjects API responses.

2024-3-27

• Addprivate-vcs toFeature Entitlements.

2024-3-26

• Add API documentation for searchingvariable sets by name.

2024-3-14

• Add documentation for creating runs with debugging mode enabled.

2024-3-12

• Update OAuth Client API endpoints to create, update, and return projects associated with an oauth client.
• Add API endpoints toAttach an OAuth Client andDetach an OAuth Client from a project.
• Addorganization-scoped attribute to theOAuth Clients API.

2024-2-29

• Updaterun task stages with new multi-stage payload format.
• Updaterun tasks with global run tasks request/response payloads.

2024-2-27

• Addprivate-policy-agents toFeature Entitlements.

2024-2-20

• Add documentation for configuring organization and workspace data retention policies through the API and on the differenttypes of data retention policies.

2024-1-30

• Update theAudit trails documentation to expand on the payloads for each event.

2024-1-24

• Introduce configurable data retention policies at the site-wide level and extend data retention policies at the organization and workspace levels.
• Added and/or updated data retention policy documentation to the following topics:
  • Admin Settings Documentation
  • Admin API Documentation
  • Organization Documentation
  • Workspace Documentation

2024-1-4

• Update theOrganizations API to support theaggregated-commit-status-enabled attribute, which controls whetherAggregated Status Checks are enabled.

2023-11-17

• Added theopa-versions endpoint to allow administrators to manage available Open Policy Agent (OPA) versions.
• Added thesentinel-versions endpoint to allow administrators to manage available Sentinel versions.
• Addauthenticated-resource relationship to theaccount API.

2023-11-15

• Introduce configurable data retention policies at theorganization andworkspace levels.
• Added data retention policy documentation to the following topics:
  • state-versions API documentation
  • configuration-versions API documentation
  • Organizations documentation
  • Workspaces documentation

2023-11-07

• Addauto_destroy_activity_duration to theWorkspaces API, which allows Terraform Cloud to schedule auto-destroy runsbased on workspace inactivity.

2023-10-31

• Update theWorkspaces API to support theauto-apply-run-trigger attribute, which controls if run trigger runs are auto-applied.

2023-10-30

• Addpriority attribute to theVariable Sets API.

2023-10-04

• Updates torun task integration API
  • Fix invalid JSON in the example payload.
  • Clarify the expected JSON:API payload fields.
• Addpolicy-tool-version attribute toPolicy Set Outcomes.

2023-10-03

• UpdatePolicy Sets API to includeagent-enabled andpolicy-tool-version.
• UpdatePolicy Evaluations API to includepolicy-tool-version.

2023-09-29

• Add support forstreamlined run task reviews, enabling run task integrations to return high fidelity results.
  • Update theTerraform cloud run task API to enable streamlined run task reviews.
  • Therun task integration API now guides integrations through sending rich results.
  • Updated the run task payloadJSON schema.

2023-09-25

• Addintermediate boolean attribute to theState Versions API.

2023-09-19

• Addfailed state upload recovery endpoint.

2023-09-15

• Addauto-destroy-at attribute to theWorkspaces API.
• Update theNotification Configurations API to includeautomatic destroy run details.

2023-09-08

• Update theOrganizations API to includedefault-execution-mode anddefault-agent-pool.
• Update theWorkspaces API to add asetting-overwrites object to allow you to overwritedefault-execution-mode anddefault-agent-pool.

2023-09-06

• Update Policy Sets API endpoints to create, update, and return excluded workspaces associated with a policy set.
• Add API endpoints toAttach a Policy Set andDetach a Policy Set from excluded workspaces.

2023-08-21

• Addsave-plan attribute,planned_and_saved status, andsave_plan operation type toRuns endpoints.

2023-08-10

• Addprovisional toconfiguration-versions endpoint.

2023-07-26

• Add support for acustom option to theteam_project access level along with various customizable permissions. Theproject-access permissions apply to the project itself, andworkspace-access permissions apply to all workspaces within the project. For more information, seeProject Team Access.

2023-06-09

• Introduce support forimport blocks.
  • Runs have a newallow-config-generation option.
  • Plans have newresource-imports andgenerated-configuration properties.
  • Applies have a newresource-imports property.
• The workspaces associated with a policy set can now be updated using thePolicy Sets PATCH endpoint
• Update theWorkspaces API endpoints to include the associatedproject.

2023-05-25

• Terraform Cloud sets theconfiguration_version_download_url,configuration_version_id, andworkspace_working_directory properties for all stages of theRun Task Request.
• Add the newenforcement-level property in the request and response ofPolicies endpoints.
• Deprecate the oldenforce property in the request and response ofPolicies endpoints.
• Add new properties to limit run tasks and policies for the Terraform Cloud free tier. We updated theentitlement set,feature set, andsubscription endpoints with the following properties:
  • run-task-limit
  • run-task-workspace-limit
  • run-task-mandatory-enforcement-limit
  • policy-set-limit
  • policy-limit
  • policy-mandatory-enforcement-limit
  • versioned-policy-set-limit

2023-04-25

• Add theversion-id property to the response for the Create, List, and UpdateWorkspace Variables endpoints.

2023-03-30

• Add thesort query parameter to the Workspaces API'slist workspaces endpoint.

2023-03-24

• Update theVariable Sets API endpoints to include assigning variable sets to projects.

2023-03-20

• Add a names filter to theProjects list API to allow fetching a list of projects by name.

2023-03-13

• UpdateProject Team Access API to include additional Project roles.
• UpdatePermissions to reflect the decoupling of projects and workspaces in the Organization Permissions UI.

2023-03-08

• Introduced theGitHub App Installation APIs.
• UpdatedWorkspaces API to acceptvcs-repo.github-app-installation-id to connect a workspace to a GitHub App Installation.
• UpdatedRegistry Module API to acceptvcs-repo.github-app-installation-id to connect to a GitHub App Installation.
• UpdatedPolicy Sets API to acceptvcs-repo.github-app-installation-id to connect to a GitHub App Installation.

2023-02-16

• Addmanage-membership to the organization access settings of theTeam API.

2023-02-03

• Updated theList Runs API to note that the filter query parameters accept comma-separated lists.

2023-01-18

• Updated theTeam API to include theread-workspaces andread-projects permissions which grants teams view access to workspaces and projects.

2023-01-17

• AddProjects API for creating, updating and deleting projects.
• AddProject Team Access API for managing access for teams to individual projects.
• UpdateWorkspaces API to include examples of creating a workspace in a project and moving a workspace between projects.
• UpdateList Teams API to accept a search parameterq, so that teams can be searched by name.

2023-01-12

• Added new rollback to previous state endpoint toState Versions API

2022-12-22

• UpdatedSafe Delete a workspace to fix HTTP verb asPOST.

2022-11-18

• UpdatePolicies API to fix policy enforcement level defaults. Enforcement level is a required field, so no defaults are available.

2022-11-03

• UpdatePolicy Checks to fix policy set outcome return data type.

2022-10-17

• Updated theOrganizations API with theallow-force-delete-workspaces, which controls whether workspace administrators can delete workspaces with resources under management.
• Updated theWorkspaces API with a safe delete endpoint that guards against deleting workspaces that are managing resources.

2022-10-12

• UpdatePolicy Checks with result counts and support for filtering policy set outcomes.
• UpdateTeam Membership API to include adding and removing users from teams using organization membership ID.

2022-09-21

• UpdateState Versions with optionaljson-state-outputs andjson-state attributes, which are base-64 encoded external JSON representations of the terraform state. The read-onlyhosted-json-state-download-url attribute links to this version of the state file when available.
• UpdateState Version Outputs with adetailed-type attribute, which refines the output with the precise Terraform type.

2022-07-26

• Updated theRun status list withfetching,queuing,pre_plan_running andpre_plan_completed
• UpdateRun Tasks to include the newstages attribute when attaching or updating workspace tasks.
• UpdatedRun Tasks Integration to specify the different request payloads for different stages.

2022-06-23

• Added new query parameter(s) toList Runs endpoint.

2022-06-21

• UpdatedAdmin Organizations endpoints with newworkspace-limit setting. This is available in Terraform Enterprise v202207-1 and later.
• UpdatedList Agent Pools to accept a filter parameterfilter[allowed_workspaces][name] so that agent pools can be filtered by name of an associated workspace. The given workspace must be allowed to use the agent pool. Refer toScoping Agent Pools to Specific Workspaces.
• Added neworganization-scoped attribute andallowed-workspaces relationship to the request/response body of the below endpoints. This is available in Terraform Enterprise v202207-1 and later.
  • Show an Agent Pool
  • Create an Agent Pool
  • Update an Agent Pool

2022-06-17

• UpdatedCreating a Run Task section to include the new description information for the run task to be configured.
• UpdateRun Tasks to include the new description attribute.

2022-06-09

• UpdatedList Agent Pools to accept a search parameterq, so that agent pools can be searched byname. This is available in Terraform Enterprise v202207-1 and later.
• FixedList Workspaces to add missingsearch[tags] query parameter.
• UpdatedList Workspaces to add newsearch[exclude_tags] query parameter. This is available in Terraform Enterprise v202207-1 and later.

2022-05-11

• Updated Run Tasks permission to the following endpoints:
  • Organizations.
  • Team Access.
  • Teams.

2022-05-04

• UpdatedFeature Sets to add newrun-tasks attribute.

2022-05-03

• Added Run Tasks permission to the following endpoints:
  • Organizations
  • Workspaces

2022-04-29

• UpdatedRun Tasks Integration to specify the allowedstatus attribute values.
• UpdatedOrganization Memberships to add newfilter[email] query parameter.
• UpdatedTeams to add newfilter[names] query parameter.

2022-04-04

• Added theRun Tasks Integration endpoint.

2022-03-14

• Added theDownload Configuration Files endpoints.

2022-03-11

• IntroducedArchiving Configuration Versions.
  • UpdatedConfiguration Versions to add newfetching andarchived states.
  • UpdatedRuns to add newfetching state.
  • Added theArchive a Configuration Version endpoint.

2022-02-25

• UpdatedWorkspace Run Tasks to add newenabledattribute.

2022-02-28

• Introduced theRegistry Providers endpoints to manage private providers for a private registry.

2021-12-09

• Addedvariables field for POST /runs and the run resource, enabling run-specific variable values.

2021-12-03

• OAuth API updated to handlesecret andrsa_public_key fields for POST/PUT.

2021-11-17

• Added pagination support to the following endpoints:
  • Feature Sets -GET /feature-sets
  • Notification Configurations -GET /workspaces/:workspace_id/notification-configurations
  • Oauth Clients -GET /organizations/:organization_name/oauth-clients
  • Oauth Tokens -GET /oauth-clients/:oauth_client_id/oauth-tokens
  • Organization Feature Sets -GET /organizations/:organization_name/feature-sets
  • Organizations -GET /organizations
  • Policy Checks -GET /runs/:run_id/policy-checks
  • Policy Set Parameters -GET /policy-sets/:policy_set_id/parameters
  • SSH Keys -GET /organizations/:organization_name/ssh-keys
  • User Tokens -GET /users/:user_id/authentication-tokens

2021-11-11

• Introduced theVariable Sets endpoints for viewing and administering Variable Sets

2021-11-18

• Introduced theRegistry Providers endpoint to manage public providers for aprivate registry. These endpoints will be available in the following Terraform Enterprise Release:v202112-1

2021-09-12

• AddedRun Tasks Stages and Results endpoint.

2021-08-18

• Introduced theState Version Outputs endpoint to retrieve the Outputs for agiven State Version

2021-08-11

• BREAKING CHANGE: Security fix toConfiguration versions: upload-url attribute foruploading configuration files is now only available on the create response.

2021-07-30

• Introduced Workspace Tagging
  • UpdatedWorkspaces:
    • addedtag-names attribute.
    • addedPOST /workspaces/:workspace_id/relationships/tags
    • addedDELETE /workspaces/:workspace_id/relationships/tags
  • AddedOrganization Tags.
  • Addedtags attribute totfrun

2021-07-19

• Notification configurations: Gave organization tokens permission to create and manage notification configurations.

2021-07-09

• State versions: Fixed the ID format for the workspace relationship of a state version. Previously, the reported ID was unusable due to a bug.
• Workspaces: Addedlocked_by as an includable related resource.
• AddedRun Tasks API endpoint.

2021-06-8

• UpdatedRegistry Module APIs.
  • addedregistry_name scoped APIs.
  • addedorganization_name scoped APIs.
  • addedModule List API.
  • updatedModule Delete APIs (see deprecation note below).
  • CLOUD: added public registry module related APIs.
• DEPRECATION: The followingRegistry Module APIs have been replaced with newer apis and will be removed in the future.
  • The following endpoints to delete modules are replaced withModule Delete APIs
    • POST /registry-modules/actions/delete/:organization_name/:name/:provider/:version replaced withDELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/:version
    • POST /registry-modules/actions/delete/:organization_name/:name/:provider replaced withDELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider
    • POST /registry-modules/actions/delete/:organization_name/:name replaced withDELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name
  • POST /registry-modules replaced withPOST /organizations/:organization_name/registry-modules/vcs
  • POST /registry-modules/:organization_name/:name/:provider/versions replaced withPOST /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/versions
  • GET /registry-modules/show/:organization_name/:name/:provider replaced withGET /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider

2021-05-27

• CLOUD:Agents: addeddelete endpoint.

2021-05-19

• Runs: addedrefresh,refresh-only, andreplace-addrs attributes.

2021-04-16

• IntroducedControlled Remote State Access.
  • Admin Settings: addeddefault-remote-state-access attribute.
  • Workspaces:
    • addedglobal-remote-state attribute.
    • addedRemote State Consumers relationship.

2021-04-13

• Teams: addedmanage-policy-overrides property to theorganization-access attribute.

2021-03-23

• ENTERPRISE:v202103-1 IntroducedShare Modules Across Organizations with Terraform Enterprise.
  • Admin Organizations:
    • added new query parameters toList all Organizations endpoint
    • added module-consumers link inrelationships response
    • addedupdate module consumers endpoint
    • addedlist module consumers endpoint
  • Organizations: addedModule Producers
  • DEPRECATION:Admin Module Sharing: is replaced with a new JSON::Api compliantendpoint

2021-03-18

• CLOUD: IntroducedNew Workspace Overview for Terraform Cloud.
  • Workspaces:
    • addedresource-count andupdated-at attributes.
    • addedperformance attributes (apply-duration-average,plan-duration-average,policy-check-failures,run-failures,workspaces-kpis-run-count).
    • addedreadme andoutputsrelated resources.
  • Team Access: updated to support pagination.

2021-03-11

• AddedVCS Events, limited to GitLab.com connections.

2021-03-08

• Workspaces: addedcurrent_configuration_version andcurrent_configuration_version.ingress_attributes as includable related resources.