Agents API

Version history

Use the Agents API to work with the GitLab agent for Kubernetes.

List the agents for a project

Returns the list of agents registered for the project.

You must have at least the Developer role to use this endpoint.

GET /projects/:id/cluster_agents

Parameters:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user

Response:

The response is a list of agents with the following fields:

AttributeTypeDescription
idintegerID of the agent
namestringName of the agent
config_projectobjectObject representing the project the agent belongs to
config_project.idintegerID of the project
config_project.descriptionstringDescription of the project
config_project.namestringName of the project
config_project.name_with_namespacestringFull name with namespace of the project
config_project.pathstringPath to the project
config_project.path_with_namespacestringFull path with namespace to the project
config_project.created_atstringISO8601 datetime when the project was created
created_atstringISO8601 datetime when the agent was created
created_by_user_idintegerID of the user who created the agent

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents"

Example response:

[
  {
    "id": 1,
    "name": "agent-1",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  },
  {
    "id": 2,
    "name": "agent-2",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  }
]

Get details about an agent

Gets a single agent details.

You must have at least the Developer role to use this endpoint.

GET /projects/:id/cluster_agents/:agent_id

Parameters:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user
agent_idintegeryesID of the agent

Response:

The response is a single agent with the following fields:

AttributeTypeDescription
idintegerID of the agent
namestringName of the agent
config_projectobjectObject representing the project the agent belongs to
config_project.idintegerID of the project
config_project.descriptionstringDescription of the project
config_project.namestringName of the project
config_project.name_with_namespacestringFull name with namespace of the project
config_project.pathstringPath to the project
config_project.path_with_namespacestringFull path with namespace to the project
config_project.created_atstringISO8601 datetime when the project was created
created_atstringISO8601 datetime when the agent was created
created_by_user_idintegerID of the user who created the agent

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1"

Example response:

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

Register an agent with a project

Registers an agent to the project.

You must have at least the Maintainer role to use this endpoint.

POST /projects/:id/cluster_agents

Parameters:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user
namestringyesName for the agent

Response:

The response is the new agent with the following fields:

AttributeTypeDescription
idintegerID of the agent
namestringName of the agent
config_projectobjectObject representing the project the agent belongs to
config_project.idintegerID of the project
config_project.descriptionstringDescription of the project
config_project.namestringName of the project
config_project.name_with_namespacestringFull name with namespace of the project
config_project.pathstringPath to the project
config_project.path_with_namespacestringFull path with namespace to the project
config_project.created_atstringISO8601 datetime when the project was created
created_atstringISO8601 datetime when the agent was created
created_by_user_idintegerID of the user who created the agent

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents" \
    -H "Content-Type:application/json" \
    -X POST --data '{"name":"some-agent"}'

Example response:

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

Delete a registered agent

Deletes an existing agent registration.

You must have at least the Maintainer role to use this endpoint.

DELETE /projects/:id/cluster_agents/:agent_id

Parameters:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user
agent_idintegeryesID of the agent

Example request:

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1

List tokens for an agent

Introduced in GitLab 15.0.

Returns a list of tokens for an agent.

You must have at least the Developer role to use this endpoint.

GET /projects/:id/cluster_agents/:agent_id/tokens

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user.
agent_idinteger or stringyesID of the agent.

Response:

The response is a list of tokens with the following fields:

AttributeTypeDescription
idintegerID of the token.
namestringName of the token.
descriptionstring or nullDescription of the token.
agent_idintegerID of the agent the token belongs to.
statusstringThe status of the token. Valid values are active and revoked.
created_atstringISO8601 datetime when the token was created.
created_by_user_idstringUser ID of the user who created the token.

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens"

Example response:

[
  {
    "id": 1,
    "name": "abcd",
    "description": "Some token",
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  },
  {
    "id": 2,
    "name": "foobar",
    "description": null,
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  }
]
note
The last_used_at field for a token is only returned when getting a single agent token.

Get a single agent token

Introduced in GitLab 15.0.

Gets a single agent token.

You must have at least the Developer role to use this endpoint.

GET /projects/:id/cluster_agents/:agent_id/tokens/:token_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user.
agent_idintegeryesID of the agent.
token_idintegeryesID of the token.

Response:

The response is a single token with the following fields:

AttributeTypeDescription
idintegerID of the token.
namestringName of the token.
descriptionstring or nullDescription of the token.
agent_idintegerID of the agent the token belongs to.
statusstringThe status of the token. Valid values are active and revoked.
created_atstringISO8601 datetime when the token was created.
created_by_user_idstringUser ID of the user who created the token.
last_used_atstring or nullISO8601 datetime when the token was last used.

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/token/1"

Example response:

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null
}

Create an agent token

Introduced in GitLab 15.0.

Creates a new token for an agent.

You must have at least the Maintainer role to use this endpoint.

POST /projects/:id/cluster_agents/:agent_id/tokens

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user.
agent_idintegeryesID of the agent.
namestringyesName for the token.
descriptionstringnoDescription for the token.

Response:

The response is the new token with the following fields:

AttributeTypeDescription
idintegerID of the token.
namestringName of the token.
descriptionstring or nullDescription of the token.
agent_idintegerID of the agent the token belongs to.
statusstringThe status of the token. Valid values are active and revoked.
created_atstringISO8601 datetime when the token was created.
created_by_user_idstringUser ID of the user who created the token.
last_used_atstring or nullISO8601 datetime when the token was last used.
tokenstringThe secret token value.
note
The token is only returned in the response of the POST endpoint and cannot be retrieved afterwards.

Example request:

curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens" \
    -H "Content-Type:application/json" \
    -X POST --data '{"name":"some-token"}'

Example response:

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null,
  "token": "qeY8UVRisx9y3Loxo1scLxFuRxYcgeX3sxsdrpP_fR3Loq4xyg"
}

Revoke an agent token

Introduced in GitLab 15.0.

Revokes an agent token.

You must have at least the Maintainer role to use this endpoint.

DELETE /projects/:id/cluster_agents/:agent_id/tokens/:token_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the project maintained by the authenticated user.
agent_idintegeryesID of the agent.
token_idintegeryesID of the token.

Example request:

curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens/1