Curation API
7 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/repositories/{name}/availability
Explain whether a package version is available
Evaluates the holds that apply to one package version of a repository and lists the ones that do. A proxy repository reports its blocked flag, its curation rules and its minimum age; the publish time comes from the metadata already cached, never from the upstream, so min_age is unknown when the repository has a minimum age but the version cannot be dated. A hosted repository reports its blocked flag and the quarantine and license-policy holds of the stored version (only for formats stored in the generic package tables; scan results are matched through the version's files). A group repository has no verdict of its own, because it serves what its members serve: ask a member (400). Package and version are matched the way the format names them, see the Package curation section of the repository docs. Needs read access to the repository.
Security: bearerAuth or cookieAuth or .
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
package | query | string | yes | Package name, at most 1024 bytes. |
version | query | string | yes | Version string as clients see it, at most 1024 bytes. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The verdict | application/json: AvailabilityResponse |
400 | Missing or oversized package or version, or the repository is a group (validation_failed) | application/json: Error |
403 | No read access to the repository | application/json: Error |
404 | Repository not found | application/json: Error |
GET /api/v1/repositories/{name}/curation-rules
List curation rules
The curation rules of a proxy repository in creation order. Requires global admin, or the maintainer or owner role in the repository's project. The rules only take effect while the repository's curation_mode is denylist or allowlist.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | The rules | application/json: CurationRules |
400 | The repository is not a proxy repository (validation_failed) | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Repository not found | application/json: Error |
POST /api/v1/repositories/{name}/curation-rules
Create curation rule
Add a block or allow rule to a proxy repository. A repository holds at most 1000 rules. Audited as curation.rule_created. Requires global admin, or the maintainer or owner role in the repository's project.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
action | string | yes | One of: block, allow. |
package_pattern | string | yes | Maximum length: 255. |
reason | string | no | Maximum length: 500. |
version_pattern | string | no | Empty or absent matches every version. Maximum length: 128. |
Responses
| Status | Description | Body |
|---|---|---|
201 | Rule created | application/json: CurationRule |
400 | Invalid rule, or the repository is not a proxy repository (validation_failed) | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Repository not found | application/json: Error |
409 | The repository already holds the maximum number of rules (conflict) | application/json: Error |
PATCH /api/v1/repositories/{name}/curation-rules/{id}
Update curation rule
Change any of the rule's action, patterns and reason; absent fields keep their value. The rule must belong to the repository in the path. Audited as curation.rule_updated. Requires global admin, or the maintainer or owner role in the repository's project.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
action | string | no | One of: block, allow. |
package_pattern | string | no | Maximum length: 255. |
reason | string | no | Maximum length: 500. |
version_pattern | string | no | Maximum length: 128. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Rule updated | application/json: CurationRule |
400 | Invalid rule, or the repository is not a proxy repository (validation_failed) | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Repository or rule not found (also a rule of another repository, or an id that is not a UUID) | application/json: Error |
DELETE /api/v1/repositories/{name}/curation-rules/{id}
Delete curation rule
Remove a rule. The rule must belong to the repository in the path. Audited as curation.rule_deleted. Requires global admin, or the maintainer or owner role in the repository's project.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | Rule deleted | - |
400 | The repository is not a proxy repository (validation_failed) | application/json: Error |
403 | Forbidden | application/json: Error |
404 | Repository or rule not found (also a rule of another repository, or an id that is not a UUID) | application/json: Error |
GET /api/v1/repositories/{name}/held-back-versions
List the versions of a proxy package held back by the gate
Lists the versions of one package of a proxy repository that the repository's gate keeps from its clients: the minimum age and the curation rules, the same gate the proxy applies to downloads and metadata. The versions are read from the upstream metadata already cached, never fetched, so supported is false (and the list empty) when the format cannot list the versions of a package or nothing is cached yet. Newest first. Only proxy repositories hold versions back: any other repository type is a 400.
Security: bearerAuth or cookieAuth or .
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
package | query | string | yes | Package name, at most 1024 bytes. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The held-back versions | application/json: HeldBackResponse |
400 | Missing or oversized package, or the repository is not a proxy (validation_failed) | application/json: Error |
403 | No read access to the repository | application/json: Error |
404 | Repository not found | application/json: Error |
GET /api/v1/repositories/{name}/proxy-versions
List the versions of a proxy package known from cached metadata
Lists every version of one package of a proxy repository that the upstream metadata already in the cache names, newest first, each available (clients can install it) or held (the repository's gate keeps it from them: the minimum age or a curation rule, with the reasons), with its publish time and whether a file of it is already cached locally. Nothing is fetched from the upstream: supported is false (and the list empty) when the format cannot list the versions of a package or nothing is cached yet, and cache_known is false when the format's cache keys do not name versions. Only proxy repositories have such a list: any other repository type is a 400.
Security: bearerAuth or cookieAuth or .
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
package | query | string | yes | Package name, at most 1024 bytes. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The versions of the package | application/json: ProxyVersionsResponse |
400 | Missing or oversized package, or the repository is not a proxy (validation_failed) | application/json: Error |
403 | No read access to the repository | application/json: Error |
404 | Repository not found | application/json: Error |