GitLab Cluster agents API

openapi: 3.2.0
info:
  title: GitLab REST Cluster agents API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Cluster agents
  description: Use this API to interact with the GitLab agent for Kubernetes.
  x-displayName: Cluster agents
  externalDocs:
    url: https://docs.gitlab.com/api/cluster_agents/
paths:
  /api/v4/projects/{id}/cluster_agents/{agent_id}/url_configurations:
    get:
      operationId: getApiV4ProjectsIdClusterAgentsAgentIdUrlConfigurations
      summary: List all agent URL configurations
      description: Lists all agent URL configurations for a specified agent. You must have the Developer, Maintainer, or Owner role to use this endpoint. This feature was introduced in GitLab 17.4.
      tags:
      - Cluster agents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgentUrlConfiguration'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
    post:
      operationId: postApiV4ProjectsIdClusterAgentsAgentIdUrlConfigurations
      summary: Create an agent URL configuration
      description: Creates an agent URL configuration. You must have the Maintainer or Owner role to use this endpoint. An agent can have only one URL configuration at the time. This feature was introduced in GitLab 17.4.
      tags:
      - Cluster agents
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgentUrlConfiguration'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdClusterAgentsAgentIdUrlConfigurationsRequest'
      x-gitlab-tier: ultimate
  /api/v4/projects/{id}/cluster_agents/{agent_id}/url_configurations/{url_configuration_id}:
    get:
      operationId: getApiV4ProjectsIdClusterAgentsAgentIdUrlConfigurationsUrlConfigurationId
      summary: Retrieve an agent URL configuration
      description: Retrieves an agent URL configuration. You must have the Developer, Maintainer, or Owner role to use this endpoint. This feature was introduced in GitLab 17.4.
      tags:
      - Cluster agents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgentUrlConfiguration'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      - name: url_configuration_id
        required: true
        description: ID of the agent URL configuration.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
    delete:
      operationId: deleteApiV4ProjectsIdClusterAgentsAgentIdUrlConfigurationsUrlConfigurationId
      summary: Delete an agent URL configuration
      description: Deletes an agent URL configuration. You must have the Maintainer or Owner role to use this endpoint. This feature was introduced in GitLab 17.4.
      tags:
      - Cluster agents
      responses:
        '204':
          description: Resource deleted
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      - name: url_configuration_id
        required: true
        description: ID of the agent URL configuration.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
  /api/v4/projects/{id}/cluster_agents:
    get:
      operationId: getApiV4ProjectsIdClusterAgents
      summary: List all agents
      description: Lists all agents registered for the project. You must have the Developer, Maintainer, or Owner role to use this endpoint.
      tags:
      - Cluster agents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgent'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
    post:
      operationId: postApiV4ProjectsIdClusterAgents
      summary: Create an agent
      description: Creates an agent for the project. You must have the Maintainer or Owner role to use this endpoint.
      tags:
      - Cluster agents
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgent'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdClusterAgentsRequest'
  /api/v4/projects/{id}/cluster_agents/{agent_id}:
    get:
      operationId: getApiV4ProjectsIdClusterAgentsAgentId
      summary: Retrieve details on an agent
      description: Retrieves details on a specified agent. You must have the Developer, Maintainer, or Owner role to use this endpoint.
      tags:
      - Cluster agents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgent'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
    delete:
      operationId: deleteApiV4ProjectsIdClusterAgentsAgentId
      summary: Delete an agent
      description: Deletes an existing agent registration. You must have the Maintainer or Owner role to use this endpoint.
      tags:
      - Cluster agents
      responses:
        '204':
          description: Resource deleted
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
  /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens:
    get:
      operationId: getApiV4ProjectsIdClusterAgentsAgentIdTokens
      summary: List all agent tokens
      description: Lists all active tokens for an agent. You must have the Developer, Maintainer, or Owner role to use this endpoint.
      tags:
      - Cluster agents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgentTokenBasic'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
    post:
      operationId: postApiV4ProjectsIdClusterAgentsAgentIdTokens
      summary: Create an agent token
      description: Creates a token for an agent. You must have the Maintainer or Owner role to use this endpoint. An agent can have only two active tokens at one time.
      tags:
      - Cluster agents
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgentTokenWithToken'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdClusterAgentsAgentIdTokensRequest'
  /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens/{token_id}:
    get:
      operationId: getApiV4ProjectsIdClusterAgentsAgentIdTokensTokenId
      summary: Retrieve an agent token
      description: Retrieves a specified agent token. You must have the Developer, Maintainer, or Owner role to use this endpoint. Returns a `404` if the agent token has been revoked.
      tags:
      - Cluster agents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesClustersAgentToken'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      - name: token_id
        required: true
        description: ID of the agent token.
        schema:
          type: integer
        in: path
    delete:
      operationId: deleteApiV4ProjectsIdClusterAgentsAgentIdTokensTokenId
      summary: Revoke an agent token
      description: Revokes an agent token. You must have the Maintainer or Owner role to use this endpoint.
      tags:
      - Cluster agents
      responses:
        '204':
          description: Resource deleted
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: agent_id
        required: true
        description: ID of the agent.
        schema:
          type: integer
        in: path
      - name: token_id
        required: true
        description: ID of the agent token.
        schema:
          type: integer
        in: path
components:
  schemas:
    APIEntitiesClustersAgentToken:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
        description:
          type: string
        agent_id:
          type: integer
          format: int64
          example: 1
        status:
          type: string
        created_at:
          type: string
          format: date-time
        created_by_user_id:
          type: integer
          format: int64
          example: 1
        last_used_at:
          type: string
          format: date-time
    postApiV4ProjectsIdClusterAgentsAgentIdUrlConfigurationsRequest:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          description: Agent URL for this URL configuration.
        client_cert:
          type:
          - string
          - 'null'
          description: Client certificate in PEM format, used for mTLS authentication. Must be provided with `client_key`.
        client_key:
          type:
          - string
          - 'null'
          description: Client key in PEM format, used for mTLS authentication. Must be provided with `client_cert`.
        ca_cert:
          type:
          - string
          - 'null'
          description: CA certificate in PEM format used to verify the agent endpoint.
        tls_host:
          type:
          - string
          - 'null'
          description: TLS host name to verify the server name in the agent endpoint.
      required:
      - url
    APIEntitiesClustersAgent:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
        config_project:
          $ref: '#/components/schemas/APIEntitiesProjectIdentity'
        created_at:
          type: string
          format: date-time
        created_by_user_id:
          type: integer
          format: int64
          example: 1
        is_receptive:
          type: boolean
    APIEntitiesClustersAgentUrlConfiguration:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        agent_id:
          type: integer
          format: int64
          example: 1
        url:
          type: string
        public_key:
          type: string
        client_cert:
          type: string
        ca_cert:
          type: string
        tls_host:
          type: string
    APIEntitiesClustersAgentTokenBasic:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
        description:
          type: string
        agent_id:
          type: integer
          format: int64
          example: 1
        status:
          type: string
        created_at:
          type: string
          format: date-time
        created_by_user_id:
          type: integer
          format: int64
          example: 1
    APIEntitiesProjectIdentity:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        description:
          type: string
          example: desc
        name:
          type: string
          example: project1
        name_with_namespace:
          type: string
          example: John Doe / project1
        path:
          type: string
          example: project1
        path_with_namespace:
          type: string
          example: namespace1/project1
        created_at:
          type: string
          format: date-time
          example: '2020-05-07T04:27:17.016Z'
    postApiV4ProjectsIdClusterAgentsAgentIdTokensRequest:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the token.
        description:
          type:
          - string
          - 'null'
          description: Description of the token.
      required:
      - name
    APIEntitiesClustersAgentTokenWithToken:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
        description:
          type: string
        agent_id:
          type: integer
          format: int64
          example: 1
        status:
          type: string
        created_at:
          type: string
          format: date-time
        created_by_user_id:
          type: integer
          format: int64
          example: 1
        last_used_at:
          type: string
          format: date-time
        token:
          type: string
    postApiV4ProjectsIdClusterAgentsRequest:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the agent.
      required:
      - name
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header