For the complete documentation index, see llms.txt. This page is also available as Markdown.

Jobs

This endpoint is used to create, update, search or delete jobs for a particular Terrakube workspace.

Entity fields:

Path
Type
Description

data.type

string

Should be "job"

data.attributes.overrideBranch

string

Branch that will be use to execute the job

data.attributes.templateReference

string

Terrakube template id to use when running the job

data.relationships.workspace.data.type

string

Should be "workspace"

data.relationships.workspace.data.Id

string

Should be the VCS Workspace Id (OPTIONAL)

To better understand Terrakube Configuration Language job templates please refer to the following GitHub repository.

Example:

{
  "data": {
    "type": "job",
    "attributes": {
      "overrideBranch": "main"
      "templateReference": "XXXXXXXXX"
    },
    "relationships":{
        "workspace":{
            "data":{
                "type": "workspace",
                "id": "{{workspaceId}}"
            }
        }
    }
  }
}

Supported Operations

post

Creates an item of type job and adds it to job

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
organizationIdstringRequired

organization Identifier

Body
Responses
201

Successful response

application/vnd.api+json
post/organization/{organizationId}/job
POST /api/v1/organization/{organizationId}/job HTTP/1.1
Host: terrakube-api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 1082

{
  "data": {
    "type": "text",
    "id": "text",
    "attributes": {
      "approvalTeam": null,
      "approvedAt": null,
      "approvedBy": null,
      "cascadeDepth": null,
      "comments": null,
      "commitId": null,
      "createdBy": null,
      "createdDate": null,
      "dispatchFailureCount": null,
      "dispatchFirstFailureAt": null,
      "dispatchLastAttemptAt": null,
      "dispatchLastError": null,
      "dispatchNextRetryAt": null,
      "encryptedVariables": null,
      "output": null,
      "overrideBranch": null,
      "overrideSource": null,
      "planChanges": null,
      "prCommentError": null,
      "prNumber": null,
      "refresh": null,
      "refreshOnly": null,
      "replaceAddrs": null,
      "resolvedTerraformVersion": null,
      "status": null,
      "targetAddrs": null,
      "templateReference": null,
      "terraformPlan": null,
      "terraformPlanArtifacts": null,
      "terraformPlanArtifactsChecksum": null,
      "triggeredByJobId": null,
      "updatedBy": null,
      "updatedDate": null,
      "variableNames": null,
      "variables": null,
      "variablesAsArguments": null,
      "via": null
    },
    "relationships": {
      "address": {
        "data": [
          null
        ]
      },
      "organization": {
        "data": [
          null
        ]
      },
      "policyEvaluation": {
        "data": [
          null
        ]
      },
      "step": {
        "data": [
          null
        ]
      },
      "workspace": {
        "data": [
          null
        ]
      }
    }
  },
  "included": [
    {
      "type": "text",
      "id": "text",
      "attributes": {},
      "relationships": {}
    }
  ]
}
201

Successful response

{
  "data": {
    "type": "text",
    "id": "text",
    "attributes": {
      "approvalTeam": null,
      "approvedAt": null,
      "approvedBy": null,
      "cascadeDepth": null,
      "comments": null,
      "commitId": null,
      "createdBy": null,
      "createdDate": null,
      "dispatchFailureCount": null,
      "dispatchFirstFailureAt": null,
      "dispatchLastAttemptAt": null,
      "dispatchLastError": null,
      "dispatchNextRetryAt": null,
      "encryptedVariables": null,
      "output": null,
      "overrideBranch": null,
      "overrideSource": null,
      "planChanges": null,
      "prCommentError": null,
      "prNumber": null,
      "refresh": null,
      "refreshOnly": null,
      "replaceAddrs": null,
      "resolvedTerraformVersion": null,
      "status": null,
      "targetAddrs": null,
      "templateReference": null,
      "terraformPlan": null,
      "terraformPlanArtifacts": null,
      "terraformPlanArtifactsChecksum": null,
      "triggeredByJobId": null,
      "updatedBy": null,
      "updatedDate": null,
      "variableNames": null,
      "variables": null,
      "variablesAsArguments": null,
      "via": null
    },
    "relationships": {
      "address": {
        "data": [
          null
        ]
      },
      "organization": {
        "data": [
          null
        ]
      },
      "policyEvaluation": {
        "data": [
          null
        ]
      },
      "step": {
        "data": [
          null
        ]
      },
      "workspace": {
        "data": [
          null
        ]
      }
    }
  },
  "included": [
    {
      "type": "text",
      "id": "text",
      "attributes": {},
      "relationships": {}
    }
  ]
}
get

Returns an instance of type job

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
organizationIdstringRequired

organization Identifier

jobIdstringRequired

job Identifier

Query parameters
Responses
200

Successful response

application/vnd.api+json
get/organization/{organizationId}/job/{jobId}
GET /api/v1/organization/{organizationId}/job/{jobId} HTTP/1.1
Host: terrakube-api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "data": {
    "type": "text",
    "id": "text",
    "attributes": {
      "approvalTeam": null,
      "approvedAt": null,
      "approvedBy": null,
      "cascadeDepth": null,
      "comments": null,
      "commitId": null,
      "createdBy": null,
      "createdDate": null,
      "dispatchFailureCount": null,
      "dispatchFirstFailureAt": null,
      "dispatchLastAttemptAt": null,
      "dispatchLastError": null,
      "dispatchNextRetryAt": null,
      "encryptedVariables": null,
      "output": null,
      "overrideBranch": null,
      "overrideSource": null,
      "planChanges": null,
      "prCommentError": null,
      "prNumber": null,
      "refresh": null,
      "refreshOnly": null,
      "replaceAddrs": null,
      "resolvedTerraformVersion": null,
      "status": null,
      "targetAddrs": null,
      "templateReference": null,
      "terraformPlan": null,
      "terraformPlanArtifacts": null,
      "terraformPlanArtifactsChecksum": null,
      "triggeredByJobId": null,
      "updatedBy": null,
      "updatedDate": null,
      "variableNames": null,
      "variables": null,
      "variablesAsArguments": null,
      "via": null
    },
    "relationships": {
      "address": {
        "data": [
          null
        ]
      },
      "organization": {
        "data": [
          null
        ]
      },
      "policyEvaluation": {
        "data": [
          null
        ]
      },
      "step": {
        "data": [
          null
        ]
      },
      "workspace": {
        "data": [
          null
        ]
      }
    }
  },
  "included": [
    {
      "type": "text",
      "id": "text",
      "attributes": {},
      "relationships": {}
    }
  ]
}
patch

Modifies an instance of type job

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
organizationIdstringRequired

organization Identifier

jobIdstringRequired

job Identifier

Body
Responses
204

Successful response

No content

patch/organization/{organizationId}/job/{jobId}
PATCH /api/v1/organization/{organizationId}/job/{jobId} HTTP/1.1
Host: terrakube-api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 1082

{
  "data": {
    "type": "text",
    "id": "text",
    "attributes": {
      "approvalTeam": null,
      "approvedAt": null,
      "approvedBy": null,
      "cascadeDepth": null,
      "comments": null,
      "commitId": null,
      "createdBy": null,
      "createdDate": null,
      "dispatchFailureCount": null,
      "dispatchFirstFailureAt": null,
      "dispatchLastAttemptAt": null,
      "dispatchLastError": null,
      "dispatchNextRetryAt": null,
      "encryptedVariables": null,
      "output": null,
      "overrideBranch": null,
      "overrideSource": null,
      "planChanges": null,
      "prCommentError": null,
      "prNumber": null,
      "refresh": null,
      "refreshOnly": null,
      "replaceAddrs": null,
      "resolvedTerraformVersion": null,
      "status": null,
      "targetAddrs": null,
      "templateReference": null,
      "terraformPlan": null,
      "terraformPlanArtifacts": null,
      "terraformPlanArtifactsChecksum": null,
      "triggeredByJobId": null,
      "updatedBy": null,
      "updatedDate": null,
      "variableNames": null,
      "variables": null,
      "variablesAsArguments": null,
      "via": null
    },
    "relationships": {
      "address": {
        "data": [
          null
        ]
      },
      "organization": {
        "data": [
          null
        ]
      },
      "policyEvaluation": {
        "data": [
          null
        ]
      },
      "step": {
        "data": [
          null
        ]
      },
      "workspace": {
        "data": [
          null
        ]
      }
    }
  },
  "included": [
    {
      "type": "text",
      "id": "text",
      "attributes": {},
      "relationships": {}
    }
  ]
}
204

Successful response

No content

delete

Deletes an instance of type job

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
organizationIdstringRequired

organization Identifier

jobIdstringRequired

job Identifier

Responses
204

Successful response

No content

delete/organization/{organizationId}/job/{jobId}
DELETE /api/v1/organization/{organizationId}/job/{jobId} HTTP/1.1
Host: terrakube-api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
204

Successful response

No content

The complete OpenAPI specification is available as terrakube-api.json, and in the UI under Help & Support → API Docs.

Run checks in 2.34.0

Creating a job requires plan permission. Workspace branch restrictions and approval rules apply to REST/GraphQL too, and destroy runs have a separate destroyJob permission. An explicit commitId is refused for apply-capable templates when branch restriction is enabled. See Run Restrictions for the checks and defaults, and API-driven Workflow for run-only variables.

Last updated

Was this helpful?