Admin Sentinel Versions API

Terraform Enterprise Only: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.

The Sentinel Versions Admin API lets site administrators manage which versions of Sentinel are available to the HCP Terraform users within their enterprise.

List all Sentinel versions

GET /api/v2/admin/sentinel-versions

This endpoint lists all known versions of Sentinel.

Status	Response	Reason
200	JSON API document (`type: "sentinel-versions"`)	Successfully lists Sentinel versions.
404	JSON API error object	Client is not an administrator.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`filter[version]`	Optional. A query string. This will find an exact Sentinel version matching the version queried. This option takes precedence over search queries.
`search[version]`	Optional. A search query string. This will search for Sentinel versions matching the version number queried.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 Sentinel versions per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/admin/sentinel-versions"

Sample Response

{
  "data": [
    {
      "id": "tool-L4oe7rNwn7J4E5Yr",
      "type": "sentinel-versions",
      "attributes": {
        "version": "0.22.1",
        "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
        "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
        "deprecated": false,
        "deprecated-reason": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "usage": 0,
        "created-at": "2023-08-23T22:34:24.561Z"
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "last": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 4,
      "total-count": 70
    }
  }
}

Create a Sentinel version

POST /api/v2/admin/sentinel-versions

Status	Response	Reason
201	JSON API document (`type: "sentinel-versions"`)	The Sentinel version was successfully created.
404	JSON API error object	The client is not an administrator.
422	JSON API error object	Validation errors.

Request Body

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

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"sentinel-versions"`.
`data.attributes.version`	string		A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`).
`data.attributes.url`	string		The URL where you can download the 64-bit Linux binary of this version.
`data.attributes.sha`	string		The SHA-256 checksum of the compressed Sentinel binary.
`data.attributes.deprecated`	bool	`false`	Whether or not this version of Sentinel is deprecated.
`data.attributes.deprecated-reason`	string	`null`	Additional context about why a version of Sentinel is deprecated. Field is null unless deprecated is `true`.
`data.attributes.official`	bool	`false`	Whether or not this is an official release of Sentinel.
`data.attributes.enabled`	bool	`true`	Whether or not this version of Sentinel is enabled for use in HCP Terraform.
`data.attributes.beta`	bool	`false`	Whether or not this version of Sentinel is a beta pre-release.

Sample Payload

{
  "data": {
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "enabled": true,
      "beta": false
    }
  }
}

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/admin/sentinel-versions

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Show a Sentinel version

GET /api/v2/admin/sentinel-versions/:id

Parameter	Description
`:id`	The ID of the Sentinel version to show.

Status	Response	Reason
200	JSON API document (`type: "sentinel-versions"`)	Successfully shows the specified Sentinel version.
404	JSON API error object	Could not find the specified Sentinel version, or client is not an administrator.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/admin/sentinel-versions/tool-L4oe7rNwn7J4E5Yr

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Update a Sentinel version

PATCH /api/v2/admin/sentinel-versions/:id

Parameter	Description
`:id`	The ID of the Sentinel version to update.

Status	Response	Reason
200	JSON API document (`type: "sentinel-versions"`)	The Sentinel version was successfully updated.
404	JSON API error object	Could not find the specified Sentinel version, or client is not an administrator.
422	JSON API error object	Validation errors.

Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"sentinel-versions"`.
`data.attributes.version`	string	(previous value)	A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"`, `"0.12.20-beta1"`).
`data.attributes.url`	string	(previous value)	The URL you can download the 64-bit Linux binary of this version.
`data.attributes.sha`	string	(previous value)	The SHA-256 checksum of the compressed Sentinel binary.
`data.attributes.official`	bool	(previous value)	Whether or not this is an official release of Sentinel.
`data.attributes.deprecated`	bool	(previous value)	Whether or not this version of Sentinel is deprecated.
`data.attributes.deprecated-reason`	string	(previous value)	Additional context about why a version of Sentinel is deprecated.
`data.attributes.enabled`	bool	(previous value)	Whether or not this version of Sentinel is enabled for use in HCP Terraform.
`data.attributes.beta`	bool	(previous value)	Whether or not this version of Sentinel is a beta pre-release.

Sample Payload

{
  "data": {
    "type": "sentinel-versions",
    "attributes": {
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Sentinel. Please upgrade as soon as possible"
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/admin/sentinel-versions/tool-L4oe7rNwn7J4E5Yr

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Sentinel. Please upgrade as soon as possible",
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Delete a Sentinel version

DELETE /api/v2/admin/sentinel-versions/:id

This endpoint removes a Sentinel version from HCP Terraform. You cannot remove officially labeled Sentinel versions or any version used by a workspace.

Parameter	Description
`:id`	The ID of the Sentinel version to delete.

Status	Response	Reason
204	Empty response	The Sentinel version was successfully deleted.
404	JSON API error object	The request could not find a matching Sentinel version with the specified ID, or the client is not an administrator.
422	JSON API error object	The request could not remove the Sentinel version because it is an official version or a workspace uses it.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/admin/sentinel-versions/tool-L4oe7rNwn7J4E5Yr