# Jobs

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

{% hint style="warning" %}
To use this endpoint you need to create a Terrakube workspace.
{% endhint %}

### 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)         |

{% hint style="info" %}
To better understand Terrakube Configuration Language job templates please refer to the following [GitHub repository.](https://github.com/AzBuilder/terrakube-extensions)
{% endhint %}

### Example:

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

### Supported Operations

## POST /organization/{organizationId}/job

> Creates an item of type job and adds it to job

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"job"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/job":{"post":{"tags":["job"],"description":"Creates an item of type job and adds it to job","requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/job"},"included":{"uniqueItems":true,"type":"array","description":"Included resources","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object"},"relationships":{"type":"object"}}}}}}}}},"responses":{"201":{"description":"Successful response","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/job"},"included":{"uniqueItems":true,"type":"array","description":"Included resources","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object"},"relationships":{"type":"object"}}}}}}}}}}}}},"components":{"schemas":{"job":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (team manage job OR team limited manage job)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"approvalTeam":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false},"comments":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"commitId":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"createdBy":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"createdDate":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"output":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"overrideBranch":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"planChanges":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"refresh":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"refreshOnly":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"status":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team approve job OR user is a super service)","readOnly":false,"writeOnly":false,"enum":["pending","waitingApproval","approved","queue","running","completed","noChanges","notExecuted","rejected","cancelled","failed","unknown"]},"tcl":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"templateReference":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"terraformPlan":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"updatedBy":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"updatedDate":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"via":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"address":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}},"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}},"step":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["step"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false}}}},"workspace":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

## GET /organization/{organizationId}/job/{jobId}

> Returns an instance of type job

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"job"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/job/{jobId}":{"get":{"tags":["job"],"description":"Returns an instance of type job","parameters":[{"name":"fields[job]","in":"query","description":"Selects the set of job fields that should be returned in the result.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["approvalTeam","comments","commitId","createdBy","createdDate","output","overrideBranch","planChanges","refresh","refreshOnly","status","tcl","templateReference","terraformPlan","updatedBy","updatedDate","via","address","organization","step","workspace"]}}},{"name":"include","in":"query","description":"Selects the set of relationships that should be expanded as a compound document in the result.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["address","organization","step","workspace"]}}}],"responses":{"200":{"description":"Successful response","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/job"},"included":{"uniqueItems":true,"type":"array","description":"Included resources","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object"},"relationships":{"type":"object"}}}}}}}}}}}}},"components":{"schemas":{"job":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (team manage job OR team limited manage job)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"approvalTeam":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false},"comments":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"commitId":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"createdBy":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"createdDate":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"output":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"overrideBranch":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"planChanges":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"refresh":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"refreshOnly":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"status":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team approve job OR user is a super service)","readOnly":false,"writeOnly":false,"enum":["pending","waitingApproval","approved","queue","running","completed","noChanges","notExecuted","rejected","cancelled","failed","unknown"]},"tcl":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"templateReference":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"terraformPlan":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"updatedBy":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"updatedDate":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"via":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"address":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}},"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}},"step":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["step"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false}}}},"workspace":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

## PATCH /organization/{organizationId}/job/{jobId}

> Modifies an instance of type job

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"job"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/job/{jobId}":{"patch":{"tags":["job"],"description":"Modifies an instance of type job","requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/job"},"included":{"uniqueItems":true,"type":"array","description":"Included resources","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object"},"relationships":{"type":"object"}}}}}}}}},"responses":{"204":{"description":"Successful response"}}}}},"components":{"schemas":{"job":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (team manage job OR team limited manage job)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"approvalTeam":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false},"comments":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"commitId":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"createdBy":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"createdDate":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"output":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"overrideBranch":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"planChanges":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"refresh":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"refreshOnly":{"type":"boolean","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"status":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team approve job OR user is a super service)","readOnly":false,"writeOnly":false,"enum":["pending","waitingApproval","approved","queue","running","completed","noChanges","notExecuted","rejected","cancelled","failed","unknown"]},"tcl":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"templateReference":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"terraformPlan":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"updatedBy":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"updatedDate":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false},"via":{"type":"string","description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"address":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["address"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}},"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}},"step":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["step"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (user is a super service)","readOnly":false,"writeOnly":false}}}},"workspace":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["workspace"]},"id":{"type":"string"}},"description":"Read Permissions : (team view job OR team limited view job)\nUpdate Permissions : (team manage job OR team limited manage job OR user is a super service)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

## DELETE /organization/{organizationId}/job/{jobId}

> Deletes an instance of type job

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"job"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/job/{jobId}":{"delete":{"tags":["job"],"description":"Deletes an instance of type job","responses":{"204":{"description":"Successful response"}}}}}}
```

{% hint style="info" %}
For a complete list of organization operation please visit the [OpenAPI specification](https://github.com/AzBuilder/terrakube-server/tree/main/openapi-spec)
{% endhint %}