Data retention policy API

Data retention policies allow administrators to control storage usage by specifying how long backing data is retained for different resource types.

A data retention policy determines when Terraform Enterprise automatically marks backing data for garbage collection. Backing data refers to the files associated with configuration versions, state versions, and run data. Run data refers to the data and log files associated with plans, apply operations, and assessment operations.

You can set data retention policies per workspace, organization, and Terraform Enterprise installation.

Default policy settings

When the data retention policy is unspecified for a workspace, the workspace inherits the data retention policy defined for the organization. Refer to Data Retention Policies in the workspace settings documentation for additional information.

When the data retention policy is unspecified for an organization, the organization inherits the global data retention policy. Refer to Data Retention Policies in the organization settings documentation for additional information.

Show data retention policy

This endpoint shows the data retention policy set on the target resource.

For more information on the types of data retention policies and the keys returned for each, refer to Data Retention Policy Types.

Request body

No request body.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://<TFE_HOSTNAME>/api/v2/organizations/hashicorp/relationships/data-retention-policy

Sample response

{
  "data": {
    "id": "drp-Kh74zpKVGNWbpugQ",
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "delete-older-than-n-days": 60,
      "delete-state-versions": true,
      "delete-configuration-versions": true,
      "delete-run-data-and-logs": false,
      "state-versions-delete-after-n-days": 60,
      "configuration-versions-delete-after-n-days": 60,
      "run-data-and-logs-delete-after-n-days": null,
      "state-versions-keep-latest-count": 0,
      "configuration-versions-keep-latest-count": 0,
      "run-data-keep-latest-count": 0
    },
    "relationships": {
      "target": {
        "data": {
          "id": "hashicorp",
          "type": "organizations"
        }
      }
    }
  }
}

Create or update data retention policy

This endpoint creates a data retention policy attached to a target resource or updates the existing policy.

You can also call the endpoint to change the type of the data retention policy. Sending a POST or PATCH request and specifying a different type of policy in the payload automatically creates the new data retention policy for the target resource to replace the existing policy. For more information on the types of data retention policies, refer to Data Retention Policy Types.

Request body

This POST endpoint requires a JSON object with the following properties as a request payload:

Sample payload

{
  "data": {
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "deleteStateVersions": true,
      "stateVersionsDeleteAfterNDays": 30,
      "deleteConfigurationVersions": true,
      "configurationVersionsDeleteAfterNDays": 30,
      "deleteRunDataAndLogs": true,
      "runDataAndLogsDeleteAfterNDays": 14
    }
  }
}

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://<TFE_HOSTNAME>/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/data-retention-policy

Sample response

{
  "data": {
    "id": "drp-Kh74zpKVGNWbpugQ",
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "delete-older-than-n-days": 30,
      "delete-state-versions": true,
      "delete-configuration-versions": true,
      "delete-run-data-and-logs": true,
      "state-versions-delete-after-n-days": 30,
      "configuration-versions-delete-after-n-days": 30,
      "run-data-and-logs-delete-after-n-days": 14,
      "state-versions-keep-latest-count": 0,
      "configuration-versions-keep-latest-count": 0,
      "run-data-keep-latest-count": 0
    },
    "relationships": {
      "target": {
        "data": {
          "id": "ws-7aiqKYf6ejMFdtWS",
          "type": "workspaces"
        }
      }
    }
  }
}

Remove data retention policy

This endpoint removes the data retention policy explicitly set on a target resource.

Request body

No request body.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://<TFE_HOSTNAME>/api/v2/organizations/hashicorp/relationships/data-retention-policy

Response

No response body.

Status code 204.

Data retention policy types

You can send a POST or PATCH request to /data-retention-policy and /data-retention-policy-settings endpoints to set the policy or change the existing policy. The schema for each type has a set of attributes specific to the type.

Specify one of the following data retention policy types in the data.type parameter in the request payload:

• data-retention-policy-delete-olders: Directs Terraform Enterprise to delete backing data after a configured number of days, with per-artifact-type control. Refer to data-retention-policy-delete-olders for additional information.
• data-retention-policy-dont-deletes: Directs Terraform Enterprise to preserve backing data for the related resource. Refer to data-retention-policy-dont-deletes for additional information.

To view the existing policy, send a GET request to the endpoint. Endpoints are polymorphic and may return different policy types depending on how Terraform Enterprise has been configured.

data-retention-policy-delete-olders

This policy directs Terraform Enterprise to delete backing data for the configured artifact types after their respective retention windows elapse.

Properties

Mixed field validation

In the same request, providing deleteOlderThanNDays together with any per-artifact field, such as stateVersionsDeleteAfterNDays or deleteRunDataAndLogs, returns a 422 Unprocessable Entity error. Use the per-artifact fields for all new integrations. The deleteOlderThanNDays field is retained only for backwards compatibility with older API clients that do not support the granular fields.

Eligibility guards for run data

Run data backing data for plan, apply, and assessment operations is never eligible for soft deletion if any of the following conditions are true:

• The associated run is in a non-terminal state.
• The run is the most recent run in the workspace.
• The run represents the last successful apply in the workspace.

These guards ensure that active and critical workspace state is never inadvertently removed.

Sample payload

{
  "data": {
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "deleteStateVersions": true,
      "stateVersionsDeleteAfterNDays": 60,
      "stateVersionsKeepLatestCount": 5,
      "deleteConfigurationVersions": true,
      "configurationVersionsDeleteAfterNDays": 60,
      "deleteRunDataAndLogs": true,
      "runDataAndLogsDeleteAfterNDays": 30,
      "runDataKeepLatestCount": 10
    }
  }
}

Sample response body

{
  "data": {
    "id": "drp-Kh74zpKVGNWbpugQ",
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "delete-older-than-n-days": 60,
      "delete-state-versions": true,
      "delete-configuration-versions": true,
      "delete-run-data-and-logs": true,
      "state-versions-delete-after-n-days": 60,
      "configuration-versions-delete-after-n-days": 60,
      "run-data-and-logs-delete-after-n-days": 30,
      "state-versions-keep-latest-count": 5,
      "configuration-versions-keep-latest-count": 0,
      "run-data-keep-latest-count": 10
    },
    "relationships": {
      "target": {
        "data": {
          "id": "ws-7aiqKYf6ejMFdtWS",
          "type": "workspaces"
        }
      }
    }
  }
}

data-retention-policy-dont-deletes

This policy directs Terraform Enterprise to preserve backing data for the related resource.

Properties

Sample payload

{
  "data": {
    "type": "data-retention-policy-dont-deletes",
    "attributes": {}
  }
}

Sample response body

{
  "data": {
    "id": "drp-Kh74zpKVGNWbpugQ",
    "type": "data-retention-policy-dont-deletes",
    "attributes": {},
    "relationships": {
      "target": {
        "data": {
          "id": "hashicorp",
          "type": "organizations"
        }
      }
    }
  }
}