DEVELOPER DOCUMENTATION / OPENAPI 3.0

Build on your registry.

Automate registries, scopes, packages, publisher keys, and recipient download access with a straightforward JSON API.

Make your first request Download OpenAPI YAML

GET STARTED

Your first request

Generate a management API key in Organization → API keys, grant it npm:package:read, and send it as a bearer token. The key acts within the organization that created it.

TerminalList registries

curl https://privatenpm.com/api/v1/registries \ -H "Authorization: Bearer $API_KEY"

The JSON response includes your private registries and the shared registry. Save the returned IDs for operations that target a registry.

01 / ACCESS

Authentication

Every management endpoint requires an organization API key in the Authorization: Bearer header. Give each integration only the permissions shown on the operations it calls. A 401 means the key is missing or invalid; a 403 means it lacks permission.

Three credentials, three jobs.

Management API keys call this API. Publisher keys authenticate npm publish and package maintenance. Download keys grant registry read access to recipients. Treat all three as secrets; issued publisher and download key values appear only once.

02 / CONVENTIONS

Requests and responses

JSON over HTTPS

Use https://privatenpm.com/api/v1 as the base URL. Send Content-Type: application/json when there is a request body. Omit optional properties you are not setting.

Pagination

List endpoints that return nextPageToken can be paged by sending that value as pageToken. Continue until no token is returned.

Safe retries

Operations marked “Idempotency-Key supported” accept a unique Idempotency-Key header. Reuse the same key when retrying the same request.

Errors

Failures return JSON with a stable code and readable message. Handle 429 with backoff; 409 indicates a conflict or stale update.

JSONError response

{ "code": "permission_denied", "message": "This API key cannot perform this action." }

03 / WORKFLOWS

What you can build

01Set up a registryCreate a private registry, then add scopes for your package names. 02Manage packagesCreate and update metadata here; publish tarballs with npm and a publisher key. 03Issue publisher accessGive CI a key scoped to the packages and registries it publishes. 04Grant recipient downloadsIssue a key for selected packages, then rotate or revoke it as needed.

INTEGRATION PATTERN

Publish from CI

Create package metadata and record the package ID.
Issue a publisher key limited to the registry or package, with publish permission.
Store the one-time secret in your CI secret store and publish the tarball with npm.

Read the publishing guide ↗

INTEGRATION PATTERN

Deliver recipient access

Issue a download key for the purchased package IDs.
Show the one-time secret to the recipient over a secure channel.
Rotate or revoke the key when access changes.

Read the download key guide ↗

04 / EVENTS

Webhooks

Register HTTPS endpoints under Settings → Webhooks (Growth and up) and subscribe to the event types below. Every delivery POSTs a signed JSON envelope to your endpoint; verify the Standard Webhooks webhook-id, webhook-timestamp and webhook-signature headers against the raw body before acting on it. Delivery is at least once and unordered — deduplicate by event id. Events are change notifications, not snapshots: fetch current state through this API when you need it.

JSONEvent envelope (schema_version 1)

{ "schema_version": 1, "id": "evt_example", "type": "npm_package.published", "tenant_id": "ten_example", "created_at": "2026-09-21T12:00:00Z", "data": { "resource_type": "npm_package", "resource_id": "rpkg_example", "action": "published", "actor_id": "usr_example" } }

Subscribing to * includes future event types. The Send test event action delivers webhook.test, which shares this envelope and is sent even when the subscription excludes other types. The webhooks guide walks through verification, testing and retries.

Packages

npm_security.created

An administrator enabled a release security watch. The envelope carries its version ID, never inventory or evidence.

npm_security.updated

Security evidence, watch configuration or suppression changed. Read the release security page for current findings.

npm_inspection_report.created

An administrator saved a dated inspection report; the envelope contains its identifier, never the report body.

npm_package.created

A package was created in a registry.

npm_package.updated

Package metadata, visibility or a dist-tag changed.

npm_package.deleted

A package was deleted.

npm_package.published

A version was published.

npm_package.unpublished

A version was unpublished; its number stays tombstoned.

PyPI projects

pypi_upstream_policy.updated

A registry manager changed the public PyPI name policy.

pypi_project.created

A project was created in a PyPI registry.

pypi_project.updated

Project metadata changed or a release was yanked or unyanked.

pypi_project.deleted

A project was deleted; its name stays tombstoned.

pypi_project.published

A release file was uploaded.

pypi_project.unpublished

A release or file was removed; its filename stays tombstoned.

Files packages

files_package.created

A package was created in a files registry.

files_package.updated

A channel moved or a download link was created.

files_package.deleted

A package was deleted; its name stays tombstoned.

files_package.published

A version's objects were uploaded.

files_package.unpublished

A version was deleted; its number stays tombstoned.

Registries

npm_registry.created

A private registry was created.

npm_registry.updated

A registry's display name or hostname changed.

npm_registry.deleted

A private registry was deleted.

Scopes

npm_scope.created

A scope was reserved, including your shared-registry scope.

npm_scope.deleted

A scope reservation was removed.

Publisher keys

npm_token.created

A publisher key was issued.

npm_token.revoked

A publisher key was revoked.

Trusted publishers

npm_trusted_publisher.created

A trusted CI (OIDC) publisher was configured for a package.

npm_trusted_publisher.updated

A package's trusted CI publisher configuration changed.

npm_trusted_publisher.deleted

A package's trusted CI publisher was removed.

Domains

registry_domain.created

A custom registry domain was requested.

registry_domain.updated

Domain verification or certificate status changed.

registry_domain.revoked

A domain was revoked and stops serving the registry.

Download keys

registry_download_key.created

A download key was issued, including through the recipient portal.

registry_download_key.updated

A key's access rule or recipient link changed.

registry_download_key.revoked

A download key was revoked.

Recipients

registry_recipient.created

A recipient was created, including by upsert.

registry_recipient.updated

A recipient was renamed, suspended or resumed.

registry_recipient_portal.created

A recipient portal invitation was created.

registry_recipient_portal.revoked

A portal invitation was revoked, revoking the keys issued through it.

ENDPOINT REFERENCEOpenAPI source ↗

API REFERENCE

Registries

GETList registries POSTCreate a private registry DELETEDelete an empty private registry GETGet the public-package policy PUTReplace the public-package policy

Registries

List registries

GET/api/v1/registries

Includes the shared registry and your private registries.

Permission npm:package:read

Response 200 RegistryList

View response fields

registriesRegistry[]

Registries

Create a private registry

POST/api/v1/registries

The hostname is provisioned with the registry, so the key also needs registry:domain:manage. Save the DNS verification challenge returned here.

Permission npm:registry:manage

JSON request body CreateRegistry

displayNamestring required

hostnamestring required

storageRegionglobal | eu | us

Where package files are stored. Defaults to global (replicated worldwide). Fixed once the registry is created; a region this installation has no storage for is refused.

Response 201 Registry

View response fields

createdAtdate-time

displayNamestring

formatstring

hostnamestring

idstring

kindshared | private

storageRegionglobal | eu | us

Where package files are stored. Shared registries are global.

tenantIdstring

verificationChallengestring

verificationExpiresAtdate-time

Registries

Delete an empty private registry

DELETE/api/v1/registries/{id}

A registry with packages, scopes, domains or credentials cannot be deleted.

Permission npm:registry:manage

Parameters

idpathstring

Response 204

No response body.

Registries

Get the public-package policy

GET/api/v1/registries/{id}/upstream-policy

Returns the caller's policy for this registry. A missing row is mode off with etag 0.

Permission npm:registry:manage

Parameters

idpathstring

Response 200 UpstreamPolicy

View response fields

allowPatternsstring[]

blockPatternsstring[]

etagstring

forwardAuditboolean

minReleaseAgeHoursinteger

modeoff | public | allowlist

registryIdstring

updatedAtdate-time

Registries

Replace the public-package policy

PUT/api/v1/registries/{id}/upstream-policy

Send the etag from the last read to refuse a stale write. A non-off mode requires public package caching on the plan.

Permission npm:registry:manage

Parameters

idpathstring

JSON request body UpdateUpstreamPolicy

allowPatternsstring[]

path.Match globs, such as react or @types/*. Used when mode is allowlist.

blockPatternsstring[]

Always win.

etagstring

Policy etag from the last read. Omit to skip the check.

forwardAuditboolean

minReleaseAgeHoursinteger

Hide versions published upstream more recently than this. 72 is a common delay.

modeoff | public | allowlist required

Response 200 UpstreamPolicy

View response fields

allowPatternsstring[]

blockPatternsstring[]

etagstring

forwardAuditboolean

minReleaseAgeHoursinteger

modeoff | public | allowlist

registryIdstring

updatedAtdate-time

API REFERENCE

Scopes

GETList registry scopes POSTCreate a scope in a private registry POSTReserve your shared registry scope DELETEDelete an unused scope

Scopes

List registry scopes

GET/api/v1/registries/{registryId}/scopes

Permission npm:package:read

Parameters

registryIdpathstring

Response 200 ScopeList

View response fields

scopesScope[]

Scopes

Create a scope in a private registry

POST/api/v1/registries/{registryId}/scopes

Permission npm:scope:manage

Parameters

registryIdpathstring

JSON request body ScopeName

namestring required

With or without the leading @.

Response 201 Scope

View response fields

createdAtdate-time

idstring

namestring

registryIdstring

Scopes

Reserve your shared registry scope

POST/api/v1/scopes/shared

An organization may reserve one shared scope.

Permission npm:scope:manage

JSON request body ScopeName

namestring required

With or without the leading @.

Response 201 Scope

View response fields

createdAtdate-time

idstring

namestring

registryIdstring

Scopes

Delete an unused scope

DELETE/api/v1/scopes/{id}

Permission npm:scope:manage

Parameters

idpathstring

Response 204

No response body.

API REFERENCE

Packages

GETList packages POSTCreate package metadata DELETEDelete an empty package GETGet package PATCHUpdate package metadata DELETERemove a dist tag PUTSet a dist tag DELETERemove trusted CI publisher GETGet trusted CI publisher PUTConfigure trusted CI publisher GETList versions and dist tags POSTRecord CI deployment inventory DELETEUnpublish a version PUTDeprecate or undeprecate a version

Packages

List packages

GET/api/v1/packages

query matches package-name words by prefix. Follow nextPageToken until empty.

Permission npm:package:read

Parameters

registryIdquerystring

queryquerystring

pageSizequeryint32

pageTokenquerystring

Response 200 PackageList

View response fields

nextPageTokenstring

packagesPackage[]

Packages

Create package metadata

POST/api/v1/packages

Publish a tarball with npm using a publisher key. Supports Idempotency-Key.

Permission npm:package:create Idempotency-Key supported

JSON request body CreatePackage

descriptionstring

namestring required

registryIdstring required

visibilityprivate | public

Response 201 Package

View response fields

createdAtdate-time

descriptionstring

etagstring

idstring

namestring

registryIdstring

updatedAtdate-time

visibilityprivate | public

Packages

Delete an empty package

DELETE/api/v1/packages/{id}

Permission npm:package:delete

Parameters

idpathstring

Response 204

No response body.

Packages

Get package

GET/api/v1/packages/{id}

Permission npm:package:read

Parameters

idpathstring

Response 200 Package

View response fields

createdAtdate-time

descriptionstring

etagstring

idstring

namestring

registryIdstring

updatedAtdate-time

visibilityprivate | public

Packages

Update package metadata

PATCH/api/v1/packages/{id}

Send the latest etag to reject stale edits.

Permission npm:package:update

Parameters

idpathstring

JSON request body UpdatePackage

descriptionstring

etagstring

visibilityprivate | public

Response 200 Package

View response fields

createdAtdate-time

descriptionstring

etagstring

idstring

namestring

registryIdstring

updatedAtdate-time

visibilityprivate | public

Packages

Remove a dist tag

DELETE/api/v1/packages/{packageId}/dist-tags/{tag}

Permission npm:package:update

Parameters

packageIdpathstring

tagpathstring

Response 204

No response body.

Packages

Set a dist tag

PUT/api/v1/packages/{packageId}/dist-tags/{tag}

Permission npm:package:update

Parameters

packageIdpathstring

tagpathstring

JSON request body TagVersion

versionstring required

Response 200 DistTag

View response fields

tagstring

versionstring

Packages

Remove trusted CI publisher

DELETE/api/v1/packages/{packageId}/trusted-publisher

Permission registry:credential:manage

Parameters

packageIdpathstring

Response 204

No response body.

Packages

Get trusted CI publisher

GET/api/v1/packages/{packageId}/trusted-publisher

Answers 404 when the package has no trusted publisher.

Permission registry:credential:manage

Parameters

packageIdpathstring

Response 200 TrustedPublisher

View response fields

createdAtdate-time

environmentstring

idstring

issuerstring

packageIdstring

providergithub | gitlab

registryIdstring

repositoryExternalIdstring

Rename-stable repository id, learned from the first exchange when unset.

repositoryNamestring

repositoryOwnerstring

updatedAtdate-time

workflowstring

Packages

Configure trusted CI publisher

PUT/api/v1/packages/{packageId}/trusted-publisher

Upserts the one trusted publisher per package; you become the subject exchanged credentials act as. CI workflows then publish with OIDC alone (npm CLI >= 11.5.1, id-token: write on GitHub Actions or an NPM_ID_TOKEN id_token on GitLab CI with audience npm:<registry host>).

Permission registry:credential:manage

Parameters

packageIdpathstring

JSON request body SetTrustedPublisher

environmentstring

issuerstring

OIDC issuer override for self-managed CI; empty pins the provider default.

providergithub | gitlab required

repositoryExternalIdstring

Rename-stable repository id (GitHub repository_id, GitLab project_id).

repositoryNamestring required

repositoryOwnerstring required

GitHub owner or GitLab namespace path.

workflowstring required

Workflow file path, e.g. .github/workflows/publish.yml or .gitlab-ci.yml.

Response 200 TrustedPublisher

View response fields

createdAtdate-time

environmentstring

idstring

issuerstring

packageIdstring

providergithub | gitlab

registryIdstring

repositoryExternalIdstring

Rename-stable repository id, learned from the first exchange when unset.

repositoryNamestring

repositoryOwnerstring

updatedAtdate-time

workflowstring

Packages

List versions and dist tags

GET/api/v1/packages/{packageId}/versions

Permission npm:package:read

Parameters

packageIdpathstring

Response 200 VersionList

View response fields

distTagsDistTag[]

versionsPackageVersion[]

Packages

Record CI deployment inventory

POST/api/v1/packages/{packageId}/versions/{version}/security-evidence

Evidence must match the immutable artifact integrity. This records authenticated submitter testimony, not verified runtime reachability. Runtime agents are not supported by this endpoint. Never submit command lines, environment values or secrets.

Permission npm:package:read

Parameters

packageIdpathstring

versionpathstring

JSON request body SecurityEvidence

artifactIntegritystring required

Exact SHA-512 SRI of the watched artifact.

environmentstring required

eventIdstring required

Stable source event ID; retries are deduplicated.

expiresAtdate-time required

Future expiry at most 30 days away.

imageDigeststring

Optional immutable container image digest reported by CI.

kinddeployment required

observedAtdate-time required

At most 24 hours old or 5 minutes in the future.

Response 200

No response body.

Packages

Unpublish a version

DELETE/api/v1/versions/{id}

Permission npm:package:delete

Parameters

idpathstring

Response 204

No response body.

Packages

Deprecate or undeprecate a version

PUT/api/v1/versions/{id}/deprecation

Set message to an empty string to clear deprecation.

Permission npm:package:update

Parameters

idpathstring

JSON request body Deprecation

messagestring required

Response 204

No response body.

API REFERENCE

PyPI projects

DELETEDelete a file GETList PyPI projects DELETEDelete a PyPI project GETGet a PyPI project GETList releases and files DELETEDelete a release POSTUnyank a release POSTYank a release

PyPI projects

Delete a file

DELETE/api/v1/pypi/files/{id}

The filename stays reserved and cannot be uploaded again. etag is the project etag.

Permission pypi:project:delete

Parameters

idpathstring

etagquerystring

Response 204

No response body.

PyPI projects

List PyPI projects

GET/api/v1/pypi/projects

Follow nextPageToken until empty.

Permission pypi:project:read

Parameters

registryIdquerystring

queryquerystring

pageSizequeryint32

pageTokenquerystring

Response 200 PypiProjectList

View response fields

nextPageTokenstring

projectsPypiProject[]

PyPI projects

Delete a PyPI project

DELETE/api/v1/pypi/projects/{id}

Refused while the project still has files unless force is true, which tombstones them first. The name stays reserved.

Permission pypi:project:delete

Parameters

idpathstring

forcequeryboolean

etagquerystring

Project etag. Omit to skip the check.

Response 204

No response body.

PyPI projects

Get a PyPI project

GET/api/v1/pypi/projects/{id}

Permission pypi:project:read

Parameters

idpathstring

Response 200 PypiProject

View response fields

createdAtdate-time

displayNamestring

etagstring

idstring

namestring

registryIdstring

summarystring

updatedAtdate-time

PyPI projects

List releases and files

GET/api/v1/pypi/projects/{id}/releases

Releases are newest first; each includes its live files.

Permission pypi:project:read

Parameters

idpathstring

Response 200 PypiReleaseList

View response fields

releasesPypiRelease[]

PyPI projects

Delete a release

DELETE/api/v1/pypi/projects/{id}/releases/{version}

Tombstones every file of the version. Filenames stay reserved.

Permission pypi:project:delete

Parameters

idpathstring

versionpathstring

etagquerystring

Response 204

No response body.

PyPI projects

Unyank a release

POST/api/v1/pypi/projects/{id}/releases/{version}/unyank

Permission pypi:project:publish

Parameters

idpathstring

versionpathstring

JSON request body PypiEtag

etagstring

Project etag. Omit to skip the check.

Response 204

No response body.

PyPI projects

Yank a release

POST/api/v1/pypi/projects/{id}/releases/{version}/yank

Yanked files stay downloadable and are marked on the simple index (PEP 592).

Permission pypi:project:publish

Parameters

idpathstring

versionpathstring

JSON request body PypiYank

etagstring

Project etag. Omit to skip the check.

reasonstring

Optional PEP 592 yank reason.

Response 204

No response body.

API REFERENCE

Files packages

GETList files packages GETGet a files package PUTPoint a channel at a version POSTCreate a signed download link GETList versions and channels DELETEDelete a version GETList objects in a version

Files packages

List files packages

GET/api/v1/files/packages

Follow nextPageToken until empty.

Permission files:object:read

Parameters

registryIdquerystring

queryquerystring

pageSizequeryint32

pageTokenquerystring

Response 200 FilesPackageList

View response fields

nextPageTokenstring

packagesFilesPackage[]

Files packages

Get a files package

GET/api/v1/files/packages/{id}

Permission files:object:read

Parameters

idpathstring

Response 200 FilesPackage

View response fields

createdAtdate-time

idstring

namestring

registryIdstring

updatedAtdate-time

visibilitystring

Files packages

Point a channel at a version

PUT/api/v1/files/packages/{id}/channels

Channels are mutable pointers such as latest.

Permission files:object:write

Parameters

idpathstring

JSON request body FilesChannelUpdate

channelstring required

versionstring required

Response 204

No response body.

Files packages

Create a signed download link

POST/api/v1/files/packages/{id}/download-links

The token is shown once. Prefix path with the registry host — and the slug, on the shared files host — to form the URL. Every download is ledgered.

Permission files:object:write

Parameters

idpathstring

JSON request body FilesDownloadLinkCreate

lifetimeSecondsint64 required

15 minutes (900) to 7 days (604800).

pathstring required

versionstring required

Response 200 FilesDownloadLink

View response fields

expiresAtdate-time

pathstring

Protocol path /-/dl/{token}. Prefix the registry host.

tokenstring

Shown once.

Files packages

List versions and channels

GET/api/v1/files/packages/{id}/versions

Live versions and the channels that point at them.

Permission files:object:read

Parameters

idpathstring

Response 200 FilesVersionList

View response fields

channelsFilesChannel[]

versionsFilesVersion[]

Files packages

Delete a version

DELETE/api/v1/files/packages/{id}/versions/{version}

Tombstones the version. The version string stays reserved.

Permission files:object:delete

Parameters

idpathstring

versionpathstring

Response 204

No response body.

Files packages

List objects in a version

GET/api/v1/files/versions/{id}/objects

id is the version id. Follow nextPageToken until empty.

Permission files:object:read

Parameters

idpathstring

pageSizequeryint32

pageTokenquerystring

Response 200 FilesObjectList

View response fields

nextPageTokenstring

objectsFilesObject[]

API REFERENCE

Publisher keys

GETList publisher keys POSTIssue a publisher key DELETERevoke a publisher key GETGet publisher key metadata POSTRotate a publisher key

Publisher keys

List publisher keys

GET/api/v1/publisher-keys

Permission registry:credential:manage

Parameters

pageSizequeryint32

pageTokenquerystring

Response 200 PublisherKeyList

View response fields

keysPublisherKey[]

nextPageTokenstring

Publisher keys

Issue a publisher key

POST/api/v1/publisher-keys

The secret is shown once. Not idempotent; a retry issues a new key.

Permission registry:credential:manage

JSON request body IssuePublisherKey

allPackagesboolean

expiresAtdate-time

namestring required

packageIdsstring[]

Packages of the registry: npm packages, PyPI projects or Files packages.

Operations the key may perform. They must belong to the format of the registry in registryIds; identity:read serves every format. npm: metadata:read, tarball:read, npm:upstream:read, package:publish, dist-tag:write, package:unpublish. PyPI: pypi:project:read, pypi:project:publish, pypi:project:delete. Files: files:object:read, files:object:write, files:object:delete.

registryIdsstring[] required

scopeIdsstring[]

npm scopes (npm registries only).

userIdstring

Omit for the caller.

Response 201 IssuedPublisherKey

View response fields

keyPublisherKey

secretstring

Shown once.

Publisher keys

Revoke a publisher key

DELETE/api/v1/publisher-keys/{id}

Permission registry:credential:manage

Parameters

idpathstring

Response 204

No response body.

Publisher keys

Get publisher key metadata

GET/api/v1/publisher-keys/{id}

The secret is never returned here.

Permission registry:credential:manage

Parameters

idpathstring

Response 200 PublisherKey

View response fields

allPackagesboolean

createdAtdate-time

displayPrefixstring

expiresAtdate-time

idstring

lastUsedAtdate-time

namestring

packageIdsstring[]

permissionsstring[]

registryIdsstring[]

revokedboolean

scopeIdsstring[]

subjectKindstring

Always publisher.

userIdstring

Publisher keys

Rotate a publisher key

POST/api/v1/publisher-keys/{id}/rotate

Save the new secret; the old one stops working. Not idempotent; a retry rotates again.

Permission registry:credential:manage

Parameters

idpathstring

Response 200 IssuedPublisherKey

View response fields

keyPublisherKey

secretstring

Shown once.

API REFERENCE

Recipients

GETSearch recipients POSTCreate or update a recipient GETGet a recipient PATCHSuspend or resume a recipient

Recipients

Search recipients

GET/api/v1/recipients

Matches recipient names and external references; omit query to list all.

Permission registry:download_key:manage

Parameters

queryquerystring

Response 200 RecipientList

View response fields

recipientsRecipient[]

Recipients

Create or update a recipient

POST/api/v1/recipients

Upserts by externalRef, so a retry with the same reference returns the same recipient instead of duplicating it.

Permission registry:download_key:manage

JSON request body UpsertRecipient

externalRefstring required

Your stable reference for this recipient, such as an account or team ID.

namestring required

Response 200 Recipient

View response fields

createdAtdate-time

externalRefstring

idstring

namestring

suspendedAtdate-time

updatedAtdate-time

Recipients

Get a recipient

GET/api/v1/recipients/{id}

Permission registry:download_key:manage

Parameters

idpathstring

Response 200 Recipient

View response fields

createdAtdate-time

externalRefstring

idstring

namestring

suspendedAtdate-time

updatedAtdate-time

Recipients

Suspend or resume a recipient

PATCH/api/v1/recipients/{id}

A suspended recipient's download keys stop working until it is resumed; use this for refunds and chargebacks.

Permission registry:download_key:manage

Parameters

idpathstring

JSON request body RecipientSuspension

suspendedboolean required

Response 200 Recipient

View response fields

createdAtdate-time

externalRefstring

idstring

namestring

suspendedAtdate-time

updatedAtdate-time

API REFERENCE

Download keys

GETList download keys POSTIssue a recipient download key POSTEnsure a recipient download key DELETERevoke a download key GETGet download key metadata PATCHChange download access POSTRotate a download key

Download keys

List download keys

GET/api/v1/download-keys

Permission registry:download_key:manage

Parameters

pageSizequeryint32

pageTokenquerystring

Response 200 DownloadKeyList

View response fields

keysDownloadKey[]

nextPageTokenstring

Download keys

Issue a recipient download key

POST/api/v1/download-keys

Save the returned secret; an admin can reveal it again in the dashboard. Not idempotent; a retry issues a new key.

Permission registry:download_key:manage

JSON request body IssueDownloadKey

allPackagesboolean

expiresAtdate-time

externalRefstring

Your stable reference for this key, such as an order ID. Required by the ensure operation.

issuedTostring required

namestring required

newRecipientNamestring

Create and link a recipient with this name. Mutually exclusive with recipientId.

packageIdsstring[]

recipientIdstring

Link the key to this recipient; the recipient name becomes issuedTo.

registryIdstring required

scopeIdstring

Response 201 IssuedDownloadKey

View response fields

keyDownloadKey

secretstring

The bearer secret. Stored encrypted; ensure returns it again and an admin can reveal it in the dashboard.

Download keys

Ensure a recipient download key

POST/api/v1/download-keys/ensure

One stable key per recipient and externalRef; a retry returns the same key and secret, and changed access (packageIds, scopeId, allPackages) is applied to it. Requires recipientId and externalRef; upsert the recipient first.

Permission registry:download_key:manage

JSON request body IssueDownloadKey

allPackagesboolean

expiresAtdate-time

externalRefstring

Your stable reference for this key, such as an order ID. Required by the ensure operation.

issuedTostring required

namestring required

newRecipientNamestring

Create and link a recipient with this name. Mutually exclusive with recipientId.

packageIdsstring[]

recipientIdstring

Link the key to this recipient; the recipient name becomes issuedTo.

registryIdstring required

scopeIdstring

Response 200 IssuedDownloadKey

View response fields

keyDownloadKey

secretstring

The bearer secret. Stored encrypted; ensure returns it again and an admin can reveal it in the dashboard.

Download keys

Revoke a download key

DELETE/api/v1/download-keys/{id}

Permission registry:download_key:manage

Parameters

idpathstring

Response 200 DownloadKey

View response fields

allPackagesboolean

createdAtdate-time

credentialVersionstring

displayPrefixstring

expiresAtdate-time

externalRefstring

idstring

issuedTostring

lastUsedAtdate-time

namestring

packageIdsstring[]

recipientIdstring

registryIdstring

revokedAtdate-time

scopeIdstring

Download keys

Get download key metadata

GET/api/v1/download-keys/{id}

Permission registry:download_key:manage

Parameters

idpathstring

Response 200 DownloadKey

View response fields

allPackagesboolean

createdAtdate-time

credentialVersionstring

displayPrefixstring

expiresAtdate-time

externalRefstring

idstring

issuedTostring

lastUsedAtdate-time

namestring

packageIdsstring[]

recipientIdstring

registryIdstring

revokedAtdate-time

scopeIdstring

Download keys

Change download access

PATCH/api/v1/download-keys/{id}

Supply exactly one of allPackages, scopeId or packageIds.

Permission registry:download_key:manage

Parameters

idpathstring

JSON request body DownloadAccess

allPackagesboolean

packageIdsstring[]

scopeIdstring

Response 200 DownloadKey

View response fields

allPackagesboolean

createdAtdate-time

credentialVersionstring

displayPrefixstring

expiresAtdate-time

externalRefstring

idstring

issuedTostring

lastUsedAtdate-time

namestring

packageIdsstring[]

recipientIdstring

registryIdstring

revokedAtdate-time

scopeIdstring

Download keys

Rotate a download key

POST/api/v1/download-keys/{id}/rotate

Save the new secret. Not idempotent; a retry rotates again.

Permission registry:download_key:manage

Parameters

idpathstring

Response 200 IssuedDownloadKey

View response fields

keyDownloadKey

secretstring

The bearer secret. Stored encrypted; ensure returns it again and an admin can reveal it in the dashboard.

API REFERENCE

Transfers

GETList transfers GETSummarize transfers

Transfers

List transfers

GET/api/v1/transfers

Pages the transfer ledger (one row per observed content transfer), newest first. Unset filters match everything; startTime is inclusive, endTime exclusive. Follow nextPageToken until empty.

Permission registry:transfer:read

Parameters

registryIdquerystring

formatquerystring

packageNamequerystring

versionquerystring

directionquerydownload | publish | upstream_serve

statusquerycomplete | partial | aborted | redirected

credentialKindquerypublisher_key | download_key | trusted_publisher | session

credentialIdquerystring

recipientIdquerystring

userIdquerystring

clientIpquerystring

An IP address or a CIDR range.

countryquerystring

ISO 3166-1 alpha-2.

clientquerystring

Parsed client token, e.g. `npm/10.8.1`.

ciqueryboolean

Continuous-integration clients only (or exclude them).

startTimequerydate-time

endTimequerydate-time

pageSizequeryint32

pageTokenquerystring

Response 200 TransferList

View response fields

nextPageTokenstring

prevPageTokenstring

transfersTransfer[]

Transfers

Summarize transfers

GET/api/v1/transfers/summary

Totals the filtered range by one dimension. A day grouping over only registry/format/direction/range filters reads the daily aggregate; every other combination groups the ledger.

Permission registry:transfer:read

Parameters

registryIdquerystring

formatquerystring

packageNamequerystring

versionquerystring

directionquerydownload | publish | upstream_serve

statusquerycomplete | partial | aborted | redirected

credentialKindquerypublisher_key | download_key | trusted_publisher | session

credentialIdquerystring

recipientIdquerystring

userIdquerystring

clientIpquerystring

An IP address or a CIDR range.

countryquerystring

ISO 3166-1 alpha-2.

clientquerystring

Parsed client token, e.g. `npm/10.8.1`.

ciqueryboolean

startTimequerydate-time

endTimequerydate-time

Response 200 TransferSummaryList

View response fields

groupsTransferSummaryGroup[]

totalBytesint64

totalRequestsint64

API REFERENCE

Audit log

GETList audit log entries

Audit log

List audit log entries

GET/api/v1/audit-logs

Pages the organization's audit log, newest first. Follow nextPageToken until empty.

Permission audit:read

Parameters

userIdquerystring

resourceTypequerystring

resourceIdquerystring

actionquerycreated | updated | deleted | accessed

credentialIdquerystring

The credential the change was made with (session, API key or registry token ID).

startTimequerydate-time

endTimequerydate-time

pageSizequeryint32

pageTokenquerystring

Response 200 AuditLogList

View response fields

auditLogsAuditLog[]

nextPageTokenstring

Ready to build?

Create a management key with the permissions your integration needs, or import the OpenAPI file into your client tooling.

Create an API key ↗Download OpenAPI YAML ↗