Data retention policy API
Data retention policies allow administrators to control storage usage by specifying how long backing data is retained for different resources.
A data retention policy determines when Terraform Enterprise automatically marks backing data for garbage collection. Backing data refers to configuration version or state version files.
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.
Resource | API Endpoint |
---|---|
Workspaces | GET /workspaces/:workspace_id/relationships/data-retention-policy |
Organizations | GET /organizations/:organization_name/relationships/data-retention-policy |
Site-wide | GET /admin/data-retention-policy-settings |
For more information on the types of data retention policies, and the keys returned for each, refer to Data Retention Policy Types
Status | Response | Reason |
---|---|---|
200 | JSON API document with type set to "data-retention-policy-delete-olders" or "data-retention-policy-dont-deletes" | Successful request. Refer to Data Retention Policy Types. |
404 | JSON API error object | Target resource not found, data retention policy does not exist, or user unauthorized to perform action. |
Request body
No request body.
Sample request
Sample response
Create or update data retention policy
This endpoint creates a data retention policy attached to a target resource or updates the existing policy.
Resource | API Endpoint |
---|---|
Workspaces | POST /workspaces/:workspace_id/relationships/data-retention-policy |
Organizations | POST /organizations/:organization_name/relationships/data-retention-policy |
Site-wide | POST /admin/data-retention-policy-settings |
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.
Status | Response | Reason(s) |
---|---|---|
204 | No content | Successfully updated the target resource's data retention policy. |
404 | JSON API error object | Target resource not found or user is not authorized to perform action. |
Request body
This POST
endpoint requires a JSON object with the following properties as a request payload:
Key path | Type | Description |
---|---|---|
data.type | string | A data retention policy type |
data.attributes | object | The attributes for the specified policy type |
Sample payload
Sample request
Sample response
Remove data retention policy
This endpoint removes the data retention policy explicitly set on a target resource.
Resource | API Endpoint |
---|---|
Workspaces | DELETE /workspaces/:workspace_id/relationships/data-retention-policy |
Organizations | DELETE /organizations/:organization_name/relationships/data-retention-policy |
Site-wide | DELETE /admin/data-retention-policy-settings |
Status | Response | Reason(s) |
---|---|---|
204 | No Content | Successfully removed the target resource's data retention policy. |
404 | JSON API error object | Target resource not found, or user unauthorized to perform action. |
Request body
No request body.
Sample request
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 that are 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 older than a set number of days. Refer todata-retention-policy-delete-olders
for additional information.data-retention-policy-dont-deletes
: Directs Terraform Enterprise to preserve backing data for the related resource. Refer todata-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 older than a set number of days.
Properties
Key path | Type | Description |
---|---|---|
data.type | string | Must be data-retention-policy-delete-olders . |
data.attributes.deleteOlderThanNDays | integer | The number of days to retain backing data for. |
data.relationships.target | object | The resource the policy is attached to. An organization, workspace, or null for the site-wide policy. Cannot be updated directly. |
Sample payload
Sample response body
data-retention-policy-dont-deletes
This policy directs Terraform Enterprise to preserve backing data for the related resource.
Properties
Key path | Type | Description |
---|---|---|
data.type | string | Must be data-retention-policy-dont-deletes . |
data.attributes | object | Not applicable. This policy type does not have attributes. |
data.relationships.target | object | The resource the policy is attached to. An organization, workspace. Cannot be updated directly. |
Sample payload
Sample response body