GitLab Dependency management API

openapi: 3.2.0
info:
  title: GitLab REST Dependency management 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: Dependency management
  description: 'Use this API to retrieve a project''s dependencies and to export

    dependency lists for a project,

    group, or pipeline.


    Every call to these endpoints requires authentication. To retrieve a project''s dependencies, the user

    must be authorized to read the repository. To see vulnerabilities in a response, the user must also be

    authorized to read the project security dashboard.

    To create or download a dependency list export, the user must have the `read_dependency` permission,

    and exports can be downloaded only by the user who created them.'
  x-displayName: Dependency management
  externalDocs:
    url: https://docs.gitlab.com/api/dependency_list_export/
paths:
  /api/v4/projects/{id}/dependency_list_exports:
    post:
      operationId: postApiV4ProjectsIdDependencyListExports
      summary: Create a dependency list export
      description: Creates a CycloneDX JSON export for all the project dependencies detected in a pipeline. If an authenticated user does not have the read_dependency permission, this request returns a `403 Forbidden` status code.
      tags:
      - Dependency management
      responses:
        '201':
          description: Created
        '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
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdDependencyListExportsRequest'
      x-gitlab-tier: ultimate
  /api/v4/groups/{id}/dependency_list_exports:
    post:
      operationId: postApiV4GroupsIdDependencyListExports
      summary: Create a dependency list export
      description: Creates a CycloneDX JSON export for all the project dependencies detected in a pipeline. If an authenticated user does not have the read_dependency permission, this request returns a `403 Forbidden` status code.
      tags:
      - Dependency management
      responses:
        '201':
          description: Created
        '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
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GroupsIdDependencyListExportsRequest'
      x-gitlab-tier: ultimate
  /api/v4/pipelines/{id}/dependency_list_exports:
    post:
      operationId: postApiV4PipelinesIdDependencyListExports
      summary: Create a dependency list export
      description: Creates a CycloneDX JSON export for all the project dependencies detected in a pipeline. If an authenticated user does not have the read_dependency permission, this request returns a `403 Forbidden` status code.
      tags:
      - Dependency management
      responses:
        '201':
          description: Created
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the pipeline.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4PipelinesIdDependencyListExportsRequest'
      x-gitlab-tier: ultimate
  /api/v4/dependency_list_exports/{export_id}:
    get:
      operationId: getApiV4DependencyListExportsExportId
      summary: Retrieve a single dependency list export
      description: Retrieves a dependency list export.
      tags:
      - Dependency management
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: export_id
        required: true
        description: ID of the dependency list export.
        schema:
          oneOf:
          - type: integer
          - type: string
        in: path
      x-gitlab-tier: ultimate
  /api/v4/dependency_list_exports/{export_id}/download:
    get:
      operationId: getApiV4DependencyListExportsExportIdDownload
      summary: Download dependency list export
      description: Downloads a dependency list export.
      tags:
      - Dependency management
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
      parameters:
      - name: export_id
        required: true
        description: ID of the dependency list export.
        schema:
          oneOf:
          - type: integer
          - type: string
        in: path
      x-gitlab-tier: ultimate
  /api/v4/occurrences/vulnerabilities:
    get:
      operationId: getApiV4OccurrencesVulnerabilities
      summary: Get vulnerabilities
      description: Returns vulnerabilities related to an occurrence.
      tags:
      - Dependency management
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID of the occurrence.
        schema:
          type:
          - string
          - 'null'
        in: query
      x-gitlab-tier: ultimate
  /api/v4/projects/{id}/dependencies:
    get:
      operationId: getApiV4ProjectsIdDependencies
      summary: List all project dependencies
      description: Lists all dependencies for a specified project. This operation partially mirrors the dependency list feature, which is available only for languages and package managers supported by Gemnasium. Responses are paginated and return 20 results by default.
      tags:
      - Dependency management
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesDependency'
        '401':
          description: Unauthorized
        '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: package_manager
        required: false
        description: Filter results by the specified package manager.
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
            enum:
            - bundler
            - yarn
            - npm
            - pnpm
            - bun
            - maven
            - composer
            - pip
            - conan
            - go
            - nuget
            - sbt
            - gradle
            - pipenv
            - poetry
            - setuptools
            - apk
            - conda
            - pub
            - cargo
        in: query
        example:
        - maven
        - yarn
        style: form
        explode: false
      - 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
      x-gitlab-tier: ultimate
components:
  schemas:
    APIEntitiesDependency:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
        package_manager:
          type: string
        dependency_file_path:
          type: string
        vulnerabilities:
          $ref: '#/components/schemas/DependencyEntityVulnerabilityEntity'
        licenses:
          $ref: '#/components/schemas/DependencyEntityLicenseEntity'
        malware:
          type: boolean
          description: 'Malware status: true if the package version matches a malware advisory, false otherwise. Omitted when the user cannot read security resources.'
    DependencyEntityVulnerabilityEntity:
      type: object
      properties:
        severity:
          type: string
        id:
          type: string
        name:
          type: string
        url:
          type: string
    postApiV4GroupsIdDependencyListExportsRequest:
      type: object
      properties:
        send_email:
          type: boolean
          description: If `true`, sends an email notification to the requesting user when the export completes.
          default: false
        export_type:
          type: string
          enum:
          - json_array
          - csv
          description: Format of the export.
          default: json_array
    postApiV4ProjectsIdDependencyListExportsRequest:
      type: object
      properties:
        send_email:
          type: boolean
          description: If `true`, sends an email notification to the requesting user when the export completes.
          default: false
        export_type:
          type: string
          enum:
          - dependency_list
          - csv
          - cyclonedx_1_6_json
          description: Format of the export.
          default: dependency_list
    DependencyEntityLicenseEntity:
      type: object
      properties:
        spdx_identifier:
          type: string
        name:
          type: string
        url:
          type: string
    postApiV4PipelinesIdDependencyListExportsRequest:
      type: object
      properties:
        send_email:
          type: boolean
          description: If `true`, sends an email notification to the requesting user when the export completes.
          default: false
        export_type:
          type: string
          enum:
          - sbom
          description: Format of the export.
          default: sbom
  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