GitLab API — runners

naftiko: 1.0.0-alpha2
info:
  label: GitLab API — runners
  description: 'GitLab API — runners. 17 operations. Lead operation: List group''s runners. Self-contained Naftiko capability
    covering one Gitlab Ci business surface.'
  tags:
  - Gitlab Ci
  - runners
  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-runners
    baseUri: https://gitlab.com
    description: GitLab API — runners business capability. Self-contained, no shared references.
    resources:
    - name: api-v4-groups-id-runners
      path: /api/v4/groups/{id}/runners
      operations:
      - name: getapiv4groupsidrunners
        method: GET
        description: List group's runners
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of a group
          required: true
        - name: type
          in: query
          type: string
          description: The type of runners to return
        - name: paused
          in: query
          type: boolean
          description: Whether to include only runners that are accepting or ignoring new jobs
        - name: status
          in: query
          type: string
          description: The status of runners to return
        - name: tag_list
          in: query
          type: array
          description: A list of runner tags
        - name: version_prefix
          in: query
          type: string
          description: The version prefix of runners to return
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
    - name: api-v4-groups-id-runners-reset_registration_token
      path: /api/v4/groups/{id}/runners/reset_registration_token
      operations:
      - name: postapiv4groupsidrunnersresetregistrationtoken
        method: POST
        description: Reset the runner registration token for a group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of a group
          required: true
    - name: api-v4-projects-id-runners
      path: /api/v4/projects/{id}/runners
      operations:
      - name: getapiv4projectsidrunners
        method: GET
        description: List project's runners
        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 owned by the authenticated user
          required: true
        - name: scope
          in: query
          type: string
          description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
        - name: type
          in: query
          type: string
          description: The type of runners to return
        - name: paused
          in: query
          type: boolean
          description: Whether to include only runners that are accepting or ignoring new jobs
        - name: status
          in: query
          type: string
          description: The status of runners to return
        - name: tag_list
          in: query
          type: array
          description: A list of runner tags
        - name: version_prefix
          in: query
          type: string
          description: The version prefix of runners to return
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
      - name: postapiv4projectsidrunners
        method: POST
        description: Assign a runner to 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 owned by the authenticated user
          required: true
        - name: postApiV4ProjectsIdRunners
          in: body
          type: string
          required: true
    - name: api-v4-projects-id-runners-reset_registration_token
      path: /api/v4/projects/{id}/runners/reset_registration_token
      operations:
      - name: postapiv4projectsidrunnersresetregistrationtoken
        method: POST
        description: Reset the runner registration token for a project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of a project
          required: true
    - name: api-v4-projects-id-runners-runner_id
      path: /api/v4/projects/{id}/runners/{runner_id}
      operations:
      - name: deleteapiv4projectsidrunnersrunnerid
        method: DELETE
        description: Unassign a project runner from the 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 owned by the authenticated user
          required: true
        - name: runner_id
          in: path
          type: integer
          description: The ID of a runner
          required: true
    - name: api-v4-runners
      path: /api/v4/runners
      operations:
      - name: getapiv4runners
        method: GET
        description: List available runners
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: scope
          in: query
          type: string
          description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
        - name: type
          in: query
          type: string
          description: The type of runners to return
        - name: paused
          in: query
          type: boolean
          description: Whether to include only runners that are accepting or ignoring new jobs
        - name: status
          in: query
          type: string
          description: The status of runners to return
        - name: tag_list
          in: query
          type: array
          description: A list of runner tags
        - name: version_prefix
          in: query
          type: string
          description: The version prefix of runners to return
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
    - name: api-v4-runners-all
      path: /api/v4/runners/all
      operations:
      - name: getapiv4runnersall
        method: GET
        description: List all runners
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: scope
          in: query
          type: string
          description: 'Deprecated: Use `type` or `status` instead. The scope of runners to return'
        - name: type
          in: query
          type: string
          description: The type of runners to return
        - name: paused
          in: query
          type: boolean
          description: Whether to include only runners that are accepting or ignoring new jobs
        - name: status
          in: query
          type: string
          description: The status of runners to return
        - name: tag_list
          in: query
          type: array
          description: A list of runner tags
        - name: version_prefix
          in: query
          type: string
          description: The version prefix of runners to return
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
    - name: api-v4-runners-reset_registration_token
      path: /api/v4/runners/reset_registration_token
      operations:
      - name: postapiv4runnersresetregistrationtoken
        method: POST
        description: Reset instance's runner registration token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-v4-runners-id
      path: /api/v4/runners/{id}
      operations:
      - name: getapiv4runnersid
        method: GET
        description: Get runner's details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          required: true
        - name: include_projects
          in: query
          type: boolean
          description: Include projects in the response. Set to false to improve performance for runners with many projects.
      - name: putapiv4runnersid
        method: PUT
        description: Update details of a runner
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          required: true
        - name: putApiV4RunnersId
          in: body
          type: string
          required: true
      - name: deleteapiv4runnersid
        method: DELETE
        description: Delete a runner
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          required: true
    - name: api-v4-runners-id-jobs
      path: /api/v4/runners/{id}/jobs
      operations:
      - name: getapiv4runnersidjobs
        method: GET
        description: List runner's jobs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          required: true
        - name: system_id
          in: query
          type: string
          description: System ID associated with the runner manager
        - name: status
          in: query
          type: string
          description: Status of the job
        - name: order_by
          in: query
          type: string
          description: Order by `id`
        - name: sort
          in: query
          type: string
          description: Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id`
        - name: cursor
          in: query
          type: string
          description: Cursor for obtaining the next set of records
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
    - name: api-v4-runners-id-managers
      path: /api/v4/runners/{id}/managers
      operations:
      - name: getapiv4runnersidmanagers
        method: GET
        description: Get a list of all runner's managers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          required: true
    - name: api-v4-runners-id-projects
      path: /api/v4/runners/{id}/projects
      operations:
      - name: getapiv4runnersidprojects
        method: GET
        description: List runner's projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          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: api-v4-runners-id-reset_authentication_token
      path: /api/v4/runners/{id}/reset_authentication_token
      operations:
      - name: postapiv4runnersidresetauthenticationtoken
        method: POST
        description: Reset runner's authentication token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of the runner
          required: true
    - name: api-v4-user-runners
      path: /api/v4/user/runners
      operations:
      - name: postapiv4userrunners
        method: POST
        description: Create a runner owned by currently authenticated user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: postApiV4UserRunners
          in: body
          type: string
          required: true
  exposes:
  - type: rest
    namespace: gitlab-ci-runners-rest
    port: 8080
    description: REST adapter for GitLab API — runners. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/api/v4/groups/{id}/runners
      name: api-v4-groups-id-runners
      description: REST surface for api-v4-groups-id-runners.
      operations:
      - method: GET
        name: getapiv4groupsidrunners
        description: List group's runners
        call: gitlab-ci-runners.getapiv4groupsidrunners
        with:
          id: rest.id
          type: rest.type
          paused: rest.paused
          status: rest.status
          tag_list: rest.tag_list
          version_prefix: rest.version_prefix
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/groups/{id}/runners/reset-registration-token
      name: api-v4-groups-id-runners-reset-registration-token
      description: REST surface for api-v4-groups-id-runners-reset_registration_token.
      operations:
      - method: POST
        name: postapiv4groupsidrunnersresetregistrationtoken
        description: Reset the runner registration token for a group
        call: gitlab-ci-runners.postapiv4groupsidrunnersresetregistrationtoken
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/projects/{id}/runners
      name: api-v4-projects-id-runners
      description: REST surface for api-v4-projects-id-runners.
      operations:
      - method: GET
        name: getapiv4projectsidrunners
        description: List project's runners
        call: gitlab-ci-runners.getapiv4projectsidrunners
        with:
          id: rest.id
          scope: rest.scope
          type: rest.type
          paused: rest.paused
          status: rest.status
          tag_list: rest.tag_list
          version_prefix: rest.version_prefix
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postapiv4projectsidrunners
        description: Assign a runner to project
        call: gitlab-ci-runners.postapiv4projectsidrunners
        with:
          id: rest.id
          postApiV4ProjectsIdRunners: rest.postApiV4ProjectsIdRunners
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/projects/{id}/runners/reset-registration-token
      name: api-v4-projects-id-runners-reset-registration-token
      description: REST surface for api-v4-projects-id-runners-reset_registration_token.
      operations:
      - method: POST
        name: postapiv4projectsidrunnersresetregistrationtoken
        description: Reset the runner registration token for a project
        call: gitlab-ci-runners.postapiv4projectsidrunnersresetregistrationtoken
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/projects/{id}/runners/{runner-id}
      name: api-v4-projects-id-runners-runner-id
      description: REST surface for api-v4-projects-id-runners-runner_id.
      operations:
      - method: DELETE
        name: deleteapiv4projectsidrunnersrunnerid
        description: Unassign a project runner from the project
        call: gitlab-ci-runners.deleteapiv4projectsidrunnersrunnerid
        with:
          id: rest.id
          runner_id: rest.runner_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners
      name: api-v4-runners
      description: REST surface for api-v4-runners.
      operations:
      - method: GET
        name: getapiv4runners
        description: List available runners
        call: gitlab-ci-runners.getapiv4runners
        with:
          scope: rest.scope
          type: rest.type
          paused: rest.paused
          status: rest.status
          tag_list: rest.tag_list
          version_prefix: rest.version_prefix
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/all
      name: api-v4-runners-all
      description: REST surface for api-v4-runners-all.
      operations:
      - method: GET
        name: getapiv4runnersall
        description: List all runners
        call: gitlab-ci-runners.getapiv4runnersall
        with:
          scope: rest.scope
          type: rest.type
          paused: rest.paused
          status: rest.status
          tag_list: rest.tag_list
          version_prefix: rest.version_prefix
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/reset-registration-token
      name: api-v4-runners-reset-registration-token
      description: REST surface for api-v4-runners-reset_registration_token.
      operations:
      - method: POST
        name: postapiv4runnersresetregistrationtoken
        description: Reset instance's runner registration token
        call: gitlab-ci-runners.postapiv4runnersresetregistrationtoken
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/{id}
      name: api-v4-runners-id
      description: REST surface for api-v4-runners-id.
      operations:
      - method: GET
        name: getapiv4runnersid
        description: Get runner's details
        call: gitlab-ci-runners.getapiv4runnersid
        with:
          id: rest.id
          include_projects: rest.include_projects
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: putapiv4runnersid
        description: Update details of a runner
        call: gitlab-ci-runners.putapiv4runnersid
        with:
          id: rest.id
          putApiV4RunnersId: rest.putApiV4RunnersId
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteapiv4runnersid
        description: Delete a runner
        call: gitlab-ci-runners.deleteapiv4runnersid
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/{id}/jobs
      name: api-v4-runners-id-jobs
      description: REST surface for api-v4-runners-id-jobs.
      operations:
      - method: GET
        name: getapiv4runnersidjobs
        description: List runner's jobs
        call: gitlab-ci-runners.getapiv4runnersidjobs
        with:
          id: rest.id
          system_id: rest.system_id
          status: rest.status
          order_by: rest.order_by
          sort: rest.sort
          cursor: rest.cursor
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/{id}/managers
      name: api-v4-runners-id-managers
      description: REST surface for api-v4-runners-id-managers.
      operations:
      - method: GET
        name: getapiv4runnersidmanagers
        description: Get a list of all runner's managers
        call: gitlab-ci-runners.getapiv4runnersidmanagers
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/{id}/projects
      name: api-v4-runners-id-projects
      description: REST surface for api-v4-runners-id-projects.
      operations:
      - method: GET
        name: getapiv4runnersidprojects
        description: List runner's projects
        call: gitlab-ci-runners.getapiv4runnersidprojects
        with:
          id: rest.id
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/{id}/reset-authentication-token
      name: api-v4-runners-id-reset-authentication-token
      description: REST surface for api-v4-runners-id-reset_authentication_token.
      operations:
      - method: POST
        name: postapiv4runnersidresetauthenticationtoken
        description: Reset runner's authentication token
        call: gitlab-ci-runners.postapiv4runnersidresetauthenticationtoken
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/user/runners
      name: api-v4-user-runners
      description: REST surface for api-v4-user-runners.
      operations:
      - method: POST
        name: postapiv4userrunners
        description: Create a runner owned by currently authenticated user
        call: gitlab-ci-runners.postapiv4userrunners
        with:
          postApiV4UserRunners: rest.postApiV4UserRunners
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: gitlab-ci-runners-mcp
    port: 9090
    transport: http
    description: MCP adapter for GitLab API — runners. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: list-group-s-runners
      description: List group's runners
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4groupsidrunners
      with:
        id: tools.id
        type: tools.type
        paused: tools.paused
        status: tools.status
        tag_list: tools.tag_list
        version_prefix: tools.version_prefix
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: reset-runner-registration-token-group
      description: Reset the runner registration token for a group
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-runners.postapiv4groupsidrunnersresetregistrationtoken
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-project-s-runners
      description: List project's runners
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4projectsidrunners
      with:
        id: tools.id
        scope: tools.scope
        type: tools.type
        paused: tools.paused
        status: tools.status
        tag_list: tools.tag_list
        version_prefix: tools.version_prefix
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: assign-runner-project
      description: Assign a runner to project
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-runners.postapiv4projectsidrunners
      with:
        id: tools.id
        postApiV4ProjectsIdRunners: tools.postApiV4ProjectsIdRunners
      outputParameters:
      - type: object
        mapping: $.
    - name: reset-runner-registration-token-project
      description: Reset the runner registration token for a project
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-runners.postapiv4projectsidrunnersresetregistrationtoken
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: unassign-project-runner-project
      description: Unassign a project runner from the project
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gitlab-ci-runners.deleteapiv4projectsidrunnersrunnerid
      with:
        id: tools.id
        runner_id: tools.runner_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-available-runners
      description: List available runners
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4runners
      with:
        scope: tools.scope
        type: tools.type
        paused: tools.paused
        status: tools.status
        tag_list: tools.tag_list
        version_prefix: tools.version_prefix
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: list-all-runners
      description: List all runners
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4runnersall
      with:
        scope: tools.scope
        type: tools.type
        paused: tools.paused
        status: tools.status
        tag_list: tools.tag_list
        version_prefix: tools.version_prefix
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: reset-instance-s-runner-registration-token
      description: Reset instance's runner registration token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-runners.postapiv4runnersresetregistrationtoken
      outputParameters:
      - type: object
        mapping: $.
    - name: get-runner-s-details
      description: Get runner's details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4runnersid
      with:
        id: tools.id
        include_projects: tools.include_projects
      outputParameters:
      - type: object
        mapping: $.
    - name: update-details-runner
      description: Update details of a runner
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.putapiv4runnersid
      with:
        id: tools.id
        putApiV4RunnersId: tools.putApiV4RunnersId
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-runner
      description: Delete a runner
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gitlab-ci-runners.deleteapiv4runnersid
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-runner-s-jobs
      description: List runner's jobs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4runnersidjobs
      with:
        id: tools.id
        system_id: tools.system_id
        status: tools.status
        order_by: tools.order_by
        sort: tools.sort
        cursor: tools.cursor
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-list-all-runner-s-managers
      description: Get a list of all runner's managers
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4runnersidmanagers
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-runner-s-projects
      description: List runner's projects
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-runners.getapiv4runnersidprojects
      with:
        id: tools.id
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: reset-runner-s-authentication-token
      description: Reset runner's authentication token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-runners.postapiv4runnersidresetauthenticationtoken
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: create-runner-owned-currently-authenticated
      description: Create a runner owned by currently authenticated user
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-runners.postapiv4userrunners
      with:
        postApiV4UserRunners: tools.postApiV4UserRunners
      outputParameters:
      - type: object
        mapping: $.