GitLab GitLab Duo API

openapi: 3.2.0
info:
  title: GitLab REST GitLab Duo 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: GitLab Duo
  description: 'Use this API to generate responses for GitLab Duo Chat

    and other GitLab Duo features.


    On GitLab.com, these endpoints are for internal use only. On GitLab Self-Managed, you can enable them

    with a feature flag named `access_rest_chat`.

    You must be a GitLab team member to use these endpoints.'
  x-displayName: GitLab Duo
  externalDocs:
    url: https://docs.gitlab.com/api/chat/
paths:
  /api/v4/duo_code_review/evaluations:
    post:
      operationId: postApiV4DuoCodeReviewEvaluations
      summary: Evaluate code review
      description: Evaluates code changes using GitLab Duo code review
      tags:
      - GitLab Duo
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4DuoCodeReviewEvaluationsRequest'
  /api/v4/chat/completions:
    post:
      operationId: postApiV4ChatCompletions
      summary: Generate a Chat response
      description: Generates a response for a GitLab Duo Chat question.
      tags:
      - GitLab Duo
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ChatCompletionsRequest'
  /api/v4/ai/third_party_agents/direct_access:
    post:
      operationId: postApiV4AiThirdPartyAgentsDirectAccess
      summary: Get connection details for third party agents
      description: Returns connection details including tokens for accessing third-party agents.
      tags:
      - GitLab Duo
      responses:
        '201':
          description: Created
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '503':
          description: Service unavailable
        '400':
          description: Bad Request
      x-gitlab-lifecycle: experiment
  /api/v4/ai/llm/git_command:
    post:
      operationId: postApiV4AiLlmGitCommand
      summary: Generate Git commands from natural text
      description: Generates Git commands from natural language input
      tags:
      - GitLab Duo
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4AiLlmGitCommandRequest'
components:
  schemas:
    postApiV4ChatCompletionsRequest:
      type: object
      properties:
        content:
          type:
          - string
          - 'null'
          description: Question sent to Chat.
          maxLength: 1000
        resource_type:
          type:
          - string
          - 'null'
          enum:
          - issue
          - epic
          - group
          - project
          - merge_request
          - commit
          - build
          - work_item
          - null
          description: Type of resource sent with the chat question.
          maxLength: 100
        resource_id:
          oneOf:
          - type:
            - string
            - 'null'
          - type:
            - integer
            - 'null'
          description: ID of the resource. Can be a numeric ID or a commit SHA.
        referer_url:
          type:
          - string
          - 'null'
          description: Referer URL.
          maxLength: 1000
        client_subscription_id:
          type:
          - string
          - 'null'
          description: Client subscription ID.
          maxLength: 500
        with_clean_history:
          type:
          - boolean
          - 'null'
          description: If `true`, resets history before and after the request.
        project_id:
          type:
          - integer
          - 'null'
          description: ID of the project. Required when `resource_type` is `commit`.
        current_file:
          type:
          - object
          - 'null'
          description: Object that contains information about the current file.
          properties:
            file_name:
              type:
              - string
              - 'null'
              description: Name of the current file.
              maxLength: 1000
            content_above_cursor:
              type:
              - string
              - 'null'
              description: Content above cursor.
              maxLength: 400000
            content_below_cursor:
              type:
              - string
              - 'null'
              description: Content below cursor.
              maxLength: 400000
            selected_text:
              type:
              - string
              - 'null'
              description: Content currently selected by the user.
              maxLength: 400000
        additional_context:
          type:
          - array
          - 'null'
          description: Additional context to pass to the chat request. See [Context attributes](https://docs.gitlab.com/api/chat/#context-attributes) for the parameters this attribute accepts.
          items:
            type: object
            properties:
              category:
                type: string
                enum:
                - file
                - snippet
                - merge_request
                - issue
                - dependency
                - local_git
                - terminal
                - user_rule
                - repository
                - directory
                - agent_user_environment
                - attachments
                description: Category of the additional context.
                minLength: 1
              id:
                type:
                - string
                - 'null'
                description: ID of the additional context.
                maxLength: 255
              content:
                type:
                - string
                - 'null'
                description: Content of the additional context.
                maxLength: 1000
              metadata:
                type:
                - object
                - 'null'
                description: Metadata of the additional context.
            required:
            - category
            - id
            - content
      required:
      - content
    postApiV4AiLlmGitCommandRequest:
      type: object
      properties:
        prompt:
          type:
          - string
          - 'null'
          description: Prompt used to generate the Git commands.
      required:
      - prompt
    postApiV4DuoCodeReviewEvaluationsRequest:
      type: object
      properties:
        diffs:
          type:
          - string
          - 'null'
          description: Raw diffs to review.
        mr_title:
          type:
          - string
          - 'null'
          description: Title of the merge request.
        mr_description:
          type:
          - string
          - 'null'
          description: Description of the merge request.
        files_content:
          type:
          - object
          - 'null'
          description: Full file contents, where keys are file paths and values are the file contents.
      required:
      - diffs
      - mr_title
      - mr_description
      - files_content
  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