Packages API

This is the API documentation of GitLab Packages.

List packages

Within a project

Get a list of project packages. All package types are included in results. When accessed without authentication, only packages of public projects are returned. By default, packages with default and error status are returned. Use the status parameter to view other packages.

GET /projects/:id/packages
Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the project
order_by string no The field to use as order. One of created_at (default), name, version, or type.
sort string no The direction of the order, either asc (default) for ascending order or desc for descending order.
package_type string no Filter the returned packages by type. One of conan, maven, npm, pypi, composer, nuget, helm, terraform_module, or golang. (Introduced in GitLab 12.9)
package_name string no Filter the project packages with a fuzzy search by name. (Introduced in GitLab 12.9)
include_versionless boolean no When set to true, versionless packages are included in the response. (Introduced in GitLab 13.8)
status string no Filter the returned packages by status. One of default (default), hidden, processing, error, or pending_destruction. (Introduced in GitLab 13.9)
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages"

Example response:

[
  {
    "id": 1,
    "name": "com/mycompany/my-app",
    "version": "1.0-SNAPSHOT",
    "package_type": "maven",
    "created_at": "2019-11-27T03:37:38.711Z"
  },
  {
    "id": 2,
    "name": "@foo/bar",
    "version": "1.0.3",
    "package_type": "npm",
    "created_at": "2019-11-27T03:37:38.711Z"
  },
  {
    "id": 3,
    "name": "Hello/0.1@mycompany/stable",
    "conan_package_name": "Hello",
    "version": "0.1",
    "package_type": "conan",
    "_links": {
      "web_path": "/foo/bar/-/packages/3",
      "delete_api_path": "https://gitlab.example.com/api/v4/projects/1/packages/3"
    },
    "created_at": "2029-12-16T20:33:34.316Z",
    "tags": []
  }
]

By default, the GET request returns 20 results, because the API is paginated.

Although you can filter packages by status, working with packages that have a processing status can result in malformed data or broken packages.

Within a group

Introduced in GitLab 12.5.

Get a list of project packages at the group level. When accessed without authentication, only packages of public projects are returned. By default, packages with default and error status are returned. Use the status parameter to view other packages.

GET /groups/:id/packages
Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the group.
exclude_subgroups boolean false If the parameter is included as true, packages from projects from subgroups are not listed. Default is false.
order_by string no The field to use as order. One of created_at (default), name, version, type, or project_path.
sort string no The direction of the order, either asc (default) for ascending order or desc for descending order.
package_type string no Filter the returned packages by type. One of conan, maven, npm, pypi, composer, nuget, helm, or golang. (Introduced in GitLab 12.9)
package_name string no Filter the project packages with a fuzzy search by name. (Introduced in GitLab 13.0)
include_versionless boolean no When set to true, versionless packages are included in the response. (Introduced in GitLab 13.8)
status string no Filter the returned packages by status. One of default (default), hidden, processing, error, or pending_destruction. (Introduced in GitLab 13.9)
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/packages?exclude_subgroups=false"

Deprecation:

The pipeline attribute in the response is deprecated in favor of pipelines, which was introduced in GitLab 13.6. Both are available until 13.7. The build_info attribute in the response is deprecated in favor of pipeline, which was introduced in GitLab 12.10.

Example response:

[
  {
    "id": 1,
    "name": "com/mycompany/my-app",
    "version": "1.0-SNAPSHOT",
    "package_type": "maven",
    "_links": {
      "web_path": "/namespace1/project1/-/packages/1",
      "delete_api_path": "/namespace1/project1/-/packages/1"
    },
    "created_at": "2019-11-27T03:37:38.711Z",
    "pipelines": [
      {
        "id": 123,
        "status": "pending",
        "ref": "new-pipeline",
        "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
        "web_url": "https://example.com/foo/bar/pipelines/47",
        "created_at": "2016-08-11T11:28:34.085Z",
        "updated_at": "2016-08-11T11:32:35.169Z",
        "user": {
          "name": "Administrator",
          "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
        }
      }
    ]
  },
  {
    "id": 2,
    "name": "@foo/bar",
    "version": "1.0.3",
    "package_type": "npm",
    "_links": {
      "web_path": "/namespace1/project1/-/packages/1",
      "delete_api_path": "/namespace1/project1/-/packages/1"
    },
    "created_at": "2019-11-27T03:37:38.711Z",
    "pipelines": [
      {
        "id": 123,
        "status": "pending",
        "ref": "new-pipeline",
        "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
        "web_url": "https://example.com/foo/bar/pipelines/47",
        "created_at": "2016-08-11T11:28:34.085Z",
        "updated_at": "2016-08-11T11:32:35.169Z",
        "user": {
          "name": "Administrator",
          "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
        }
      }
    ]
  }
]

By default, the GET request returns 20 results, because the API is paginated.

The _links object contains the following properties:

  • web_path: The path which you can visit in GitLab and see the details of the package.
  • delete_api_path: The API path to delete the package. Only available if the request user has permission to do so.

Although you can filter packages by status, working with packages that have a processing status can result in malformed data or broken packages.

Get a project package

Get a single project package.

GET /projects/:id/packages/:package_id
Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the project.
package_id integer yes ID of a package.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id"

Deprecation:

The pipeline attribute in the response is deprecated in favor of pipelines, which was introduced in GitLab 13.6. Both are available until 13.7. The build_info attribute in the response is deprecated in favor of pipeline, which was introduced in GitLab 12.10.

Example response:

{
  <