GitLab GLQL API

openapi: 3.2.0
info:
  title: GitLab REST GLQL 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: GLQL
  description: 'Use this API to execute GitLab Query Language (GLQL) queries

    programmatically. GLQL provides a simplified query language to search and filter

    GitLab resources such as issues, merge requests,

    and epics across projects and groups.


    The group or project must allow access to its data. For private groups and projects, you must

    authenticate with a personal access token

    that has the appropriate permissions.'
  x-displayName: GLQL
  externalDocs:
    url: https://docs.gitlab.com/api/glql/
paths:
  /api/v4/glql:
    post:
      operationId: postApiV4Glql
      summary: Execute a GLQL query
      description: Executes a GLQL query to search and filter GitLab resources.
      tags:
      - GLQL
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGlqlResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal server error
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GlqlRequest'
  /api/v4/glql/schema:
    get:
      operationId: getApiV4GlqlSchema
      summary: Retrieve the GLQL schema
      description: 'Retrieves the GLQL schema: data sources with their filter, display and sort fields, the operator, value kind and reference type vocabularies, the available functions, and the display types a query can be rendered as.'
      tags:
      - GLQL
      responses:
        '200':
          description: OK
        '500':
          description: Internal server error
components:
  schemas:
    APIEntitiesGlqlData:
      type: object
      properties:
        count:
          type: integer
          description: Number of found items
          example: 42
        nodes:
          type: array
          description: The list of found items
          example: []
          items:
            type: array
        pageInfo:
          description: Pagination information
          $ref: '#/components/schemas/APIEntitiesGlqlPageInfo'
    postApiV4GlqlRequest:
      type: object
      properties:
        glql_yaml:
          type:
          - string
          - 'null'
          description: GLQL query that may include YAML configuration. Maximum size is 10,000 bytes. See [query formats](https://docs.gitlab.com/api/glql/#query-formats) for details.
        after:
          type:
          - string
          - 'null'
          description: Cursor for pagination. Use the `data.pageInfo.endCursor` value from a previous query to fetch the next page of results.
      required:
      - glql_yaml
    APIEntitiesGlqlResult:
      type: object
      properties:
        data:
          description: Query result data containing count, nodes, and pagination info
          $ref: '#/components/schemas/APIEntitiesGlqlData'
        error:
          type: string
          description: Error message if query failed
        fields:
          type: array
          description: Field definitions for the query results
          items:
            $ref: '#/components/schemas/APIEntitiesGlqlField'
        success:
          type: boolean
          example: true
    APIEntitiesGlqlField:
      type: object
      properties:
        key:
          type: string
          description: Unique field key
          example: title
        label:
          type: string
          description: Human-readable field label
          example: Title
        name:
          type: string
          description: Underlying name of field, often the same as `key`, but it may be different if one type of field has multiple possible keys. Example `created` and `createdAt`
          example: title
        field:
          type: string
          description: Base field name. For aliased parameterised fields this is the underlying field (for example, `durationQuantile`), while `key` is the alias (for example, `p50`). For standard fields, same as `key`
          example: title
        type:
          type: string
          description: Field classification. Either `dimension` or `metric` for analytics mode fields, absent for standard fields
          example: dimension
        parameters:
          type: object
          description: Resolved parameter metadata for parameterised fields, absent when the field has no parameters
          example:
            granularity: weekly
    APIEntitiesGlqlPageInfo:
      type: object
      properties:
        endCursor:
          type: string
          description: Cursor for the last item
          example: eyJpZCI6IjE3In0
        hasNextPage:
          type: boolean
          description: Whether there are more items
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there are previous items
          example: false
        startCursor:
          type: string
          description: Cursor for the first item
          example: eyJpZCI6IjE3In0
  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