Dependency list export API

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Every call to this endpoint requires authentication.

Create a dependency list export

History

Create a new CycloneDX JSON export for all the project dependencies detected in a pipeline.

If an authenticated user does not have permission to read_dependency, this request returns a 403 Forbidden status code.

SBOM exports can be only accessed by the export’s author.

Copy to clipboard 
POST /projects/:id/dependency_list_exports
POST /groups/:id/dependency_list_exports
POST /pipelines/:id/dependency_list_exports
AttributeTypeRequiredDescription
idintegeryesThe ID of the project, group, or pipeline that the authenticated user has access to.
export_typestringyesFormat of the export. See export types for a list of accepted values.
send_emailbooleannoWhen set to true, sends an email notification to the user who requested the export when the export completes.
Shell Copy to clipboard 
curl --request POST --header "PRIVATE-TOKEN: <private_token>" "https://gitlab.example.com/api/v4/pipelines/1/dependency_list_exports" --data "export_type=sbom"

The created dependency list export is automatically deleted after 1 hour.

Example response:

JSON Copy to clipboard 
{
  "id": 2,
  "status": "running",
  "has_finished": false,
  "export_type": "sbom",
  "send_email": false,
  "self": "http://gitlab.example.com/api/v4/dependency_list_exports/2",
  "download": "http://gitlab.example.com/api/v4/dependency_list_exports/2/download"
}

Export types

Exports can be requested in different file formats. Some formats are only available for certain objects.

Export TypeDescriptionAvailable for
dependency_listA standard JSON object that lists the dependencies as key-value pairs.Projects
sbomA CycloneDX 1.4 bill of materialsPipelines
json_arrayA flat JSON array that contains component objects.Groups
csvA comma-separated values (CSV) document.Projects, Groups

Get single dependency list export

Get a single dependency list export.

Copy to clipboard 
GET /dependency_list_exports/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of the dependency list export.
Shell Copy to clipboard 
curl --header "PRIVATE-TOKEN: <private_token>" "https://gitlab.example.com/api/v4/dependency_list_exports/2"

The status code is 202 Accepted when the dependency list export is being generated, and 200 OK when it’s ready.

Example response:

JSON Copy to clipboard 
{
  "id": 4,
  "has_finished": true,
  "self": "http://gitlab.example.com/api/v4/dependency_list_exports/4",
  "download": "http://gitlab.example.com/api/v4/dependency_list_exports/4/download"
}

Download dependency list export

Download a single dependency list export.

Copy to clipboard 
GET /dependency_list_exports/:id/download
AttributeTypeRequiredDescription
idintegeryesThe ID of the dependency list export.
Shell Copy to clipboard 
curl --header "PRIVATE-TOKEN: <private_token>" "https://gitlab.example.com/api/v4/dependency_list_exports/2/download"

The response is 404 Not Found if the dependency list export is not finished yet or was not found.

Example response:

JSON Copy to clipboard 
{
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "serialNumber": "urn:uuid:aec33827-20ae-40d0-ae83-18ee846364d2",
  "version": 1,
  "metadata": {
    "tools": [
      {
        "vendor": "Gitlab",
        "name": "Gemnasium",
        "version": "2.34.0"
      }
    ],
    "authors": [
      {
        "name": "Gitlab",
        "email": "support@gitlab.com"
      }
    ],
    "properties": [
      {
        "name": "gitlab:dependency_scanning:input_file",
        "value": "package-lock.json"
      }
    ]
  },
  "components": [
    {
      "name": "com.fasterxml.jackson.core/jackson-core",
      "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.9.2",
      "version": "2.9.2",
      "type": "library",
      "licenses": [
        {
          "license": {
            "id": "MIT",
            "url": "https://spdx.org/licenses/MIT.html"
          }
        },
        {
          "license": {
            "id": "BSD-3-Clause",
            "url": "https://spdx.org/licenses/BSD-3-Clause.html"
          }
        }
      ]
    }
  ]
}