Bulk actions API reference

Call the /bulk-actions endpoints to add, remove, or set tags on registry artifacts, such as modules, providers, and Stacks components, in a single request.

Requirements

To successfully call the endpoints:

All target resources must be the same type. For example, you cannot modify a registry module and a registry provider in the same request.
All target resources must reside in the same organization. Even if you have access to more than one organization, you cannot update artifacts in different organizations in the same request.
You must have permission to all artifacts you are attempting to update in the request. If the request includes an artifact that you don't have permission to access, HCP Terraform won't update any of the artifacts.

Add tags in bulk

POST /api/v2/tag-bindings/bulk-actions/add

Adds the specified tags to the target artifacts. If a target already contains a tag, then HCP Terraform ignores that tag for that target.

Status	Response	Reason
201	JSON API document (`type: "tag-binding-bulk-actions"`)	Successfully scheduled the bulk action job
400	JSON API error object	Malformed request body, such as missing relationships or bad types
404	JSON API error object	User not authorized to modify one or more target artifacts

Request body

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

Key path	Type	Description
`data.type`	string	Must be `"tag-binding-bulk-actions"`.
`data.relationships.targets.data`	array	A list of target artifacts to modify. Each target is a resource identifier object with an `id` and a `type`. You can specify up to 100 targets, and all targets must be the same type and reside in the same organization.
`data.relationships.targets.data[].id`	string	The ID of the target artifact. For example, `mod-WKZBbsFkTExqosLi`.
`data.relationships.targets.data[].type`	string	The JSON API type of the target artifact. For example, `"registry-modules"`.
`data.relationships.tag-bindings.data`	array	A list of tag bindings to apply to each target. You can specify up to 30 tags.
`data.relationships.tag-bindings.data[].type`	string	Must be `"tag-bindings"`.
`data.relationships.tag-bindings.data[].attributes.key`	string	The key of the tag to apply.
`data.relationships.tag-bindings.data[].attributes.value`	string	Optional. The value of the tag to apply.

Sample payload

{
  "data": {
    "type": "tag-binding-bulk-actions",
    "relationships": {
      "targets": {
        "data": [
          {
            "id": "mod-0sjfdIFGxina62",
            "type": "registry-modules"
          },
          {
            "id": "mod-Ofmdsjng3dY8P",
            "type": "registry-modules"
          }
        ]
      },
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "DEPT",
              "value": "ENG"
            }
          }
        ]
      }
    }
  }
}

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/tag-bindings/bulk-actions/add

Sample response

HCP Terraform validates and authorizes the payload, schedules the action, and returns a unique job ID and polling URL that you can use to determine when the job completes and the result of the job.

{
  "data": {
    "id": "bulktagging-wP2UDHA24HH",
    "type": "tag-binding-bulk-actions",
    "attributes": {
      "status": "pending",
      "action": "add",
      "target-type": "registry-modules"
    },
    "links": {
      "self": "/api/v2/tag-bindings/bulk-actions/398"
    }
  }
}

Remove tags in bulk

POST /api/v2/tag-bindings/bulk-actions/remove

Removes the specified tags from the target artifacts. If a target does not contain a tag, then HCP Terraform ignores that tag for that target.

Status	Response	Reason
201	JSON API document (`type: "tag-binding-bulk-actions"`)	Successfully scheduled the bulk action job
400	JSON API error object	Malformed request body, such as missing relationships or bad types
404	JSON API error object	User not authorized to modify one or more target artifacts

Request body

This endpoint uses the same request body as the add tags in bulk endpoint.

Properties without a default value are required.

Key path	Type	Description
`data.type`	string	Must be `"tag-binding-bulk-actions"`.
`data.relationships.targets.data`	array	A list of target artifacts to modify. Each target is a resource identifier object with an `id` and a `type`. You can specify up to 100 targets, and all targets must be the same type and reside in the same organization.
`data.relationships.targets.data[].id`	string	The ID of the target artifact. For example, `mod-WKZBbsFkTExqosLi`.
`data.relationships.targets.data[].type`	string	The JSON API type of the target artifact. For example, `"registry-modules"`.
`data.relationships.tag-bindings.data`	array	A list of tag bindings to remove from each target. You can specify up to 30 tags.
`data.relationships.tag-bindings.data[].type`	string	Must be `"tag-bindings"`.
`data.relationships.tag-bindings.data[].attributes.key`	string	The key of the tag to remove.
`data.relationships.tag-bindings.data[].attributes.value`	string	Optional. The value of the tag to remove.

Sample payload

{
  "data": {
    "type": "tag-binding-bulk-actions",
    "relationships": {
      "targets": {
        "data": [
          {
            "id": "mod-WKZBbsFkTExqosLi",
            "type": "registry-modules"
          },
          {
            "id": "mod-pjcbMFbKWEFNW5b6",
            "type": "registry-modules"
          }
        ]
      },
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": { "key": "foo" }
          },
          {
            "type": "tag-bindings",
            "attributes": { "key": "bar", "value": "baz" }
          }
        ]
      }
    }
  }
}

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/tag-bindings/bulk-actions/remove

Sample response

{
  "data": {
    "id": "bulktagging-5EbJFSDO48RT",
    "type": "tag-binding-bulk-actions",
    "attributes": {
      "status": "pending",
      "action": "add",
      "target-type": "registry-modules"
    },
    "links": {
      "self": "/api/v2/tag-bindings/bulk-actions/400"
    }
  }
}

Set tags in bulk

POST /tag-bindings/bulk-actions/set

Replaces all tags on the target artifacts with the specified tags.

Status	Response	Reason
201	JSON API document (`type: "tag-binding-bulk-actions"`)	Successfully scheduled the bulk action job
400	JSON API error object	Malformed request body, such as missing relationships or bad types
404	JSON API error object	User not authorized to modify one or more target artifacts

Request body

This endpoint uses the same request body as the add tags in bulk endpoint.

Properties without a default value are required.

Key path	Type	Description
`data.type`	string	Must be `"tag-binding-bulk-actions"`.
`data.relationships.targets.data`	array	A list of target artifacts to modify. Each target is a resource identifier object with an `id` and a `type`. You can specify up to 100 targets, and all targets must be the same type and reside in the same organization.
`data.relationships.targets.data[].id`	string	The ID of the target artifact. For example, `mod-WKZBbsFkTExqosLi`.
`data.relationships.targets.data[].type`	string	The JSON API type of the target artifact. For example, `"registry-modules"`.
`data.relationships.tag-bindings.data`	array	A list of tag bindings that replaces all existing tags on each target. You can specify up to 30 tags.
`data.relationships.tag-bindings.data[].type`	string	Must be `"tag-bindings"`.
`data.relationships.tag-bindings.data[].attributes.key`	string	The key of the tag to set.
`data.relationships.tag-bindings.data[].attributes.value`	string	Optional. The value of the tag to set.

Sample payload

{
  "data": {
    "type": "tag-binding-bulk-actions",
    "relationships": {
      "targets": {
        "data": [
          {
            "id": "mod-0sjfdIFGxina62",
            "type": "registry-modules"
          },
          {
            "id": "mod-Ofmdsjng3dY8P",
            "type": "registry-modules"
          }
        ]
      },
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "DEPT",
              "value": "ENG"
            }
          }
        ]
      }
    }
  }
}

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/tag-bindings/bulk-actions/set

Sample response

{
  "data": {
    "id": "bulktagging-5fsdWRFg198RT",
    "type": "tag-binding-bulk-actions",
    "attributes": {
      "status": "pending",
      "action": "add",
      "target-type": "registry-modules"
    },
    "links": {
      "self": "/api/v2/tag-bindings/bulk-actions/400"
    }
  }
}

Error responses

When you process changes in bulk, one or more resources might fail to update. In this case, HCP Terraform sends an HTTP error code with a JSON API error payload for each failure. When HCP Terraform returns an error response, it modifies no artifacts.

An HTTP 400 response occurs when the request is malformed. For example, the request is missing required relationships, contains bad data types, or fails to comply with the resource and organization requirements.

{
  "errors": [
    {
      "status": "400",
      "title": "bad request",
      "detail": "Missing targets relationship",
      "source": {
        "pointer": "/data/relationships"
      }
    }
  ]
}

Get a bulk tagging job status

After HCP Terraform schedules a bulk action job, query the following endpoint to get the status and result of the job:

GET api/v2/tag-bindings/bulk-actions/:id

Parameter	Description
`:id`	The ID of the bulk action job to read.

Response codes

Status	Response	Reason
200	JSON API document (`type: "tag-binding-bulk-actions"`)	The request was successful
404	JSON API error object	Job not found or user not authorized to read the job

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  https://app.terraform.io/api/v2/tag-bindings/bulk-actions/bulktagging-WKZBbsFkTExqosLi

Sample responses

HCP Terraform sends this response when a job has completed and all targets were processed successfully.

{
  "data": {
    "id": "bulktagging-5EbPPFG5Qng198RT",
    "type": "tag-binding-bulk-actions",
    "attributes": {
      "status": "completed",
      "action": "add",
      "target-type": "registry-modules",
      "targets": [
        "mod-ntUw7VH1a2WNNoMy",
        "mod-7Ecnpevu8A6TGnhB"
      ]
    },
    "links": {
      "self": "/api/v2/tag-bindings/bulk-actions/400"
    }
  }
}

HCP Terraform sends this response when a job has completed and encountered one or more errors during processing.

{
  "data": {
    "id": "bulktagging-WKZBbsFkTExqosLi",
    "type": "tag-binding-bulk-actions",
    "attributes": {
      "status": "errored",
      "errors": {
        "mod-gxuxGdrprxrAPqU7": "cannot have more than 10 tags"
      },
      "targets": [
        "mod-gxuxGdrprxrAPqU7",
        "mod-oegt7LFC2yAw6ZJu"
      ],
      "target_type": "registry-modules"
    },
    "links": {
      "self": "/api/v2/tag-bindings/bulk-actions/bulktagging-WKZBbsFkTExqosLi"
    }
  }
}

HCP Terraform sends this response when a job has yet to complete.

{
  "data": {
    "id": "bulktagging-5EbPPFG5Qng198RT",
    "type": "tag-binding-bulk-actions",
    "attributes": {
      "status": "pending",
      "action": "add",
      "target-type": "registry-modules"
    },
    "links": {
      "self": "/api/v2/tag-bindings/bulk-actions/400"
    }
  }
}