# Agent

This endpoint is used to create, update, search or delete job agents for a Terrakube organization.

{% hint style="info" %}
You need to be part of the administrator group to work with this endpoint
{% endhint %}

### Entity fields:

| Path                        | Type   | Description                                                                                                           |
| --------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| data.type                   | string | Should be "agent"                                                                                                     |
| data.attributes.name        | string | Agent pool name                                                                                                       |
| data.attributes.description | string | agent pool description                                                                                                |
| data.attributes.url         | string | URL where the executor component will be available. Example: <http://terrakube-executor-service.self-hosted-executor> |

### Example:

```
POST {{terrakubeApi}}/api/v1/organization/{{organizationId}}/agent
{
  "data": {
    "type": "agent",
    "attributes": {
      "name": "sample-agent",
      "url": "http://localhost:8090",
      "description": "This is a sample agent"
    }
  }
}
```

### Supported Operations:

####

## GET /organization/{organizationId}/agent

> Returns the relationship agent

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"agent"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/agent":{"get":{"tags":["agent"],"description":"Returns the relationship agent","parameters":[{"name":"sort","in":"query","description":"Sorts the collection on the selected attributes.  A prefix of '-' sorts descending","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["description","-description","name","-name","url","-url","id","-id"]}}},{"name":"fields[agent]","in":"query","description":"Selects the set of agent fields that should be returned in the result.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["description","name","url","organization"]}}},{"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":["organization"]}}},{"name":"filter[agent]","in":"query","description":"Filters the collection of agent using a 'disjoint' RSQL expression","schema":{"type":"string"}},{"name":"page[number]","in":"query","description":"Number of pages to return.  Can be used with page[size]","schema":{"type":"integer","format":"int32"}},{"name":"page[size]","in":"query","description":"Number of elements per page.  Can be used with page[number]","schema":{"type":"integer","format":"int32"}},{"name":"page[offset]","in":"query","description":"Offset from 0 to start paginating.  Can be used with page[limit]","schema":{"type":"integer","format":"int32"}},{"name":"page[limit]","in":"query","description":"Maximum number of items to return.  Can be used with page[offset]","schema":{"type":"integer","format":"int32"}},{"name":"page[totals]","in":"query","description":"For requesting total pages/records be included in the response page meta data","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/agent"}},"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":{"agent":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (user is a superuser)\nDelete Permissions : (user is a superuser)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"description":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"name":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"url":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

## POST /organization/{organizationId}/agent

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

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"agent"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/agent":{"post":{"tags":["agent"],"description":"Creates an item of type agent and adds it to agent","requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/agent"},"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/agent"},"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":{"agent":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (user is a superuser)\nDelete Permissions : (user is a superuser)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"description":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"name":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"url":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

## GET /organization/{organizationId}/agent/{agentId}

> Returns an instance of type agent

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"agent"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/agent/{agentId}":{"get":{"tags":["agent"],"description":"Returns an instance of type agent","parameters":[{"name":"fields[agent]","in":"query","description":"Selects the set of agent fields that should be returned in the result.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["description","name","url","organization"]}}},{"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":["organization"]}}}],"responses":{"200":{"description":"Successful response","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/agent"},"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":{"agent":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (user is a superuser)\nDelete Permissions : (user is a superuser)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"description":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"name":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"url":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```

## DELETE /organization/{organizationId}/agent/{agentId}

> Deletes an instance of type agent

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

## PATCH /organization/{organizationId}/agent/{agentId}

> Modifies an instance of type agent

```json
{"openapi":"3.0.1","info":{"title":"Elide Service","version":"0.0.1"},"tags":[{"name":"agent"}],"servers":[{"url":"/api/v1"}],"paths":{"/organization/{organizationId}/agent/{agentId}":{"patch":{"tags":["agent"],"description":"Modifies an instance of type agent","requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/agent"},"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":{"agent":{"type":"object","properties":{"type":{"type":"string","description":"Create Permissions : (user is a superuser)\nDelete Permissions : (user is a superuser)"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"description":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"name":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false},"url":{"type":"string","description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}},"relationships":{"type":"object","properties":{"organization":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"id":{"type":"string"}},"description":"Update Permissions : (user is a superuser)","readOnly":false,"writeOnly":false}}}}}}}}}}}
```