API Changelog

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

2024-10-15

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

2024-10-14

• Update the Organizations API to support the vcs-speculative-plan-management attribute, which controls automatic cancellation of plan-only runs triggered by outdated commits.

2024-10-11

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

2024-09-02

• Add warning about the deprecation and future removal of the Policy 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 an organization's team tokens.

2024-08-01

• Update the admin settings API and admin organizations API to indicate that the terraform-build-worker-plan-timeout and terraform-build-worker-apply-timeout attributes are deprecated and will be replaced by plan-timeout and apply-timeout, respectively.

2024-07-24

• Remove beta tags from documentation for audit trail tokens.

2024-07-15

• Update the Team API to include allow-member-token-management.

2024-07-12

• Add beta tags to documentation for audit trail tokens.

2024-06-25

• Add API documentation for new team token management setting.
• Update API documentation for the manage teams permission.

2024-05-29

• Add API documentation for the new audit trails token.

2024-05-23

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

2024-05-10

• Add API documentation for new manage agent pools permission.

2024-04-25

• Project names can now be up to 40 characters.

2024-04-08

• Add API documentation for new team management permissions.

2024-04-04

• Add a sort parameter to the Projects list API to allow sorting projects by name.
• Add a description attribute to the Projects API.
• Add project-count and workspace-count attributes to sample Projects API responses.

2024-3-27

• Add private-vcs to Feature Entitlements.

2024-3-26

• Add API documentation for searching variable 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 to Attach an OAuth Client and Detach an OAuth Client from a project.
• Add organization-scoped attribute to the OAuth Clients API.

2024-2-29

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

2024-2-27

• Add private-policy-agents to Feature Entitlements.

2024-2-20

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

2024-2-8

• Add Explorer API documentation

2024-1-30

• Update the Audit 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 the Organizations API to support the aggregated-commit-status-enabled attribute, which controls whether Aggregated Status Checks are enabled.

2023-11-17

• Added the opa-versions endpoint to allow administrators to manage available Open Policy Agent (OPA) versions.
• Added the sentinel-versions endpoint to allow administrators to manage available Sentinel versions.
• Add authenticated-resource relationship to the account API.

2023-11-15

• Introduce configurable data retention policies at the organization and workspace 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

• Add auto_destroy_activity_duration to the Workspaces API, which allows Terraform Cloud to schedule auto-destroy runs based on workspace inactivity.

2023-10-31

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

2023-10-30

• Add priority attribute to the Variable Sets API.

2023-10-04

• Updates to run task integration API
  • Fix invalid JSON in the example payload.
  • Clarify the expected JSON:API payload fields.
• Add policy-tool-version attribute to Policy Set Outcomes.

2023-10-03

• Update Policy Sets API to include agent-enabled and policy-tool-version.
• Update Policy Evaluations API to include policy-tool-version.

2023-09-29

• Add support for streamlined run task reviews, enabling run task integrations to return high fidelity results.
  • Update the Terraform cloud run task API to enable streamlined run task reviews.
  • The run task integration API now guides integrations through sending rich results.
  • Updated the run task payload JSON Schema.

2023-09-25

• Add intermediate boolean attribute to the State Versions API.

2023-09-19

• Add failed state upload recovery endpoint.

2023-09-15

• Add auto-destroy-at attribute to the Workspaces API.
• Update the Notification Configurations API to include automatic destroy run details.

2023-09-08

• Update the Organizations API to include default-execution-mode and default-agent-pool.
• Update the Workspaces API to add a setting-overwrites object to allow you to overwrite default-execution-mode and default-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 to Attach a Policy Set and Detach a Policy Set from excluded workspaces.

2023-08-21

• Add save-plan attribute, planned_and_saved status, and save_plan operation type to Runs endpoints.

2023-08-10

• Add provisional to configuration-versions endpoint.

2023-07-26

• Add support for a custom option to the team_project access level along with various customizable permissions. The project-access permissions apply to the project itself, and workspace-access permissions apply to all workspaces within the project. For more information, see Project Team Access.

2023-06-09

• Introduce support for import blocks.
  • Runs have a new allow-config-generation option.
  • Plans have new resource-imports and generated-configuration properties.
  • Applies have a new resource-imports property.
• The workspaces associated with a policy set can now be updated using the Policy Sets PATCH endpoint
• Update the Workspaces API endpoints to include the associated project.

2023-05-25

• Terraform Cloud sets the configuration_version_download_url, configuration_version_id, and workspace_working_directory properties for all stages of the Run Task Request.
• Add the new enforcement-level property in the request and response of Policies endpoints.
• Deprecate the old enforce property in the request and response of Policies endpoints.
• Add new properties to limit run tasks and policies for the Terraform Cloud free tier. We updated the entitlement set, feature set, and subscription 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 the version-id property to the response for the Create, List, and Update Workspace Variables endpoints.

2023-03-30

• Add the sort query parameter to the Workspaces API's list workspaces endpoint.

2023-03-24

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

2023-03-20

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

2023-03-13

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

2023-03-08

• Introduced the GitHub App Installation APIs.
• Updated Workspaces API to accept vcs-repo.github-app-installation-id to connect a workspace to a GitHub App Installation.
• Updated Registry Module API to accept vcs-repo.github-app-installation-id to connect to a GitHub App Installation.
• Updated Policy Sets API to accept vcs-repo.github-app-installation-id to connect to a GitHub App Installation.

2023-02-16

• Add manage-membership to the organization access settings of the Team API.

2023-02-03

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

2023-01-18

• Updated the Team API to include the read-workspaces and read-projects permissions which grants teams view access to workspaces and projects.

2023-01-17

• Add Projects API for creating, updating and deleting projects.
• Add Project Team Access API for managing access for teams to individual projects.
• Update Workspaces API to include examples of creating a workspace in a project and moving a workspace between projects.
• Update List Teams API to accept a search parameter q, so that teams can be searched by name.

2023-01-12

• Added new rollback to previous state endpoint to State Versions API

2022-12-22

• Updated Safe Delete a workspace to fix HTTP verb as POST.

2022-11-18

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

2022-11-03

• Update Policy Checks to fix policy set outcome return data type.

2022-10-17

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

2022-10-12

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

2022-10-06

• Updated the Policies API with support for Open Policy Agent (OPA) policies.
• Update Policy Sets with support for OPA policy sets.
• Updated Policy Checks to add support for listing policy evaluations and policy set outcomes.
• Update Run Tasks Stage to include the new policy_evaluations attribute in the output.

2022-09-21

• Update State Versions with optional json-state-outputs and json-state attributes, which are base-64 encoded external JSON representations of the terraform state. The read-only hosted-json-state-download-url attribute links to this version of the state file when available.
• Update State Version Outputs with a detailed-type attribute, which refines the output with the precise Terraform type.

2022-07-26

• Updated the Run status list with fetching, queuing, pre_plan_running and pre_plan_completed
• Update Run Tasks to include the new stages attribute when attaching or updating workspace tasks.
• Updated Run Tasks Integration to specify the different request payloads for different stages.

2022-06-23

• Added the Assessments.

• Updated Workspace and Notification Configurations to account for assessments.

• Added new query parameter(s) to List Runs endpoint.

2022-06-21

• Updated Admin Organizations endpoints with new workspace-limit setting. This is available in Terraform Enterprise v202207-1 and later.
• Updated List Agent Pools to accept a filter parameter filter[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 to Scoping Agent Pools to Specific Workspaces.
• Added new organization-scoped attribute and allowed-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

• Updated Creating a Run Task section to include the new description information for the run task to be configured.
• Update Run Tasks to include the new description attribute.

2022-06-09

• Updated List Agent Pools to accept a search parameter q, so that agent pools can be searched by name. This is available in Terraform Enterprise v202207-1 and later.
• Fixed List Workspaces to add missing search[tags] query parameter.
• Updated List Workspaces to add new search[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

• Updated Feature Sets to add new run-tasks attribute.

2022-05-03

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

2022-04-29

• Updated Run Tasks Integration to specify the allowed status attribute values.
• Updated Organization Memberships to add new filter[email] query parameter.
• Updated Teams to add new filter[names] query parameter.

2022-04-04

• Added the Run Tasks Integration endpoint.

2022-03-14

• Added the Download Configuration Files endpoints.

2022-03-11

• Introduced Archiving Configuration Versions.
  • Updated Configuration Versions to add new fetching and archived states.
  • Updated Runs to add new fetching state.
  • Added the Archive a Configuration Version endpoint.

2022-02-25

• Updated Workspace Run Tasks to add new enabledattribute.

2022-02-28

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

2021-12-09

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

2021-12-03

• OAuth API updated to handle secret and rsa_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 the Variable Sets endpoints for viewing and administering Variable Sets

2021-11-18

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

2021-09-12

• Added Run Tasks Stages and Results endpoint.

2021-08-18

• Introduced the State Version Outputs endpoint to retrieve the Outputs for a given State Version

2021-08-11

• BREAKING CHANGE: Security fix to Configuration versions: upload-url attribute for uploading configuration files is now only available on the create response.

2021-07-30

• Introduced Workspace Tagging
  • Updated Workspaces:
    • added tag-names attribute.
    • added POST /workspaces/:workspace_id/relationships/tags
    • added DELETE /workspaces/:workspace_id/relationships/tags
  • Added Organization Tags.
  • Added tags attribute to tfrun

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: Added locked_by as an includable related resource.
• Added Run Tasks API endpoint.

2021-06-8

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

2021-05-27

• CLOUD: Agents: added delete endpoint.

2021-05-19

• Runs: added refresh, refresh-only, and replace-addrs attributes.

2021-04-16

• Introduced Controlled Remote State Access.
  • Admin Settings: added default-remote-state-access attribute.
  • Workspaces:
    • added global-remote-state attribute.
    • added Remote State Consumers relationship.

2021-04-13

• Teams: added manage-policy-overrides property to the organization-access attribute.

2021-03-23

• ENTERPRISE: v202103-1 Introduced Share Modules Across Organizations with Terraform Enterprise.
  • Admin Organizations:
    • added new query parameters to List all Organizations endpoint
    • added module-consumers link in relationships response
    • added update module consumers endpoint
    • added list module consumers endpoint
  • Organizations: added Module Producers
  • DEPRECATION: Admin Module Sharing: is replaced with a new JSON::Api compliant endpoint

2021-03-18

• CLOUD: Introduced New Workspace Overview for Terraform Cloud.
  • Workspaces:
    • added resource-count and updated-at attributes.
    • added performance attributes (apply-duration-average, plan-duration-average, policy-check-failures, run-failures, workspaces-kpis-run-count).
    • added readme and outputs related resources.
  • Team Access: updated to support pagination.

2021-03-11

• Added VCS Events, limited to GitLab.com connections.

2021-03-08

• Workspaces: added current_configuration_version and current_configuration_version.ingress_attributes as includable related resources.