GitLab Search API

openapi: 3.2.0
info:
  title: GitLab REST Search 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: Search
  description: 'Use this API to search across GitLab in an instance, a group,

    or a project, and to retrieve information about

    advanced search migrations.


    Every call to this API requires authentication. Retrieving advanced search migrations requires

    administrator access.


    Some scopes are available for basic search.

    When advanced search or

    exact code search is

    enabled, additional scopes become available. To use basic search instead, see

    specify a search type.


    These endpoints support offset-based pagination.'
  x-displayName: Search
  externalDocs:
    url: https://docs.gitlab.com/api/search/
paths:
  /api/v4/projects/{id}/(-/)search/semantic:
    get:
      operationId: getApiV4ProjectsIdDashSearchSemantic
      summary: Search project code using natural language
      description: 'Introduced in GitLab 18.11.


        Searches indexed project code using semantic (meaning-based) similarity rather than

        keyword matching. Use this when you do not know the exact symbol or file name, or

        to discover how a behavior is implemented across the codebase.


        Primary use cases:

        - When you do not know the exact symbol or file path

        - To see how a behavior or feature is implemented across the codebase

        - To discover related implementations (clients, jobs, workers)


        How to use:

        - Provide a concise, specific query with concrete keywords

        - Use directory_path to narrow scope (e.g. "app/services/")

        - Prefer precise intent over broad terms


        Results are grouped by file. Each file includes merged line ranges with content

        and a relevance score (0.0-1.0). The response includes an overall confidence

        level (high/medium/low/unknown) based on score distribution. Results are

        filtered by Duo context exclusion settings.


        Requires semantic code search to be enabled and indexed for the project namespace.'
      tags:
      - Search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiSemanticCodeResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found - project not found or semantic code search unavailable
        '422':
          description: Unprocessable entity - project has no embeddings
        '429':
          description: Too many requests
        '503':
          description: Service unavailable - search backend timed out
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: q
        required: true
        description: Natural language search query, for example `authentication middleware` or `rate limiting logic`.
        schema:
          type:
          - string
          - 'null'
          maxLength: 1000
        in: query
      - name: directory_path
        required: false
        description: Restrict search to files under this directory path, for example `app/services/`. Must be a relative path with no leading slash and no `..` segments.
        schema:
          type:
          - string
          - 'null'
          maxLength: 100
        in: query
      - name: knn
        required: false
        description: 'Number of nearest neighbours to retrieve internally (default: 64). Higher values improve recall at the cost of latency.'
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 64
        in: query
      - name: limit
        required: false
        description: 'Maximum number of results to return (default: 20).'
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        in: query
      x-gitlab-lifecycle: beta
  /api/v4/admin/search/migrations:
    get:
      operationId: getApiV4AdminSearchMigrations
      summary: List all advanced search migrations
      description: Lists all advanced search migrations for the GitLab instance.
      tags:
      - Search
      responses:
        '200':
          description: OK
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
      x-gitlab-tier: premium
  /api/v4/admin/search/migrations/{migration_id}:
    get:
      operationId: getApiV4AdminSearchMigrationsMigrationId
      summary: Retrieve an advanced search migration
      description: Retrieves a specified advanced search migration by migration version or name.
      tags:
      - Search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesSearchMigration'
        '401':
          description: 401 Unauthorized
        '403':
          description: 403 Forbidden
        '404':
          description: 404 Not found
        '400':
          description: Bad Request
      parameters:
      - name: migration_id
        required: true
        description: Version or name of the search migration.
        schema:
          oneOf:
          - type: integer
          - type: string
        in: path
      x-gitlab-tier: premium
  /api/v4/search:
    get:
      operationId: getApiV4Search
      summary: Search an instance
      description: Searches for a term across the entire GitLab instance. The response depends on the requested scope.
      tags:
      - Search
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
      parameters:
      - name: search
        required: true
        description: Search query.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: scope
        required: true
        description: Scope of the search.
        schema:
          type: string
          enum:
          - wiki_blobs
          - blobs
          - commits
          - notes
          - projects
          - groups
          - issues
          - work_items
          - merge_requests
          - milestones
          - snippet_titles
          - users
          minLength: 1
        in: query
      - name: state
        required: false
        description: Filter results by state. Applies only to the `issues`, `work_items`, and `merge_requests` scopes.
        schema:
          type:
          - string
          - 'null'
          enum:
          - all
          - opened
          - closed
          - merged
          - null
        in: query
      - name: confidential
        required: false
        description: If `true`, returns only confidential results. If `false`, returns only non-confidential results. Applies only to the `issues` and `work_items` scopes.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: type
        required: false
        description: 'Filter work items by type. Only applies to work_items scope. Available types: issue, task, epic, incident, test_case, requirement, objective, key_result, ticket.'
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
        in: query
        style: form
        explode: false
      - name: include_archived
        required: false
        description: If `true`, includes archived projects in the search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/493281) in GitLab 18.7.
        schema:
          type: boolean
          default: false
        in: query
      - name: fields
        required: false
        description: Fields to search. Supports only `issues` and `merge_requests` scopes. Premium and Ultimate only.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
            enum:
            - title
        in: query
        style: form
        explode: false
      - name: exclude_forks
        required: false
        description: If `true`, excludes forked projects from the search. If omitted, forks are excluded. Available for exact code search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/493281) in GitLab 18.7.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: num_context_lines
        required: false
        description: Number of context lines to include around each match in the results. Available for advanced and exact code search only. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/583217) in GitLab 18.11.
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 20
        in: query
      - name: regex
        required: false
        description: If `true`, uses regular expressions to search for code. If omitted, regular expressions are used. Available for exact code search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/521686) in GitLab 18.9.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: source_branch
        required: false
        description: Filter merge requests by source branch. Available with advanced search and the merge_requests scope.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: target_branch
        required: false
        description: Filter merge requests by target branch. Available with advanced search and the merge_requests scope.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: author_username
        required: false
        description: Filter by author username. A username that matches no user is ignored. Available with advanced search and the issues, merge_requests and work_items scopes.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: label_name
        required: false
        description: Filter by label name. A result must carry every name that resolves to an existing label; names that match no label are ignored. Maximum 30 names. Available with advanced search and the issues, merge_requests and work_items scopes.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
        in: query
        style: form
        explode: false
      - name: not
        required: false
        description: Filter out results matching the parameters supplied. Supplying a filter together with its negation matches either condition, which widens the result set.
        schema:
          type:
          - object
          - 'null'
        in: query
      - name: not[source_branch]
        required: false
        description: Exclude merge requests with this source branch
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: not[target_branch]
        required: false
        description: Exclude merge requests with this target branch
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: not[author_username]
        required: false
        description: Exclude results authored by this username
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
  /api/v4/groups/{id}/(-/)search:
    get:
      operationId: getApiV4GroupsIdDashSearch
      summary: Search on GitLab within a group
      description: This feature was introduced in GitLab 10.5.
      tags:
      - Search
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: search
        required: true
        description: Search query.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: scope
        required: true
        description: Scope of the search.
        schema:
          type: string
          enum:
          - wiki_blobs
          - blobs
          - commits
          - notes
          - projects
          - groups
          - issues
          - work_items
          - merge_requests
          - milestones
          - users
          minLength: 1
        in: query
      - name: state
        required: false
        description: Filter results by state. Applies only to the `issues`, `work_items`, and `merge_requests` scopes.
        schema:
          type:
          - string
          - 'null'
          enum:
          - all
          - opened
          - closed
          - merged
          - null
        in: query
      - name: confidential
        required: false
        description: If `true`, returns only confidential results. If `false`, returns only non-confidential results. Applies only to the `issues` and `work_items` scopes.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: type
        required: false
        description: 'Filter work items by type. Only applies to work_items scope. Available types: issue, task, epic, incident, test_case, requirement, objective, key_result, ticket.'
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
        in: query
        style: form
        explode: false
      - name: include_archived
        required: false
        description: If `true`, includes archived projects in the search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/493281) in GitLab 18.7.
        schema:
          type: boolean
          default: false
        in: query
      - name: fields
        required: false
        description: Fields to search. Supports only `issues` and `merge_requests` scopes. Premium and Ultimate only.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
            enum:
            - title
        in: query
        style: form
        explode: false
      - name: exclude_forks
        required: false
        description: If `true`, excludes forked projects from the search. If omitted, forks are excluded. Available for exact code search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/493281) in GitLab 18.7.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: num_context_lines
        required: false
        description: Number of context lines to include around each match in the results. Available for advanced and exact code search only. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/583217) in GitLab 18.11.
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 20
        in: query
      - name: regex
        required: false
        description: If `true`, uses regular expressions to search for code. If omitted, regular expressions are used. Available for exact code search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/521686) in GitLab 18.9.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: source_branch
        required: false
        description: Filter merge requests by source branch. Available with advanced search and the merge_requests scope.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: target_branch
        required: false
        description: Filter merge requests by target branch. Available with advanced search and the merge_requests scope.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: author_username
        required: false
        description: Filter by author username. A username that matches no user is ignored. Available with advanced search and the issues, merge_requests and work_items scopes.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: label_name
        required: false
        description: Filter by label name. A result must carry every name that resolves to an existing label; names that match no label are ignored. Maximum 30 names. Available with advanced search and the issues, merge_requests and work_items scopes.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
        in: query
        style: form
        explode: false
      - name: not
        required: false
        description: Filter out results matching the parameters supplied. Supplying a filter together with its negation matches either condition, which widens the result set.
        schema:
          type:
          - object
          - 'null'
        in: query
      - name: not[source_branch]
        required: false
        description: Exclude merge requests with this source branch
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: not[target_branch]
        required: false
        description: Exclude merge requests with this target branch
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: not[author_username]
        required: false
        description: Exclude results authored by this username
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
  /api/v4/projects/{id}/(-/)search:
    get:
      operationId: getApiV4ProjectsIdDashSearch
      summary: Search a project
      description: Searches for content in a specified project.
      tags:
      - Search
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      - name: search
        required: true
        description: Search query.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: scope
        required: true
        description: Scope of the search.
        schema:
          type: string
          enum:
          - issues
          - work_items
          - merge_requests
          - milestones
          - notes
          - wiki_blobs
          - commits
          - blobs
          - users
          minLength: 1
        in: query
      - name: ref
        required: false
        description: Name of the repository branch or tag. If omitted, uses the default branch.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: state
        required: false
        description: Filter results by state. Applies only to the `issues`, `work_items`, and `merge_requests` scopes.
        schema:
          type:
          - string
          - 'null'
          enum:
          - all
          - opened
          - closed
          - merged
          - null
        in: query
      - name: confidential
        required: false
        description: If `true`, returns only confidential results. If `false`, returns only non-confidential results. Applies only to the `issues` and `work_items` scopes.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: type
        required: false
        description: 'Filter work items by type. Only applies to work_items scope. Available types: issue, task, epic, incident, test_case, requirement, objective, key_result, ticket.'
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
        in: query
        style: form
        explode: false
      - name: fields
        required: false
        description: Fields to search. Supports only `issues` and `merge_requests` scopes. Premium and Ultimate only.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
            enum:
            - title
        in: query
        style: form
        explode: false
      - name: num_context_lines
        required: false
        description: Number of context lines to include around each match in the results. Available for advanced and exact code search only. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/583217) in GitLab 18.11.
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 20
        in: query
      - name: regex
        required: false
        description: If `true`, uses regular expressions to search for code. If omitted, regular expressions are used. Available for exact code search. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/521686) in GitLab 18.9.
        schema:
          type:
          - boolean
          - 'null'
        in: query
      - name: source_branch
        required: false
        description: Filter merge requests by source branch. Available with advanced search and the merge_requests scope.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: target_branch
        required: false
        description: Filter merge requests by target branch. Available with advanced search and the merge_requests scope.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: author_username
        required: false
        description: Filter by author username. A username that matches no user is ignored. Available with advanced search and the issues, merge_requests and work_items scopes.
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: label_name
        required: false
        description: Filter by label name. A result must carry every name that resolves to an existing label; names that match no label are ignored. Maximum 30 names. Available with advanced search and the issues, merge_requests and work_items scopes.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
        in: query
        style: form
        explode: false
      - name: not
        required: false
        description: Filter out results matching the parameters supplied. Supplying a filter together with its negation matches either condition, which widens the result set.
        schema:
          type:
          - object
          - 'null'
        in: query
      - name: not[source_branch]
        required: false
        description: Exclude merge requests with this source branch
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: not[target_branch]
        required: false
        description: Exclude merge requests with this target branch
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: not[author_username]
        required: false
        description: Exclude results authored by this username
        schema:
          type:
          - string
          - 'null'
        in: query
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
components:
  schemas:
    APIEntitiesAiSemanticCodeGroupedResult:
      type: object
      properties:
        path:
          type: string
          example: app/models/user.rb
        blob_id:
          type: string
          example: abc123def456
        file_url:
          type: string
          example: https://gitlab.com/group/project/-/blob/main/user.rb
        score:
          type: number
          example: 0.92
        snippet_ranges:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesAiSemanticCodeSnippetRange'
    APIEntitiesAiSemanticCodeResponse:
      type: object
      properties:
        confidence:
          type: string
          example: high
        results:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesAiSemanticCodeGroupedResult'
    APIEntitiesAiSemanticCodeSnippetRange:
      type: object
      properties:
        start_line:
          type: integer
          example: 42
        end_line:
          type: integer
          example: 44
        content:
          type: string
          example: "def authenticate\n  ...\nend"
        score:
          type: number
          example: 0.85
    APIEntitiesSearchMigration:
      type: object
      properties:
        version:
          type: integer
          example: 20230427555555
        name:
          type: string
          example: BackfillHiddenOnMergeRequests
        started_at:
          type: string
          format: date-time
          example: '2023-05-14T12:30:50.355Z'
        completed_at:
          type: string
          format: date-time
          example: '2023-05-16T12:30:50.355Z'
        completed:
          type: boolean
          example: true
        obsolete:
          type: boolean
          example: false
        migration_state:
          type: object
          example:
            task_id: task_id
  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