Packages API

12 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.

Endpoints

GET /api/v1/packages/recent

Recent packages

The most recently published package versions across the repositories the caller can read, newest first. A version with several files (architectures, classifiers, distributions) appears once. Proxy cache entries are not publications and are left out. The server records no publisher, so created_by_name is never set; mine=true narrows the list to the repositories the caller can write to.

Parameters

Name	In	Type	Required	Description
mine	query	boolean	no	true keeps the repositories the caller has write permission on
limit	query	integer	no	Maximum entries (default 10, at most 50). Minimum: 1. Maximum: 50.

Responses

Status	Description	Body
200	Recent package versions	application/json: object
400	Invalid mine	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
packages	array of RecentPackage	yes	-

GET /api/v1/repositories/{name}/artifacts/search

Search artifacts

Search artifacts by properties

Security: bearerAuth or cookieAuth or .

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
key	query	string	yes	-
value	query	string	yes	-

Responses

Status	Description	Body
200	Search results	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Repository or addressed resource not found	application/json: Error

GET /api/v1/repositories/{name}/artifacts/{artifact_id}/properties

List artifact properties

List properties for a specific artifact

Security: bearerAuth or cookieAuth or .

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
artifact_id	path	string (uuid)	yes	-

Responses

Status	Description	Body
200	Artifact properties	application/json: map of string
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Repository or addressed resource not found	application/json: Error

PUT /api/v1/repositories/{name}/artifacts/{artifact_id}/properties

Set artifact properties

Replace all properties for a specific artifact

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
artifact_id	path	string (uuid)	yes	-

Request body (required)

application/json: map of string

Responses

Status	Description	Body
200	Properties updated	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Repository or addressed resource not found	application/json: Error

PATCH /api/v1/repositories/{name}/artifacts/{artifact_id}/properties

Update artifact properties

Patch properties for a specific artifact

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
artifact_id	path	string (uuid)	yes	-

Request body (required)

application/json: map of string

Responses

Status	Description	Body
200	Properties updated	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Repository or addressed resource not found	application/json: Error

DELETE /api/v1/repositories/{name}/artifacts/{artifact_id}/properties/{key}

Delete artifact property

Delete a specific property from an artifact

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
artifact_id	path	string (uuid)	yes	-
key	path	string	yes	-

Responses

Status	Description	Body
204	Property deleted	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Property not found	-

GET /api/v1/repositories/{name}/packages

List packages in repository

List all packages in a specific repository

Security: bearerAuth or cookieAuth or .

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
page	query	integer	no	Minimum: 1.
limit	query	integer	no	Minimum: 1. Maximum: 100.
q	query	string	no	Only list rows whose listed name or version contains this text (case-insensitive, at most 200 characters). Maximum length: 200.
sort	query	string	no	Row order: newest first (created, the default) or by name and version (name). One of: created, name.
format	query	string	no	Only list packages of this format
package_name	query	string	no	Only list rows whose listed package name equals this value exactly (all versions of one package)
group	query	string	no	package returns one entry per package (format and name) instead of one per file: its latest version, version count, latest size and the scan state of the latest version. total then counts packages. The q, format and package_name filters apply to the rows before they are grouped. One of: package.
flagged	query	boolean	no	With group=package, true keeps the packages whose latest version has a critical or high vulnerability, a secret finding or a quarantined scan result. Rejected without group=package.

Responses

Status	Description	Body
200	List of packages: one entry per file (PackageFile), or one per package (PackageGroup) with group=package	application/json: object
400	Invalid sort, group, flagged or q	-
403	Forbidden	application/json: Error
404	Repository not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
limit	integer	no	-
packages	array of any	no	-
page	integer	no	-
total	integer	no	-

GET /api/v1/repositories/{name}/packages/{id}

Get a package version

One package version, by the row id of the package listing: the metadata its format stores, its declared dependencies and the files of the version. Requires read access to the repository. Dependencies are returned for npm (dependencies, devDependencies, peerDependencies, optionalDependencies), cargo, nuget (kind is the target framework), rubygems, conda, deb (Depends, Pre-Depends), rpm (requires) and go (go.mod require directives); the other formats do not store them server-side and return an empty list. Metadata holds only what the format's table stores: for pypi, helm, maven, docker and conan there are no declared dependencies, and docker layers or the image config are not part of the response.

Security: bearerAuth or cookieAuth or .

Parameters

Name	In	Type	Required	Description
name	path	string	yes	Repository name
id	path	string (uuid)	yes	Row id from the package listing

Responses

Status	Description	Body
200	The package version	application/json: PackageDetail
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	No read access to the repository	-
404	Repository or package not found (a package of another repository is not found either)	-

POST /api/v1/repositories/{name}/uploads

Start a presigned upload

Hosted raw repositories on any storage backend with a staging area: S3-compatible and GCS (presigned URLs), Azure (SAS URLs), and the filesystem and OCI registry backends (short-lived HMAC-signed URLs served by this server, which need baseUrl to be set). Returns a short-lived presigned PUT URL to a staging object; upload the bytes directly to it, then call the complete endpoint. Files above 5 GiB (up to 5 TiB) must set multipart: the response then carries the part plan instead of a URL, and each part URL comes from the parts endpoint. Requires write permission on the repository and on the path. The response carries a bearer credential and is sent with Cache-Control: no-store. A user may have at most storage.presignMaxPendingUploads uploads outstanding (not completed, not expired).

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: PresignedUploadRequest

Responses

Status	Description	Body
201	Upload target	application/json: PresignedUpload
400	Invalid path, size, part size or sha256 (code invalid_size also when a size above 5 GiB lacks multipart, or is too large for a single upload on Azure), or the repository is not a hosted raw repository	application/json: Error
401	Authentication required	-
403	Write permission denied	-
404	Repository not found	-
429	Too many outstanding uploads for this user (retry after the Retry-After header)	application/json: Error
501	The storage backend does not support presigned uploads	application/json: Error

POST /api/v1/repositories/{name}/uploads/{id}/abort

Abort a presigned upload

Discards an upload that will not be completed: the staging object, the parts uploaded so far and the upload record. Only the creator of the upload or an administrator may abort it. Abandoned uploads are also swept automatically after they expire.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	The upload was discarded	-
400	Invalid request	application/json: Error
401	Authentication required	-
403	Write permission denied, or the caller is neither the creator of the upload nor an administrator	-
404	Repository or upload not found (or expired and swept)	-
409	Code upload_completed: the upload is already completed. Code upload_in_progress: a complete is running (retry after the Retry-After header)	application/json: Error
501	The storage backend does not support presigned uploads	application/json: Error

POST /api/v1/repositories/{name}/uploads/{id}/complete

Complete a presigned upload

Verifies that the staged object has the declared size and sha256, moves it to its content-addressed key, records the artifact (overwriting an existing path, like a raw PUT) and deletes the staging object. Only the creator of the upload or an administrator may complete it. The server reads the object back (up to 5 TiB) in a detached job (30 minutes plus about one second per 20 MiB, at most 6 hours) that survives a client disconnect; the read and the move are conditional on the object version seen at verification, so an object re-uploaded in between is refused. The call is idempotent: the first success returns 201, a retry returns 200 with the same body, and a retry while a verification is running returns 409 upload_in_progress. On a size or sha256 mismatch, or when the object changed during verification, the staging object and the upload are discarded and nothing is recorded. The repository's storage quota is enforced (507 quota_exceeded: the upload stays pending, nothing is recorded, and completing again after freeing space works); license and secret scanning are not applied, as for a raw PUT.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-
force	query	boolean	no	Administrators only: true overwrites an existing file of a repository with immutable_releases. Ignored for everyone else.

Responses

Status	Description	Body
200	The upload was already completed; the original result	application/json: PresignedUploadResult
201	Artifact recorded	application/json: PresignedUploadResult
400	The repository is not a hosted raw repository	application/json: Error
401	Authentication required	-
403	Write permission denied, or the caller is neither the creator of the upload nor an administrator	-
404	Repository or upload not found (or expired and swept)	-
409	Code upload_missing: nothing has been uploaded to the upload URL yet. Code upload_in_progress: another complete is verifying this upload (retry after the Retry-After header). Code upload_incomplete: a part of a multipart upload is missing or has the wrong size (the message names the part numbers; upload them and call complete again). Code upload_changed: the staged object was overwritten during verification; the upload was discarded. Code immutable_release: the path already exists in a repository with immutable_releases; nothing was recorded and the upload stays pending (retry with force=true as an administrator)	application/json: Error
410	The upload expired	application/json: Error
422	Size or sha256 does not match the declaration; the upload was discarded	application/json: Error
501	The storage backend does not support presigned uploads	application/json: Error
507	Code quota_exceeded: the repository's storage quota would be exceeded; nothing was recorded and the upload stays pending	application/json: Error

POST /api/v1/repositories/{name}/uploads/{id}/parts

Sign the parts of a multipart upload

Returns presigned PUT URLs for up to 100 parts of a multipart upload, each for exactly the returned size. Call it as often as needed (URLs live as long as the single-upload URL, and every call extends the upload's deadline), PUT the parts in any order and in parallel, then call complete. A part may be re-uploaded. The response carries bearer credentials and is sent with Cache-Control: no-store. Only the creator of the upload or an administrator may call it.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-

Request body (required)

application/json: PresignedPartsRequest

Responses

Status	Description	Body
200	Part upload targets	application/json: PresignedParts
400	Code invalid_part_numbers: empty, duplicate, more than 100 or out-of-range part numbers. Code not_multipart: the upload is a single upload	application/json: Error
401	Authentication required	-
403	Write permission denied, or the caller is neither the creator of the upload nor an administrator	-
404	Repository or upload not found (or expired and swept)	-
409	Code upload_completed: the upload is already completed	application/json: Error
410	The upload expired	application/json: Error
501	The storage backend does not support multipart uploads	application/json: Error