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.

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://app.terraform.io/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
    },
    "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": {
      "deleteOlderThanNDays": 33
    }
  }
}

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/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": 33
    },
    "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://app.terraform.io/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 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 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 older than a set number of days.

Properties

Sample payload

{
  "data": {
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "deleteOlderThanNDays": 33
    }
  }
}

Sample response body

{
  "data": {
    "id": "drp-Kh74zpKVGNWbpugQ",
    "type": "data-retention-policy-delete-olders",
    "attributes": {
      "delete-older-than-n-days": 33
    },
    "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"
        }
      }
    }
  }
}