GitLab Runner controllers API

openapi: 3.2.0
info:
  title: GitLab REST Runner controllers 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: Runner controllers
  description: 'Use this API to manage the runner controllers that handle CI/CD job admission control, and the scopes

    assigned to them. Runner controllers connect to the job router and evaluate jobs against custom

    policies, deciding whether to admit or reject them.


    These endpoints require administrator access to the instance.


    > [!note]

    > The availability of these endpoints is controlled by a feature flag. They are available for

    > testing, but not ready for production use.'
  x-displayName: Runner controllers
  externalDocs:
    url: https://docs.gitlab.com/api/runner_controllers/
paths:
  /api/v4/runner_controllers/{id}/scopes:
    get:
      operationId: getApiV4RunnerControllersIdScopes
      summary: List all scopes for a runner controller
      description: Lists all scopes for a runner controller.
      tags:
      - Runner controllers
      responses:
        '200':
          description: OK
        '403':
          description: Forbidden
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      x-gitlab-lifecycle: experiment
      x-gitlab-tier: ultimate
  /api/v4/runner_controllers/{id}/scopes/instance:
    post:
      operationId: postApiV4RunnerControllersIdScopesInstance
      summary: Add instance scope
      description: Adds an instance scope to a runner controller. When added, the runner controller evaluates jobs for all runners in the GitLab instance. A runner controller can have only one instance scope. If an instance scope already exists, this operation returns an error.
      tags:
      - Runner controllers
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRunnerControllerInstanceLevelScoping'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '409':
          description: Conflict
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
    delete:
      operationId: deleteApiV4RunnerControllersIdScopesInstance
      summary: Remove instance scope
      description: Removes an instance scope from a runner controller.
      tags:
      - Runner controllers
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
  /api/v4/runner_controllers/{id}/scopes/runners/{runner_id}:
    post:
      operationId: postApiV4RunnerControllersIdScopesRunnersRunnerId
      summary: Add runner scope
      description: Adds a runner scope to a runner controller. When added, the runner controller evaluates jobs only for a specified runner. A runner controller with an instance scope cannot have runner scopes. Remove the instance scope before adding runner scopes.
      tags:
      - Runner controllers
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRunnerControllerRunnerLevelScoping'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '409':
          description: Conflict
        '422':
          description: Unprocessable Entity
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      - name: runner_id
        required: true
        description: ID of the runner.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
    delete:
      operationId: deleteApiV4RunnerControllersIdScopesRunnersRunnerId
      summary: Remove runner scope
      description: Removes a runner scope from a runner controller.
      tags:
      - Runner controllers
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      - name: runner_id
        required: true
        description: ID of the runner.
        schema:
          type: integer
        in: path
      x-gitlab-tier: ultimate
  /api/v4/runner_controllers:
    post:
      operationId: postApiV4RunnerControllers
      summary: Register a runner controller
      description: Registers a runner controller.
      tags:
      - Runner controllers
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRunnerController'
        '403':
          description: Forbidden
        '400':
          description: Bad Request
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4RunnerControllersRequest'
      x-gitlab-lifecycle: experiment
      x-gitlab-tier: ultimate
  /api/v4/runner_controllers/{id}:
    get:
      operationId: getApiV4RunnerControllersId
      summary: Retrieve a single runner controller
      description: Retrieves details of a specified runner controller.
      tags:
      - Runner controllers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRunnerControllerDetail'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      x-gitlab-lifecycle: experiment
      x-gitlab-tier: ultimate
    put:
      operationId: putApiV4RunnerControllersId
      summary: Update a runner controller
      description: Updates the details of an existing runner controller by its ID.
      tags:
      - Runner controllers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRunnerController'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4RunnerControllersIdRequest'
      x-gitlab-lifecycle: experiment
      x-gitlab-tier: ultimate
    delete:
      operationId: deleteApiV4RunnerControllersId
      summary: Delete a runner controller
      description: Deletes a specified runner controller. Administrators only.
      tags:
      - Runner controllers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesCiRunnerController'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the runner controller.
        schema:
          type: integer
        in: path
      x-gitlab-lifecycle: experiment
      x-gitlab-tier: ultimate
components:
  schemas:
    APIEntitiesCiRunnerControllerDetail:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        description:
          type: string
          example: Controller for managing runner
        state:
          type: string
          example: enabled
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        connected:
          type: boolean
          example: true
    APIEntitiesCiRunnerController:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        description:
          type: string
          example: Controller for managing runner
        state:
          type: string
          example: enabled
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    APIEntitiesCiRunnerControllerRunnerLevelScoping:
      type: object
      properties:
        runner_id:
          type: integer
          format: int64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    postApiV4RunnerControllersRequest:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: Description of the runner controller.
          example: Controller for managing runner
        state:
          type: string
          enum:
          - disabled
          - enabled
          - dry_run
          description: State of the runner controller.
          default: disabled
    putApiV4RunnerControllersIdRequest:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: Description of the runner controller.
          example: Controller for managing runner
        state:
          type:
          - string
          - 'null'
          enum:
          - disabled
          - enabled
          - dry_run
          - null
          description: State of the runner controller.
    APIEntitiesCiRunnerControllerInstanceLevelScoping:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  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