From de9034f333f0a7da7a41f98f3ecf0617f50f7d0f Mon Sep 17 00:00:00 2001 From: Sowju Sutherland Date: Wed, 22 Oct 2025 16:27:16 -0700 Subject: [PATCH 1/2] Adds documentation for queries api --- .../cloud-docs/api-docs/queries/index.mdx | 425 ++++++++++++++++++ 1 file changed, 425 insertions(+) create mode 100644 content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx new file mode 100644 index 000000000..a380f66d8 --- /dev/null +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx @@ -0,0 +1,425 @@ +--- +page_title: /queries API reference for HCP Terraform +description: Call the HCP Terraform API's `/queries` endpoint to create and manage query runs. +tfc_only: true +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents + +[JSON API error object]: http://jsonapi.org/format/#error-objects + +# Query API reference + +Call query API endpoints to execute query runs against your HCP Terraform workspaces. Query runs retrieve information about workspace resources and configurations. They are asynchronous operations that you can monitor for status and results. + +## Overview + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +|----------|-------------------------------------------------- |------------------------------------------------------------------------------------------------------------| +| `POST` | `/queries` | Call this endpoint to [create a query run](#create-a-query-run). | +| `GET` | `/queries/:query_id` | Call this endpoint to [show a query run](#show-a-query-run). | +| `POST` | `/queries/:query_id/actions/cancel` | Call this endpoint to [cancel a query run](#cancel-a-query-run). | +| `GET` | `/workspaces/:workspace_id/queries` | Call this endpoint to [list query runs for a workspace](#list-query-runs-for-a-workspace). | + +## Create a query run + +This endpoint creates a new query run. + +`POST /queries` + +| Status | Response | Reason | +|---------|---------------------------|-----------------------------------------------------------------------| +| [201][] | [JSON API document][] | Successfully created a query run. | +| [404][] | [JSON API error object][] | Not found or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body, such as missing attributes and wrong types. | +| [500][] | [JSON API error object][] | Internal system failure. | + + +### 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 `"queries"`. | +| `data.attributes.source` | string | | The source of the query such as query content or reference. | +| `data.attributes.variables` | array[{key, value}] | (empty array) | Specifies an optional list of run-specific variable values. Refer to run-specific variables for details. | +| `data.relationships.workspace.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.workspace.data.id` | string | | The ID of the workspace to run the query against. | +| `data.relationships.configuration-version.data.type` | string | | Must be `"configuration-versions"`. | +| `data.relationships.configuration-version.data.id` | string | | The ID of the configuration version to use for the query. | + +### Sample Payload + +```json +{ + "data": { + "type": "queries", + "attributes": { + "source": "example-query-content", + "variables": [ + { "key": "replicas", "value": "2" } + ] + }, + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-ABC123" + } + }, + "configuration-version": { + "data": { + "type": "configuration-versions", + "id": "cv-XYZ789" + } + } + } + } +} +``` + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/queries +``` + +### Sample Response + +```json +{ + "data": { + "id": "query-ABC123", + "type": "queries", + "attributes": { + "actions": { + "is-cancelable": true, + "is-force-cancelable": false + }, + "canceled-at": null, + "updated-at": "2025-01-15T10:30:00.000Z", + "created-at": "2025-01-15T10:30:00.000Z", + "source": "example-query-content", + "variables": [ + { "key": "replicas", "value": "2" } + ], + "status-timestamps": { + "pending-at": "2025-01-15T10:30:00.000Z", + "queued-at": null, + "errored-at": null, + "canceled-at": null, + "running-at": null, + "finished-at": null + }, + "status": "pending", + "log-read-url": "https://archivist.terraform.io/v1/object/...", + }, + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-ABC123" + } + }, + "configuration-version": { + "data": { + "type": "configuration-versions", + "id": "cv-XYZ789" + } + }, + "created-by": { + "data": { + "type": "users", + "id": "user-123" + } + }, + "canceled-by": { + "data": null + } + }, + "links": { + "self": "/api/v2/queries/query-ABC123" + } + } +} +``` + +## List query runs for a workspace + +This endpoint lists query runs for a particular workspace. + +`GET /workspaces/:workspace_id/queries` + +| Parameter | Description | +|------------------|-------------------------------------------------------| +| `:workspace_id` | The ID of the workspace to list query runs for. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters). You must use percent-style encoding `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +|----------------|------------------------------------------------------------------------------| +| `page[number]` | Optional. If omitted, the endpoint returns the first page. | +| `page[size]` | Optional. If omitted, the endpoint returns 20 query runs per page. | + +| Status | Response | Reason | +|---------|---------------------------|----------------------------------------------------------------| +| [200][] | [JSON API document][] | Successfully retrieved the list of query runs. | +| [404][] | [JSON API error object][] | Not found or the user is unauthorized to perform this action. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "query-ABC123", + "type": "queries", + "attributes": { + "canceled-at": null, + "updated-at": "2025-01-15T10:35:00.000Z", + "created-at": "2025-01-15T10:30:00.000Z", + "source": "example-query-content", + "variables": [ + { "key": "replicas", "value": "2" } + ], + "status-timestamps": { + "pending-at": "2025-01-15T10:30:00.000Z", + "queued-at": "2025-01-15T10:30:05.000Z", + "errored-at": null, + "canceled-at": null, + "running-at": "2025-01-15T10:30:10.000Z", + "finished-at": "2025-01-15T10:35:00.000Z" + }, + "status": "finished", + "log-read-url": "https://archivist.terraform.io/v1/object/..." + }, + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-ABC123" + } + }, + "configuration-version": { + "data": { + "type": "configuration-versions", + "id": "cv-XYZ789" + } + }, + "created-by": { + "data": { + "type": "users", + "id": "user-123" + } + }, + "canceled-by": { + "data": null + } + }, + "links": { + "self": "/api/v2/queries/query-ABC123" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show a query run + +This endpoint shows details for a specific query run. + +`GET /queries/:query_id` + +| Parameter | Description | +|-------------|------------------------------------------| +| `:query_id` | The ID of the query run to retrieve. | + +| Status | Response | Reason | +|---------|---------------------------|----------------------------------------------------------------| +| [200][] | [JSON API document][] | Successfully retrieved the query run. | +| [404][] | [JSON API error object][] | Not found or the user is unauthorized to perform this action. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/queries/query-ABC123 +``` + +### Sample Response + +```json +{ + "data": { + "id": "query-ABC123", + "type": "queries", + "attributes": { + "actions": { + "is-cancelable": true, + "is-force-cancelable": false + }, + "canceled-at": null, + "updated-at": "2025-01-15T10:30:15.000Z", + "created-at": "2025-01-15T10:30:00.000Z", + "source": "example-query-content", + "variables": [ + { "key": "replicas", "value": "2" } + ], + "status-timestamps": { + "pending-at": "2025-01-15T10:30:00.000Z", + "queued-at": "2025-01-15T10:30:05.000Z", + "errored-at": null, + "canceled-at": null, + "running-at": "2025-01-15T10:30:10.000Z", + "finished-at": null + }, + "status": "running", + "log-read-url": "https://archivist.terraform.io/v1/object/...", + }, + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-ABC123" + } + }, + "configuration-version": { + "data": { + "type": "configuration-versions", + "id": "cv-XYZ789" + } + }, + "created-by": { + "data": { + "type": "users", + "id": "user-123" + } + }, + "canceled-by": { + "data": null + } + }, + "links": { + "self": "/api/v2/queries/query-ABC123" + } + } +} +``` + +## Cancel a query run + +This endpoint cancels a query run that is currently pending or running. + +`POST /queries/:query_id/actions/cancel` + +| Parameter | Description | +|-------------|--------------------------------------| +| `:query_id` | The ID of the query run to cancel. | + +| Status | Response | Reason | +|---------|---------------------------|-----------------------------------------------------------------------| +| [202][] | Empty body | Successfully canceled the query run. | +| [409][] | [JSON API error object][] | Failed to transition query run to a canceled state. | + +### Sample Request + +```shell +$ curl\ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/queries/query-ABC123/actions/cancel +``` + +## Query run attributes + +Query runs have the following attributes: + +### Status + +The `status` attribute indicates the current state of the query run. Possible values are: + +- `pending`: The query run has been created but is not yet queued for execution. +- `running`: The query run is currently executing. +- `finished`: The query run completed successfully. +- `canceled`: The query run was canceled before completion. +- `errored`: The query run encountered an error during execution. + +### Status timestamps + +The `status-timestamps` object contains timestamps for when the query run entered each status: + +- `pending-at`: When the query run was created. +- `queued-at`: When the query run was queued for execution. +- `running-at`: When the query run started executing. +- `finished-at`: When the query run completed successfully. +- `errored-at`: When the query run encountered an error. +- `canceled-at`: When the query run was canceled. + +### Log read URL + +The `log-read-url` attribute contains a URL to retrieve the logs for the query run. + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with the [`include`](/terraform/cloud-docs/api-docs#inclusion-of-related-resources) query parameter. The following resource types are available: + +- `created-by` - The user who created the query run. +- `configuration-version` - The configuration version used for the query run. +- `configuration_version.ingress_attributes` - The ingress attributes for the configuration version used for the query run. From 6d3f124c367690dcef08f37e5e10c8f03c889e59 Mon Sep 17 00:00:00 2001 From: Sowju Sutherland Date: Fri, 31 Oct 2025 12:50:29 -0700 Subject: [PATCH 2/2] Adds Queries to side navigation an reorganizes the List Queries to appear after Create --- content/terraform-docs-common/data/cloud-docs-nav-data.json | 1 + .../docs/cloud-docs/api-docs/queries/index.mdx | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/content/terraform-docs-common/data/cloud-docs-nav-data.json b/content/terraform-docs-common/data/cloud-docs-nav-data.json index b387ddb01..2de6c7df1 100644 --- a/content/terraform-docs-common/data/cloud-docs-nav-data.json +++ b/content/terraform-docs-common/data/cloud-docs-nav-data.json @@ -809,6 +809,7 @@ }, { "title": "Projects", "path": "api-docs/projects" }, { "title": "Project team access", "path": "api-docs/project-team-access" }, + { "title": "Queries", "path": "api-docs/queries" }, { "title": "Reserved tag keys", "path": "api-docs/reserved-tag-keys"}, { "title": "Runs", "path": "api-docs/run" }, { diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx index a380f66d8..dac41ece1 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx @@ -35,9 +35,10 @@ The scope of the API includes the following endpoints: | Method | Path | Action | |----------|-------------------------------------------------- |------------------------------------------------------------------------------------------------------------| | `POST` | `/queries` | Call this endpoint to [create a query run](#create-a-query-run). | +| `GET` | `/workspaces/:workspace_id/queries` | Call this endpoint to [list query runs for a workspace](#list-query-runs-for-a-workspace). | | `GET` | `/queries/:query_id` | Call this endpoint to [show a query run](#show-a-query-run). | | `POST` | `/queries/:query_id/actions/cancel` | Call this endpoint to [cancel a query run](#cancel-a-query-run). | -| `GET` | `/workspaces/:workspace_id/queries` | Call this endpoint to [list query runs for a workspace](#list-query-runs-for-a-workspace). | + ## Create a query run