Terraform
Agents and agent pools API reference
An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose. A workspace or Stack may be configured to use one of the organization's agent pools to run remote operations with isolated, private, or on-premises infrastructure.
Terraform Enterprise does not currently support Stacks, so any references to Stacks in the following API endpoints only apply to HCP Terraform.
Note: HCP Terraform Free edition includes one self-hosted agent. Refer to HCP Terraform pricing for details.
List Agent Pools
GET /organizations/:organization_name/agent-pools
Parameter | Description |
---|---|
:organization_name | The name of the organization. |
This endpoint allows you to list agent pools, their agents, and their tokens for an organization.
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agent-pools" ) | Success |
404 | JSON API error object | Organization not found |
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 |
---|---|
q | Optional. A search query string. Agent pools are searchable by name. |
sort | Optional. Allows sorting the returned agents pools. Valid values are "name" and "created-at" . Prepending a hyphen to the sort parameter will reverse the order (e.g. "-name" ). |
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 agent pools per page. |
filter[allowed_workspaces][name] | Optional. Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces. |
filter[allowed_stacks][name] | Optional. Filters agent pools to those associated with the given Stack. The Stack must have permission to use the agent pool. Only available in HCP Terraform, refer to Scope agent pools to learn more. |
filter[allowed_projects][name] | Optional. Filters agent pools to those associated with the given project. The project must have permission to use the agent pool. Refer to Scoping Agent Pools to Specific Projects. |
Response fields
Responses for this endpoint can contain an attributes
object with the following fields:
Field name | Type | Description |
---|---|---|
data.attributes.agent-count | number | The number of agents in Idle , Busy or Unknown states. Agents that are Exited or Errored are excluded. |
data.attributes.meta.status-counts.total | number | The total number of resources the filter was applied to. |
data.attributes.meta.status-counts.matching | number | The total number of resources returned, which match the filter you applied. |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/organizations/my-organization/agent-pools
Sample Response
{
"data": [
{
"id": "apool-yoGUFz5zcRMMz53i",
"type": "agent-pools",
"attributes": {
"name": "example-pool",
"created-at": "2020-08-05T18:10:26.964Z",
"organization-scoped": false,
"agent-count": 3
},
"relationships": {
"agents": {
"links": {
"related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
},
"authentication-tokens": {
"links": {
"related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
},
"workspaces": {
"data": [
{
"id": "ws-9EEkcEQSA3XgWyGe",
"type": "workspaces"
}
]
},
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"allowed-stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"excluded-stacks": {
"data": [
{
"id": "st-ksVruWHkgjHVB8zM",
"type": "stacks"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
],
"links": {
"self": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20"
},
"meta": {
"pagination": {
"current-page": 1,
"prev-page": null,
"next-page": null,
"total-pages": 1,
"total-count": 1
},
"status-counts": {
"total": 1,
"matching": 1
}
}
}
List Agents
GET /agent-pools/:agent_pool_id/agents
Parameter | Description |
---|---|
:agent_pool_id | The ID of the Agent Pool to list. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agents" ) | Success |
404 | JSON API error object | Agent Pool not found, or user unauthorized to perform action |
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[last-ping-since] | Optional. Accepts a date in ISO8601 format (ex. 2020-08-11T10:41:23Z ). |
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 agents per page. |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/agents
Sample Response
{
"data": [
{
"id": "agent-A726QeosTCpCumAs",
"type": "agents",
"attributes": {
"name": "my-cool-agent",
"status": "idle",
"ip-address": "123.123.123.123",
"last-ping-at": "2020-10-09T18:52:25.246Z"
},
"links": {
"self": "/api/v2/agents/agent-A726QeosTCpCumAs"
}
},
{
"id": "agent-4cQzjbr1cnM6Pcxr",
"type": "agents",
"attributes": {
"name": "my-other-cool-agent",
"status": "exited",
"ip-address": "123.123.123.123",
"last-ping-at": "2020-08-12T15:25:09.726Z"
},
"links": {
"self": "/api/v2/agents/agent-4cQzjbr1cnM6Pcxr"
}
},
{
"id": "agent-yEJjXQCucpNxtxd2",
"type": "agents",
"attributes": {
"name": null,
"status": "errored",
"ip-address": "123.123.123.123",
"last-ping-at": "2020-08-11T06:22:20.300Z"
},
"links": {
"self": "/api/v2/agents/agent-yEJjXQCucpNxtxd2"
}
}
],
"links": {
"self": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20"
},
"meta": {
"pagination": {
"current-page": 1,
"prev-page": null,
"next-page": null,
"total-pages": 1,
"total-count": 3
}
}
}
Show an Agent Pool
GET /agent-pools/:id
Parameter | Description |
---|---|
:id | The ID of the Agent Pool to show |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agent-pools" ) | Success |
404 | JSON API error object | Agent Pool not found, or user unauthorized to perform action |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
Sample Response
{
"data": {
"id": "apool-yoGUFz5zcRMMz53i",
"type": "agent-pools",
"attributes": {
"name": "example-pool",
"created-at": "2020-08-05T18:10:26.964Z",
"organization-scoped": false
},
"relationships": {
"agents": {
"links": {
"related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
},
"authentication-tokens": {
"links": {
"related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
},
"workspaces": {
"data": [
{
"id": "ws-9EEkcEQSA3XgWyGe",
"type": "workspaces"
}
]
},
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"allowed-stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"excluded-stacks":
"data": [
{
"id": "st-ksVruWHkgjHVB8zM",
"type": "stacks"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
Show an Agent
GET /agents/:id
Parameter | Description |
---|---|
:id | The ID of the agent to show |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agents" ) | Success |
404 | JSON API error object | Agent not found, or user unauthorized to perform action |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
Sample Response
{
"data": {
"id": "agent-Zz9PTEcUgBtYzht8",
"type": "agents",
"attributes": {
"name": "my-agent",
"status": "busy",
"ip-address": "123.123.123.123",
"last-ping-at": "2020-09-08T18:47:35.361Z"
},
"links": {
"self": "/api/v2/agents/agent-Zz9PTEcUgBtYzht8"
}
}
}
This endpoint lists details about an agent along with that agent's status. Learn more about agents statuses.
Delete an Agent
DELETE /agents/:id
Parameter | Description |
---|---|
:id | The ID of the agent to delete |
Status | Response | Reason |
---|---|---|
204 | No Content | Success |
412 | JSON API error object | Agent is not deletable. Agents must have a status of unknown , errored , or exited before being deleted. |
404 | JSON API error object | Agent not found, or user unauthorized to perform action |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--request DELETE \
https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ
Create an Agent Pool
POST /organizations/:organization_name/agent-pools
Parameter | Description |
---|---|
:organization_name | The name of the organization. |
This endpoint allows you to create an Agent Pool for an organization. Only one Agent Pool may exist for an organization.
Status | Response | Reason |
---|---|---|
201 | JSON API document (type: "agent-pools" ) | Agent Pool successfully created |
404 | JSON API error object | Organization not found or user unauthorized to perform action |
422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
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 "agent-pools" . | |
data.attributes.name | string | The name of the agent pool, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. | |
data.attributes.organization-scoped | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. |
data.relationships.allowed-workspaces.data.type | string | Must be "workspaces" . | |
data.relationships.allowed-workspaces.data.id | string | The ID of the workspace that has permission to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces. | |
data.relationships.allowed-stacks.data.type | string | Must be "stacks" . Only available in HCP Terraform. | |
data.relationships.allowed-stacks.data.id | string | The ID of the stack that has permission to use the agent pool. Only available in HCP Terraform, refer to Scope agent pools to learn more. | |
data.relationships.allowed-projects.data.type | string | Must be "projects" . Refer to Scoping Agent Pools to Specific Projects. | |
data.relationships.allowed-projects.data.id | string | The ID of the project that has permission to use the agent pool. | |
data.relationships.excluded-workspaces.data.type | string | Must be "workspaces" . | |
data.relationships.excluded-workspaces.data.id | string | The ID of the workspace that is excluded from the scope of the agent pool. | |
data.relationships.excluded-stacks.data.type | string | Must be "stacks" . Only available in HCP Terraform. | |
data.relationships.excluded-stacks.data.id | string | The ID of the Stack that is excluded from the scope of the agent pool. Only available in HCP Terraform. |
Sample Payload
{
"data": {
"type": "agent-pools",
"attributes": {
"name": "my-pool",
"organization-scoped": false
},
"relationships": {
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"excluded-stacks":
"data": [
{
"id": "st-ksVruWHkgjHVB8zM",
"type": "stacks"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
}
}
}
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/organizations/my-organization/agent-pools
Sample Response
{
"data": {
"id": "apool-55jZekR57npjHHYQ",
"type": "agent-pools",
"attributes": {
"name": "my-pool",
"created-at": "2020-10-13T16:32:45.165Z",
"organization-scoped": false,
},
"relationships": {
"agents": {
"links": {
"related": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/agents"
}
},
"authentication-tokens": {
"links": {
"related": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/authentication-tokens"
}
},
"workspaces": {
"data": []
},
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"stacks": {
"data": []
},
"allowed-stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"excluded-stacks":
"data": [
{
"id": "st-ksVruWHkgjHVB8zM",
"type": "stacks"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ"
}
}
}
Update an Agent Pool
PATCH /agent-pools/:id
Parameter | Description |
---|---|
:id | The ID of the Agent Pool to update |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "agent-pools" ) | Success |
404 | JSON API error object | Agent Pool not found, or user unauthorized to perform action |
422 | JSON error document | Malformed request body (missing attributes, wrong types, etc.) |
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 "agent-pools" . | |
data.attributes.name | string | (previous value) | The name of the agent pool, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. |
data.attributes.organization-scoped | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. |
data.relationships.allowed-workspaces.data.type | string | Must be "workspaces" . | |
data.relationships.allowed-workspaces.data.id | string | The ID of the workspace that has permission to use the agent pool. Refer to Scoping Agent Pools to Specific Workspaces. | |
data.relationships.allowed-stacks.data.type | string | Must be "stacks" . Only available in HCP Terraform. | |
data.relationships.allowed-stacks.data.id | string | The ID of the Stack that has permission to use the agent pool. Only available in HCP Terraform, refer to Scope agent pools to learn more. | |
data.relationships.allowed-projects.data.type | string | Must be "projects" . Refer to Scoping Agent Pools to Specific Projects. | |
data.relationships.allowed-projects.data.id | string | The ID of the project that has permission to use the agent pool. | |
data.relationships.excluded-workspaces.data.type | string | Must be "workspaces" . | |
data.relationships.excluded-workspaces.data.id | string | The ID of the workspace that is excluded from the scope of the agent pool. | |
data.relationships.excluded-stacks.data.type | string | Must be "stacks" . Only available in HCP Terraform. | |
data.relationships.excluded-stacks.data.id | string | The ID of the Stack that is excluded from the scope of the agent pool. Only available in HCP Terraform. |
Sample Payload
{
"data": {
"type": "agent-pools",
"attributes": {
"name": "example-pool",
"organization-scoped": false
},
"relationships": {
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"allowed-stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"excluded-stacks":
"data": [
{
"id": "st-ksVruWHkgjHVB8zM",
"type": "stacks"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
}
}
}
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/agent-pools/apool-MCf6kkxu5FyHbqhd
Sample Response
{
"data": {
"id": "apool-yoGUFz5zcRMMz53i",
"type": "agent-pools",
"attributes": {
"name": "example-pool",
"created-at": "2020-08-05T18:10:26.964Z"
},
"relationships": {
"agents": {
"links": {
"related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents"
}
},
"authentication-tokens": {
"links": {
"related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens"
}
},
"workspaces": {
"data": [
{
"id": "ws-9EEkcEQSA3XgWyGe",
"type": "workspaces"
}
]
},
"allowed-workspaces": {
"data": [
{
"id": "ws-x9taqV23mxrGcDrn",
"type": "workspaces"
}
]
},
"excluded-workspaces":
"data": [
{
"id": "ws-KyBgj8dDRvQqwBCC",
"type": "workspaces"
}
]
},
"stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"allowed-stacks": {
"data": [
{
"id": "st-udYJjMCsnxU87uur",
"type": "stacks"
}
]
},
"excluded-stacks":
"data": [
{
"id": "st-ksVruWHkgjHVB8zM",
"type": "stacks"
}
]
},
"allowed-projects": {
"data": [
{
"id": "prj-WsVcWRr7SfxRci1v",
"type": "projects"
}
]
}
},
"links": {
"self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i"
}
}
}
Delete an Agent Pool
DELETE /agent-pools/:agent_pool_id
Parameter | Description |
---|---|
:agent_pool_id | The ID of the agent pool ID to delete |
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd
Available Related Resources
The GET endpoints above can optionally return related resources, if requested with the include
query parameter. The following resource types are available:
Resource Name | Description |
---|---|
workspaces | The workspaces attached to this agent pool. |
stacks | The Stacks attached to this agent pool. Only available in HCP Terraform. |