GitLab API — cluster_agents

naftiko: 1.0.0-alpha2
info:
  label: GitLab API — cluster_agents
  description: 'GitLab API — cluster_agents. 8 operations. Lead operation: List the agents for a project. Self-contained Naftiko
    capability covering one Gitlab Ci business surface.'
  tags:
  - Gitlab Ci
  - cluster_agents
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    GITLAB_CI_API_KEY: GITLAB_CI_API_KEY
capability:
  consumes:
  - type: http
    namespace: gitlab-ci-cluster-agents
    baseUri: https://gitlab.com
    description: GitLab API — cluster_agents business capability. Self-contained, no shared references.
    resources:
    - name: api-v4-projects-id-cluster_agents
      path: /api/v4/projects/{id}/cluster_agents
      operations:
      - name: getapiv4projectsidclusteragents
        method: GET
        description: List the agents for a project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
      - name: postapiv4projectsidclusteragents
        method: POST
        description: Register an agent with a project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: postApiV4ProjectsIdClusterAgents
          in: body
          type: string
          required: true
    - name: api-v4-projects-id-cluster_agents-agent_id
      path: /api/v4/projects/{id}/cluster_agents/{agent_id}
      operations:
      - name: getapiv4projectsidclusteragentsagentid
        method: GET
        description: Get details about an agent
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: agent_id
          in: path
          type: integer
          description: The ID of an agent
          required: true
      - name: deleteapiv4projectsidclusteragentsagentid
        method: DELETE
        description: Delete a registered agent
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: agent_id
          in: path
          type: integer
          description: The ID of an agent
          required: true
    - name: api-v4-projects-id-cluster_agents-agent_id-tokens
      path: /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens
      operations:
      - name: getapiv4projectsidclusteragentsagentidtokens
        method: GET
        description: List tokens for an agent
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: agent_id
          in: path
          type: integer
          description: The ID of an agent
          required: true
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
      - name: postapiv4projectsidclusteragentsagentidtokens
        method: POST
        description: Create an agent token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: agent_id
          in: path
          type: integer
          description: The ID of an agent
          required: true
        - name: postApiV4ProjectsIdClusterAgentsAgentIdTokens
          in: body
          type: string
          required: true
    - name: api-v4-projects-id-cluster_agents-agent_id-tokens-token_id
      path: /api/v4/projects/{id}/cluster_agents/{agent_id}/tokens/{token_id}
      operations:
      - name: getapiv4projectsidclusteragentsagentidtokenstokenid
        method: GET
        description: Get a single agent token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: agent_id
          in: path
          type: integer
          description: The ID of an agent
          required: true
        - name: token_id
          in: path
          type: integer
          description: The ID of the agent token
          required: true
      - name: deleteapiv4projectsidclusteragentsagentidtokenstokenid
        method: DELETE
        description: Revoke an agent token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID or URL-encoded path of the project
          required: true
        - name: agent_id
          in: path
          type: integer
          description: The ID of an agent
          required: true
        - name: token_id
          in: path
          type: integer
          description: The ID of the agent token
          required: true
  exposes:
  - type: rest
    namespace: gitlab-ci-cluster-agents-rest
    port: 8080
    description: REST adapter for GitLab API — cluster_agents. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/api/v4/projects/{id}/cluster-agents
      name: api-v4-projects-id-cluster-agents
      description: REST surface for api-v4-projects-id-cluster_agents.
      operations:
      - method: GET
        name: getapiv4projectsidclusteragents
        description: List the agents for a project
        call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragents
        with:
          id: rest.id
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postapiv4projectsidclusteragents
        description: Register an agent with a project
        call: gitlab-ci-cluster-agents.postapiv4projectsidclusteragents
        with:
          id: rest.id
          postApiV4ProjectsIdClusterAgents: rest.postApiV4ProjectsIdClusterAgents
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/projects/{id}/cluster-agents/{agent-id}
      name: api-v4-projects-id-cluster-agents-agent-id
      description: REST surface for api-v4-projects-id-cluster_agents-agent_id.
      operations:
      - method: GET
        name: getapiv4projectsidclusteragentsagentid
        description: Get details about an agent
        call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragentsagentid
        with:
          id: rest.id
          agent_id: rest.agent_id
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteapiv4projectsidclusteragentsagentid
        description: Delete a registered agent
        call: gitlab-ci-cluster-agents.deleteapiv4projectsidclusteragentsagentid
        with:
          id: rest.id
          agent_id: rest.agent_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/projects/{id}/cluster-agents/{agent-id}/tokens
      name: api-v4-projects-id-cluster-agents-agent-id-tokens
      description: REST surface for api-v4-projects-id-cluster_agents-agent_id-tokens.
      operations:
      - method: GET
        name: getapiv4projectsidclusteragentsagentidtokens
        description: List tokens for an agent
        call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragentsagentidtokens
        with:
          id: rest.id
          agent_id: rest.agent_id
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postapiv4projectsidclusteragentsagentidtokens
        description: Create an agent token
        call: gitlab-ci-cluster-agents.postapiv4projectsidclusteragentsagentidtokens
        with:
          id: rest.id
          agent_id: rest.agent_id
          postApiV4ProjectsIdClusterAgentsAgentIdTokens: rest.postApiV4ProjectsIdClusterAgentsAgentIdTokens
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/projects/{id}/cluster-agents/{agent-id}/tokens/{token-id}
      name: api-v4-projects-id-cluster-agents-agent-id-tokens-token-id
      description: REST surface for api-v4-projects-id-cluster_agents-agent_id-tokens-token_id.
      operations:
      - method: GET
        name: getapiv4projectsidclusteragentsagentidtokenstokenid
        description: Get a single agent token
        call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragentsagentidtokenstokenid
        with:
          id: rest.id
          agent_id: rest.agent_id
          token_id: rest.token_id
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteapiv4projectsidclusteragentsagentidtokenstokenid
        description: Revoke an agent token
        call: gitlab-ci-cluster-agents.deleteapiv4projectsidclusteragentsagentidtokenstokenid
        with:
          id: rest.id
          agent_id: rest.agent_id
          token_id: rest.token_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: gitlab-ci-cluster-agents-mcp
    port: 9090
    transport: http
    description: MCP adapter for GitLab API — cluster_agents. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: list-agents-project
      description: List the agents for a project
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragents
      with:
        id: tools.id
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: register-agent-project
      description: Register an agent with a project
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-cluster-agents.postapiv4projectsidclusteragents
      with:
        id: tools.id
        postApiV4ProjectsIdClusterAgents: tools.postApiV4ProjectsIdClusterAgents
      outputParameters:
      - type: object
        mapping: $.
    - name: get-details-about-agent
      description: Get details about an agent
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragentsagentid
      with:
        id: tools.id
        agent_id: tools.agent_id
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-registered-agent
      description: Delete a registered agent
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gitlab-ci-cluster-agents.deleteapiv4projectsidclusteragentsagentid
      with:
        id: tools.id
        agent_id: tools.agent_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-tokens-agent
      description: List tokens for an agent
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragentsagentidtokens
      with:
        id: tools.id
        agent_id: tools.agent_id
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: create-agent-token
      description: Create an agent token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-cluster-agents.postapiv4projectsidclusteragentsagentidtokens
      with:
        id: tools.id
        agent_id: tools.agent_id
        postApiV4ProjectsIdClusterAgentsAgentIdTokens: tools.postApiV4ProjectsIdClusterAgentsAgentIdTokens
      outputParameters:
      - type: object
        mapping: $.
    - name: get-single-agent-token
      description: Get a single agent token
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-cluster-agents.getapiv4projectsidclusteragentsagentidtokenstokenid
      with:
        id: tools.id
        agent_id: tools.agent_id
        token_id: tools.token_id
      outputParameters:
      - type: object
        mapping: $.
    - name: revoke-agent-token
      description: Revoke an agent token
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gitlab-ci-cluster-agents.deleteapiv4projectsidclusteragentsagentidtokenstokenid
      with:
        id: tools.id
        agent_id: tools.agent_id
        token_id: tools.token_id
      outputParameters:
      - type: object
        mapping: $.