Admin API

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

Endpoints

GET /api/v1/admin/audit

List audit entries

List audit log entries, newest first (admin only). Two paging modes: offset paging (page/per_page, the default) and keyset paging (cursor). Keyset paging never counts rows or scans past an offset, so it stays fast on large tables; follow next_cursor while has_more is true. In offset mode total is exact when total_exact is true (small tables and the last page); otherwise it is the planner's row estimate (no filter) or a lower bound (with actor/action filters).

Parameters

Name	In	Type	Required	Description
page	query	integer	no	1-based page number (offset paging). Ignored when cursor is present. Minimum: 1.
per_page	query	integer	no	Minimum: 1. Maximum: 100.
cursor	query	string	no	Opaque next_cursor of the previous page. Present but empty starts keyset paging at the newest entry. Selects keyset paging: the response carries no page, total or total_exact.
actor	query	string	no	Case-insensitive substring of the actor name or actor id.
action	query	string	no	Case-insensitive substring of the action name.

Responses

Status	Description	Body
200	Paginated list of audit entries	application/json: object
400	Malformed cursor	-
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of AuditEntry	no	-
has_more	boolean	no	True when entries follow this page.
next_cursor	string	no	Pass as cursor to fetch the next page. Absent when has_more is false.
page	integer	no	Offset paging only.
per_page	integer	no	-
total	integer	no	Offset paging only. See total_exact.
total_exact	boolean	no	Offset paging only. False when total is an estimate or a lower bound.

GET /api/v1/admin/audit/export

Export audit log

Export the audit log as JSONL or CSV (admin only). Streams the log as a download without counting rows: entries are read in keyset pages (newest first) and flushed after every page, so memory stays bounded however long the log is. The body is chunked (no Content-Length); if the server fails after the response started the connection is aborted rather than ended normally, so a truncated file is detectable. In CSV, cells starting with =, +, -, @, tab or CR are prefixed with ' to defuse spreadsheet formula injection. Fields (stable; new fields may be appended): id, timestamp (RFC 3339, UTC), action, actor, actor_type, actor_id, resource_type, resource_id, repository_id, project_id, ip, details (JSON object; in CSV its JSON text). Unset values are null in JSONL and empty in CSV.

Parameters

Name	In	Type	Required	Description
format	query	string	no	jsonl (default): one JSON object per line. csv: header row plus one record per entry. One of: jsonl, csv. Default: jsonl.
since	query	string	no	Only entries at or after this instant: RFC 3339 timestamp or YYYY-MM-DD (00:00 UTC).
until	query	string	no	Only entries strictly before this instant (same forms as since); must be after since.
actor	query	string	no	Case-insensitive substring of the actor name or actor id.
action	query	string	no	Case-insensitive substring of the action name.

Responses

Status	Description	Body
200	Audit export stream Headers: Content-Disposition.	application/x-ndjson: string; text/csv: string
400	Unknown format, malformed since/until, or since not before until	-
403	Admin access required	-

GET /api/v1/admin/backup

List backups

List all backups (admin only)

Responses

Status	Description	Body
200	List of backups	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
backups	array of Backup	no	-

POST /api/v1/admin/backup

Create backup

Trigger a new backup (admin only)

Request body (required)

application/json: object

Field	Type	Required	Description
type	string	yes	One of: full, metadata-only.

Responses

Status	Description	Body
202	Backup started	application/json: object
400	Invalid request	application/json: Error
403	Admin access required	-

Fields of the 202 response (application/json):

Field	Type	Required	Description
created_at	string (date-time)	no	-
id	string (uuid)	no	-
status	string	no	One of: pending, in_progress, completed, failed.
type	string	no	One of: full, metadata-only.

GET /api/v1/admin/backup/{id}

Get backup

Get details of a specific backup (admin only)

Parameters

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

Responses

Status	Description	Body
200	Backup details	application/json: Backup
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Backup not found	-

GET /api/v1/admin/backup/{id}/download

Download backup

Download a backup file (admin only)

Parameters

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

Responses

Status	Description	Body
200	Backup file	application/octet-stream: string (binary)
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Backup not found	-

GET /api/v1/admin/gpg/keys

List GPG keys

Lists the database-managed signing keys plus the read-only entry for the key configured through gpg.keyPath / GPG_KEY_PATH (admin only). Private key material is never returned.

Responses

Status	Description	Body
200	List of GPG keys	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
can_store_keys	boolean	no	False when OPENARTIFACT_SECRET_KEY is not set: keys cannot be imported or generated because private keys are only stored encrypted.
keys	array of GPGKey	no	-

POST /api/v1/admin/gpg/keys

Import GPG key

Imports an ASCII-armored private key (admin only). A passphrase-protected key is unlocked with passphrase and stored without it, sealed with OPENARTIFACT_SECRET_KEY. The key becomes the global active key when nothing signs globally yet, unless activate says otherwise.

Request body (required)

application/json: object

Field	Type	Required	Description
activate	boolean	no	Make it the global active key; default: only when nothing signs globally yet
name	string	no	Unique display name; defaults to key-<keyid>. Maximum length: 255.
passphrase	string	no	Passphrase of a protected key
private_key	string	yes	ASCII-armored private key

Responses

Status	Description	Body
201	GPG key imported	application/json: GPGKey
400	Invalid, protected (code passphrase_required), revoked or expired key	-
403	Admin access required	-
409	Name or fingerprint already exists, or OPENARTIFACT_SECRET_KEY is not set (code secret_key_required)	-

POST /api/v1/admin/gpg/keys/generate

Generate GPG key

Generates a signing key pair on the server (admin only). The private key is stored sealed and never returned; export the public key with the export route.

Request body

application/json: object

Field	Type	Required	Description
activate	boolean	no	Make it the global active key; default: only when nothing signs globally yet
algorithm	string	no	One of: ed25519, rsa4096. Default: ed25519.
comment	string	no	-
email	string	no	-
name	string	no	Maximum length: 255.
user_name	string	no	User id name; default OpenArtifact repository signing key

Responses

Status	Description	Body
201	GPG key generated	application/json: GPGKey
400	Invalid input	-
403	Admin access required	-
409	Name already exists, or OPENARTIFACT_SECRET_KEY is not set (code secret_key_required)	-

DELETE /api/v1/admin/gpg/keys/{id}

Delete GPG key

Deletes a database-managed key (admin only). An active key (global or assigned to a repository) is refused with 409 key_in_use unless force=true; the repositories it signed are then re-signed by the next applicable key or become unsigned. The config key cannot be deleted.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key
force	query	boolean	no	-

Responses

Status	Description	Body
204	GPG key deleted	-
400	Invalid request	application/json: Error
403	Admin access required	-
404	GPG key not found	-
409	Key is active (key_in_use) or read-only	-

PUT /api/v1/admin/gpg/keys/{id}/activate

Activate GPG key

Makes the key sign every deb, rpm and pacman repository without a key of its own (global scope), or only the named hosted deb, rpm or pacman repository when repository is given. Affected repositories are re-signed (admin only).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key

Request body

application/json: object

Field	Type	Required	Description
repository	string	no	Repository name; omit for the global scope

Responses

Status	Description	Body
200	The key	application/json: GPGKey
400	Repository is not a hosted deb, rpm or pacman repository	-
403	Admin access required	-
404	Key or repository not found	-
409	Read-only config key	-

DELETE /api/v1/admin/gpg/keys/{id}/activate

Deactivate GPG key

Stops the key signing globally, or for the repository named in the repository query parameter (admin only).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key
repository	query	string	no	-

Responses

Status	Description	Body
204	Deactivated	-
400	Invalid request	application/json: Error
403	Admin access required	-
404	Key or repository not found	-
409	The key was not active there, or it is the read-only config key	-

GET /api/v1/admin/gpg/keys/{id}/export

Export public key

Downloads the ASCII-armored public key (admin only).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key

Responses

Status	Description	Body
200	Armored public key	application/pgp-keys: string
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Admin access required	-
404	GPG key not found	-

GET /api/v1/admin/license/policies

List all license policies

List all license policies (admin only)

Responses

Status	Description	Body
200	List of license policies	-
403	Forbidden	application/json: Error

POST /api/v1/admin/license/policies

Create global license policy

Create a global license policy (admin only)

Request body (required)

application/json: LicensePolicy

Responses

Status	Description	Body
201	License policy created	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error

GET /api/v1/admin/quotas

List all quotas

Every live repository and every project with its quota and live usage, largest usage first, in one request. A repository or project without a limit is listed as unlimited. Admin only.

Parameters

Name	In	Type	Required	Description
scope	query	string	no	One of: repository, project.
limited	query	boolean	no	true keeps only quotas that enforce a limit.
q	query	string	no	Case-insensitive substring of the repository or project name.
page	query	integer	no	Default: 1. Minimum: 1.
limit	query	integer	no	Default: 500. Minimum: 1. Maximum: 2000.

Responses

Status	Description	Body
200	One page of quotas	application/json: QuotaOverviewList
400	Invalid scope	-
403	Admin access required	-

GET /api/v1/admin/recovery/status

Disaster-recovery journal status

State of the row journal behind openartifact rebuild: how many changed package rows still wait for their sidecar blob, how old the oldest is, the last failure and the progress of the backfill reconcile (admin only)

Responses

Status	Description	Body
200	Journal status	application/json: RecoveryStatus
403	Admin access required	-

POST /api/v1/admin/restore

Restore backup

Restore from a backup file (admin only) - multipart form upload

Request body (required)

multipart/form-data: object

Field	Type	Required	Description
file	string (binary)	yes	Backup file to restore

Responses

Status	Description	Body
200	Restore started	-
400	Invalid backup file	-
409	A restore is already in progress	-

GET /api/v1/admin/sso-providers

List SSO providers

List all SSO providers (admin only)

Responses

Status	Description	Body
200	List of SSO providers	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
providers	array of SSOProvider	yes	-

POST /api/v1/admin/sso-providers

Create SSO provider

Create a new SSO provider (admin only)

Request body (required)

application/json: object

Field	Type	Required	Description
config	object	no	-
display_name	string	yes	-
enabled	boolean	no	-
kind	string	yes	One of: oidc, saml.
slug	string	yes	-

Responses

Status	Description	Body
201	SSO provider created	application/json: SSOProvider
400	Invalid request	application/json: Error
403	Admin access required	-

GET /api/v1/admin/sso-providers/{slug}

Get SSO provider

Get details of a specific SSO provider (admin only)

Parameters

Name	In	Type	Required	Description
slug	path	string	yes	-

Responses

Status	Description	Body
200	SSO provider details	application/json: SSOProvider
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	SSO provider not found	-

PATCH /api/v1/admin/sso-providers/{slug}

Update SSO provider

Update an SSO provider (admin only)

Parameters

Name	In	Type	Required	Description
slug	path	string	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
config	object	no	-
display_name	string	no	-
enabled	boolean	no	-

Responses

Status	Description	Body
200	SSO provider updated	application/json: SSOProvider
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	SSO provider not found	-

DELETE /api/v1/admin/sso-providers/{slug}

Delete SSO provider

Delete an SSO provider (admin only)

Parameters

Name	In	Type	Required	Description
slug	path	string	yes	-

Responses

Status	Description	Body
204	SSO provider deleted	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	SSO provider not found	-

POST /api/v1/admin/sso-providers/{slug}/test

Test SSO provider

Test an SSO provider configuration (admin only)

Parameters

Name	In	Type	Required	Description
slug	path	string	yes	-

Responses

Status	Description	Body
200	Test result	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
404	SSO provider not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
error	string	no	-
kind	string	no	-
message	string	no	-
ok	boolean	no	-

GET /api/v1/admin/storage

List storage backends

List the storage backends stored in the database (items) and the primary store the server is configured with (primary, read-only; absent when none is wired). The primary store is not part of items or total. Its status comes from a health check cached for 10 seconds.

Responses

Status	Description	Body
200	List of storage backends	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
items	array of StorageBackend	no	-
primary	StoragePrimary	no	-
total	integer	no	-

POST /api/v1/admin/storage

Create storage backend

Create a new storage backend (admin only). The names "primary" and "replication" are reserved (they are static paths under /admin/storage): creating one answers 400

Request body (required)

application/json: object

Field	Type	Required	Description
config	object	no	-
kind	string	yes	One of: filesystem, s3, gcs, azure.
name	string	yes	-

Responses

Status	Description	Body
201	Storage backend created	application/json: StorageBackend
400	Invalid request	application/json: Error
403	Admin access required	-

GET /api/v1/admin/storage/primary

Get the primary storage

The primary blob store the server is configured with (storage.* settings), with its non-secret location, live status and usage (admin only). The name "primary" is reserved: this static path takes precedence over /admin/storage/{name}.

Responses

Status	Description	Body
200	The primary storage	application/json: StoragePrimary
403	Admin access required	-
404	No primary storage is wired	-

PATCH /api/v1/admin/storage/primary

Update the primary storage (not allowed)

Always answers 405 read_only: the primary storage is set by the server configuration.

Responses

Status	Description	Body
403	Admin access required	-
405	read_only	application/json: Error

DELETE /api/v1/admin/storage/primary

Delete the primary storage (not allowed)

Always answers 405 read_only: the primary storage is set by the server configuration.

Responses

Status	Description	Body
403	Admin access required	-
405	read_only	application/json: Error

POST /api/v1/admin/storage/primary/test

Test the primary storage

Runs a live health check through the store that serves every request and refreshes the cached status (admin only).

Responses

Status	Description	Body
200	Test result	application/json: object
403	Admin access required	-
404	No primary storage is wired	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
error	string	no	-
message	string	no	-
ok	boolean	no	-

GET /api/v1/admin/storage/replication

Blob replication status

Backlog, lag, totals and the last verify pass of the replication to storage.replica (admin only). Reports enabled=false when no replica is configured. This static path takes precedence over /admin/storage/{name}.

Responses

Status	Description	Body
200	Replication status	application/json: ReplicationStatus
403	Admin access required	-

POST /api/v1/admin/storage/replication/verify

Verify the replica now

Requests a verify pass that compares the primary store with the replica and repairs differences in either direction; it runs in the background on the replica holding the verify lock (admin only)

Responses

Status	Description	Body
202	Pass requested	application/json: object
403	Admin access required	-
404	Blob replication is not configured	-
409	A verify pass is already running or requested	-

Fields of the 202 response (application/json):

Field	Type	Required	Description
requested	boolean	no	-

GET /api/v1/admin/storage/{name}

Get storage backend

Get details of a specific storage backend (admin only)

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Responses

Status	Description	Body
200	Storage backend details	application/json: StorageBackend
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Storage backend not found	-

PATCH /api/v1/admin/storage/{name}

Update storage backend

Update a storage backend (admin only). Renaming it to "primary" or "replication" answers 400. The name "primary" answers 405 read_only unless a record of that name still exists from before it was reserved, which this then renames. Changing kind or config is refused with 409 while the backend holds blobs, serves a tier or is named by a tier move

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
config	object	no	-

Responses

Status	Description	Body
200	Storage backend updated	application/json: StorageBackend
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Storage backend not found	-
405	The name is the reserved primary storage, which is set by the server configuration and read-only (error code read_only)	application/json: Error
409	The kind or config cannot change while the backend holds blobs, serves a tier or is named by a tier move	-

DELETE /api/v1/admin/storage/{name}

Delete storage backend

Delete a storage backend (admin only)

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Responses

Status	Description	Body
204	Storage backend deleted	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Storage backend not found	-
405	The name is the reserved primary storage, which is set by the server configuration and read-only (error code read_only)	application/json: Error

POST /api/v1/admin/storage/{name}/test

Test storage backend

Test connection to a storage backend (admin only)

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Responses

Status	Description	Body
200	Test result	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
404	Storage backend not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
error	string	no	-
message	string	no	-
ok	boolean	no	-

POST /api/v1/admin/tiering/dry-run

Simulate storage policies

Reports what a mover pass would move now (counts, bytes, per route and policy, and a sample) without changing anything. With policy set only that draft is simulated; otherwise every enabled policy and promote-on-read are (admin only)

Request body (required)

application/json: object

Field	Type	Required	Description
policy	StoragePolicyInput	no	-
sample_limit	integer	no	Between 0 and 200; default 200.

Responses

Status	Description	Body
200	Simulation result	application/json: TierDryRun
400	Invalid request	-
403	Admin access required	-

GET /api/v1/admin/tiering/policies

List storage policies

Lists lifecycle policies in evaluation order (admin only)

Responses

Status	Description	Body
200	List of policies	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
items	array of StoragePolicy	no	-
total	integer	no	-

POST /api/v1/admin/tiering/policies

Create storage policy

Creates a lifecycle policy; the first enabled policy matching a blob decides its tier (admin only)

Request body (required)

application/json: StoragePolicyInput

Responses

Status	Description	Body
201	Policy created	application/json: StoragePolicy
400	Invalid request	-
403	Admin access required	-
409	Name already used	-

GET /api/v1/admin/tiering/policies/{id}

Get storage policy

Gets a lifecycle policy (admin only)

Parameters

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

Responses

Status	Description	Body
200	Policy	application/json: StoragePolicy
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Admin access required	-
404	Storage policy not found	-

PUT /api/v1/admin/tiering/policies/{id}

Replace storage policy

Replaces every field of a lifecycle policy (admin only)

Parameters

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

Request body (required)

application/json: StoragePolicyInput

Responses

Status	Description	Body
200	Policy updated	application/json: StoragePolicy
400	Invalid request	-
403	Admin access required	-
404	Storage policy not found	-
409	Name already used	-

DELETE /api/v1/admin/tiering/policies/{id}

Delete storage policy

Deletes a lifecycle policy; blobs already moved stay where they are (admin only)

Parameters

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

Responses

Status	Description	Body
204	Policy deleted	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Admin access required	-
404	Storage policy not found	-

POST /api/v1/admin/tiering/run

Run the tier mover now

Queues an immediate mover pass on the replica holding the mover lock (admin only)

Responses

Status	Description	Body
202	Pass requested	application/json: object
403	Admin access required	-
409	The mover is disabled	-

Fields of the 202 response (application/json):

Field	Type	Required	Description
started	boolean	no	False when a pass was already running.

GET /api/v1/admin/tiering/status

Tier mover status

State of the background mover and the moves still in its crash-recovery journal (admin only)

Responses

Status	Description	Body
200	Mover status	application/json: TierMoverStatus
403	Admin access required	-

GET /api/v1/admin/tiering/tiers

List storage tiers

Lists the storage tiers (hottest first) with their placement: blob count and bytes per tier (admin only)

Responses

Status	Description	Body
200	List of tiers	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
items	array of StorageTier	no	-
total	integer	no	-

POST /api/v1/admin/tiering/tiers

Create storage tier

Maps an existing storage backend to a named tier (admin only)

Request body (required)

application/json: object

Field	Type	Required	Description
backend	string	yes	Name of an existing storage backend.
name	string	yes	-
promote_on_read	boolean	no	-
rank	integer	no	Position from hot (low) to cold (high); defaults to after the last tier.

Responses

Status	Description	Body
201	Tier created	application/json: StorageTier
400	Invalid request	-
403	Admin access required	-
409	Name or backend already used by a tier	-

PATCH /api/v1/admin/tiering/tiers/{name}

Update storage tier

Renames a tier or changes its rank or promote-on-read flag (admin only)

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
name	string	no	-
promote_on_read	boolean	no	-
rank	integer	no	-

Responses

Status	Description	Body
200	Tier updated	application/json: StorageTier
400	Invalid request	-
403	Admin access required	-
404	Storage tier not found	-
409	Name already used	-

DELETE /api/v1/admin/tiering/tiers/{name}

Delete storage tier

Deletes a tier that holds no blobs and is not referenced by a policy; the primary tier cannot be deleted (admin only)

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Responses

Status	Description	Body
204	Tier deleted	-
400	The primary tier cannot be deleted	-
403	Admin access required	-
404	Storage tier not found	-
409	Tier still holds blobs, has moves in progress or is used by a policy	-

GET /api/v1/admin/tokens

List all API tokens

List all API tokens across users (admin only)

Parameters

Name	In	Type	Required	Description
page	query	integer	no	Minimum: 1.
per_page	query	integer	no	Minimum: 1. Maximum: 100.

Responses

Status	Description	Body
200	Paginated list of tokens	application/json: object
400	Invalid request	application/json: Error
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of AdminToken	no	-
page	integer	no	-
per_page	integer	no	-
total	integer	no	-

DELETE /api/v1/admin/tokens/{tokenId}

Revoke any API token

Revoke any user's API token (admin only)

Parameters

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

Responses

Status	Description	Body
204	Token revoked	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Token not found	-