> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/run-terraform/workspaces/api-driven-workflow.md).

# API-driven Workflow

Anything the UI does can be done over the [API](/2.34.0/api-reference/getting-started.md), so you can start runs from your own pipeline or tooling. For GitHub Actions, see [CI/CD Integration](/2.34.0/integrate/ci-cd-integration.md); for the Terraform CLI, see [CLI-driven Workflow](/2.34.0/run-terraform/workspaces/cli-driven-workflow.md).

### Start a run

Create a `job` for a workspace with the template to run:

```bash
curl -X POST "$TERRAKUBE_API/api/v1/organization/$ORG_ID/job" \
  -H "Authorization: Bearer $TERRAKUBE_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "job",
      "attributes": {
        "templateReference": "<template id>",
        "overrideBranch": "main"
      },
      "relationships": {
        "workspace": { "data": { "type": "workspace", "id": "<workspace id>" } }
      }
    }
  }'
```

Creating a job needs permission to plan in the workspace. Poll the job (`GET .../job/{id}`) or subscribe to status changes until it reaches `waitingApproval`, `completed` or a failure.

### Variables for one run

Pass `variables` on the job to set Terraform input variables for that run only, without touching the workspace's stored variables. This is how CI can forward values such as `TF_VAR_image_tag`:

```json
"attributes": {
  "templateReference": "<template id>",
  "variables": { "image_tag": "release-42" }
}
```

* A run variable replaces a workspace or template variable with the same name. `-var` and variable files keep Terraform's normal precedence.
* Values are encrypted, never returned by the API, and kept with the run so a saved-plan apply uses the same values. The run page lists the variable **names**.
* Up to 100 variables and 64 KiB in total. Names must be valid Terraform variable names.
* You need rights to manage the workspace (the same as editing its variables). A plan-only user can create jobs but not send `variables`.
* The plan file contains input values, as it does for workspace variables. Mark secrets `sensitive = true`.

### Approve or discard

A run waiting for approval is approved by updating the job's status to `approved`, or discarded with `rejected`, by a user in the template's approval team. Terrakube records who approved the run and when.

### Large lists

Page through collections with `page[number]` and `page[size]`. The workspaces query on the GraphQL endpoint (`/graphql/api/v1`) also supports cursor pagination, which stays fast on organizations with thousands of workspaces.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terrakube.io/2.34.0/run-terraform/workspaces/api-driven-workflow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.