GitLab Active context API

openapi: 3.2.0
info:
  title: GitLab REST Active context 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: Active context
  description: 'Use this API to administer the ActiveContext indexing infrastructure, including its connections,

    collection options, the namespaces enabled for code indexing, and the dead queue.


    These endpoints require administrator access to the instance.'
  x-displayName: Active context
paths:
  /api/v4/admin/active_context/connections:
    get:
      operationId: getApiV4AdminActiveContextConnections
      summary: Get all ActiveContext connections
      description: Returns every ActiveContext connection configured for this instance.
      tags:
      - Active context
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiActiveContextConnection'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
  /api/v4/admin/active_context/connections/activate:
    put:
      operationId: putApiV4AdminActiveContextConnectionsActivate
      summary: Activate an ActiveContext connection
      description: Activates the specified connection and deactivates the previously active connection, if any.
      tags:
      - Active context
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiActiveContextConnection'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4AdminActiveContextConnectionsActivateRequest'
  /api/v4/admin/active_context/connections/deactivate:
    put:
      operationId: putApiV4AdminActiveContextConnectionsDeactivate
      summary: Deactivate an ActiveContext connection
      description: Deactivates the specified connection. This asynchronously drops indexed data for the connection and deletes the connection record.
      tags:
      - Active context
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiActiveContextConnection'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '400':
          description: Bad Request
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4AdminActiveContextConnectionsDeactivateRequest'
  /api/v4/admin/active_context/collections/{id}:
    put:
      operationId: putApiV4AdminActiveContextCollectionsId
      summary: Update collection options
      description: Updates the queue shard count and/or queue shard limit for the specified collection.
      tags:
      - Active context
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiActiveContextCollection'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '422':
          description: 422 Unprocessable entity
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: Name or ID of the collection.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4AdminActiveContextCollectionsIdRequest'
  /api/v4/admin/active_context/dead_queue:
    delete:
      operationId: deleteApiV4AdminActiveContextDeadQueue
      summary: Clear the ActiveContext dead queue
      description: Removes all items from the dead queue and returns the number of items cleared.
      tags:
      - Active context
      responses:
        '200':
          description: OK
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
  /api/v4/admin/active_context/dead_queue/replay:
    post:
      operationId: postApiV4AdminActiveContextDeadQueueReplay
      summary: Replay items from the dead queue into another queue
      description: Enqueues a background task that replays dead queue items into the specified target queue.
      tags:
      - Active context
      responses:
        '201':
          description: Created
        '400':
          description: 400 Bad Request
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4AdminActiveContextDeadQueueReplayRequest'
  /api/v4/admin/active_context/code/enabled_namespaces:
    put:
      operationId: putApiV4AdminActiveContextCodeEnabledNamespaces
      summary: Update enabled namespace state
      description: Transitions the indexing state of an enabled namespace to pending or ready.
      tags:
      - Active context
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiActiveContextCodeEnabledNamespace'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4AdminActiveContextCodeEnabledNamespacesRequest'
components:
  schemas:
    APIEntitiesAiActiveContextCollection:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: gitlab_active_context_code
        connection_id:
          type: integer
          example: 1234
        options:
          type: object
          example:
            queue_shard_count: 24
            queue_shard_limit: 1000
        created_at:
          type: string
          example: '2023-01-01T00:00:00.000Z'
        updated_at:
          type: string
          example: '2023-01-01T00:00:00.000Z'
    APIEntitiesAiActiveContextCodeEnabledNamespace:
      type: object
      properties:
        id:
          type: integer
          example: 1
        namespace_id:
          type: integer
          example: 9970
        connection_id:
          type: integer
          example: 1234
        state:
          type: string
          example: pending
        created_at:
          type: string
          example: '2023-01-01T00:00:00.000Z'
        updated_at:
          type: string
          example: '2023-01-01T00:00:00.000Z'
    putApiV4AdminActiveContextCollectionsIdRequest:
      type: object
      properties:
        queue_shard_count:
          type:
          - integer
          - 'null'
          description: Number of queue shards. At least one of `queue_shard_count`, `queue_shard_limit` must be provided.
        queue_shard_limit:
          type:
          - integer
          - 'null'
          description: Maximum number of queued items processed from each queue shard at a time. At least one of `queue_shard_count`, `queue_shard_limit` must be provided.
        connection_id:
          type:
          - integer
          - 'null'
          description: ID of the connection. If omitted, defaults to the active connection.
    postApiV4AdminActiveContextDeadQueueReplayRequest:
      type: object
      properties:
        queue:
          type:
          - string
          - 'null'
          description: Name of the target queue, for example `retry_queue`, `second_retry_queue`, `code`, or `code_backfill`.
      required:
      - queue
    putApiV4AdminActiveContextCodeEnabledNamespacesRequest:
      type: object
      properties:
        namespace_id:
          oneOf:
          - type:
            - string
            - 'null'
          - type:
            - integer
            - 'null'
          description: ID or path of the namespace.
        state:
          type: string
          enum:
          - pending
          - ready
          description: Indexing state to transition the enabled namespace to.
          minLength: 1
        connection_id:
          type:
          - integer
          - 'null'
          description: ID of the connection. If omitted, defaults to the active connection.
      required:
      - namespace_id
      - state
    putApiV4AdminActiveContextConnectionsActivateRequest:
      type: object
      properties:
        connection_id:
          type:
          - integer
          - 'null'
          description: ID of the connection.
      required:
      - connection_id
    putApiV4AdminActiveContextConnectionsDeactivateRequest:
      type: object
      properties:
        connection_id:
          type:
          - integer
          - 'null'
          description: ID of the connection. If omitted, defaults to the active connection.
    APIEntitiesAiActiveContextConnection:
      type: object
      properties:
        id:
          type: integer
          example: 1234
        name:
          type: string
          example: elastic
        adapter_class:
          type: string
          example: ActiveContext::Databases::Elasticsearch::Adapter
        prefix:
          type: string
          example: gitlab
        active:
          type: boolean
          example: true
        created_at:
          type: string
          example: '2023-01-01T00:00:00.000Z'
        updated_at:
          type: string
          example: '2023-01-01T00:00:00.000Z'
  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