Artifacts and catalog
Published artifacts: listing, details, content, annotations, references, search, the catalog audit and its change feed.
Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).
Operations
Get the annotations of an artifact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
Access: Repository permission: annotation.read; file keys: read · Retry: Safe to repeat (read)
Returns the current labels, metadata and collections of a published artifact with their revision. Revision 0 means they were never replaced: labels and metadata are those given when the upload was created, and collections are empty. Pass the revision to setAnnotations as expectedRevision.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
revision | integer | yes | 0–2147483647 |
labels | array of string | yes | up to 32 items |
metadata | map of string | yes | up to 32 entries |
collections | array of string | yes | up to 32 items |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Replace the annotations of an artifact
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
Access: Repository permission: annotation.write, artifact.read; file keys: read, write · Retry: Repeat only with the expected revision (compare-and-swap)
Replaces labels, metadata and collections of a published artifact at once; a field left out of value becomes empty. expectedRevision must be the current revision (0 for the first change), otherwise 409 revision_mismatch: read the annotations again and reapply the change. Up to 32 labels and 32 collections (1–64 letters, digits or _.:-) and 32 metadata entries (values up to 1024 characters); the bytes and the original descriptor never change.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
expectedRevision | integer | yes | 0–2147483646 |
value | object | yes | — |
value.labels | array of string | no | up to 32 items |
value.metadata | map of string | no | up to 32 entries |
value.collections | array of string | no | up to 32 items |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
revision | integer | yes | 0–2147483647 |
labels | array of string | yes | up to 32 items |
metadata | map of string | yes | up to 32 entries |
collections | array of string | yes | up to 32 items |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"value":{}}'Register an artifact as a UPack package
POST /api/v1/repositories/{repository}/artifacts/{id}/package
Access: Repository permission: package.publish, artifact.read; file keys: read, write · Retry: Safe to repeat: the same request has the same effect
Opens the published artifact as a UPack ZIP, reads the root upack.json (name, optional group, SemVer version) and registers that package version for it; unsafe or invalid archives are rejected with 400. A version is immutable: registering the same artifact again returns the same entry, another artifact for an existing group, name and version (compared without case) is a 409 version_exists. Afterwards the version appears in listPackages and resolves by name, range and stage.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
group | string | no | — |
name | string | no | — |
version | string | no | — |
artifactId | string (uuid) | no | — |
manifest | object | no | — |
Responses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Search artifacts
GET HEAD /api/v1/repositories/{repository}/search
Access: Repository permission: artifact.list; file keys: read · Retry: Safe to repeat (read)
Finds published artifacts by q (a case-insensitive substring of the name or of a current metadata value), an exact current label, a collection, and an exact metadataKey/metadataValue pair, which go together; all given filters must match. Results come in pages of 100 ordered by ID, each with size, creation and publication times, current labels and promotion stages; continue with after set to next. Metadata and collections are not returned: read them with getAnnotations.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
q | query | string | no | — |
label | query | string | no | — |
collection | query | string | no | — |
after | query | string | no | — |
metadataKey | query | string | no | matches ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; up to 64 characters; Exact metadata key; requires metadataValue. |
metadataValue | query | string | no | up to 1024 characters; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 100 items |
items[].id | string (uuid) | yes | — |
items[].name | string | yes | — |
items[].size | string | yes | a whole number in decimal digits, sent as a string; Byte size, decimal string |
items[].createdAt | string (date-time) | yes | Upload reservation time |
items[].publishedAt | string (date-time) | yes | may be null; Publication time; null only when none was recorded |
items[].labels | array of string | yes | up to 32 items; Current labels: annotation when replaced, otherwise the upload descriptor |
items[].stages | array of string | yes | up to 16 items; each: matches ^[a-z0-9][a-z0-9_.-]{0,31}$; Current promotion stages in byte order |
next | string (uuid) | yes | may be null; Last ID of a full page; pass as after |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Read the catalog audit of a repository
GET HEAD /api/v1/repositories/{repository}/audit
Access: Repository permission: audit.read; file keys: write · Retry: Safe to repeat (read)
Returns, oldest first, up to 100 catalog changes of the repository after the sequence number after (default 0): publications, deletions, annotation and attachment changes, package registrations, file path changes, references, stages and promotions, each with actor, action, artifact and time. To read further, pass the last sequence of the page as after; there is no next field. Downloads and sign-ins are not in it; mirrors follow listCatalogChanges, which omits actors.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | query | string | no | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | no | — |
items[].sequence | string | no | — |
items[].actor | string | no | — |
items[].action | string | no | — |
items[].artifactId | string | no | — |
items[].occurredAt | string (date-time) | no | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Add a reference to an artifact
POST /api/v1/repositories/{repository}/artifacts/{id}/references
Access: Repository permission: reference.write, artifact.read; file keys: read, write · Retry: Safe to repeat: the same request has the same effect
Records that something outside Arkvory uses this artifact, under a key of your choice (1–256 letters, digits or _.:/-), for example a deployment name. A referenced artifact cannot be deleted or removed by retention until every reference is gone. The reference belongs to the caller; adding the same key again changes nothing.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
key | string | yes | up to 256 characters |
Responses: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'Remove a reference from an artifact
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
Access: Repository permission: reference.write, artifact.read; file keys: read, write · Retry: Safe to repeat: the same request has the same effect
Removes the caller's own reference key from the artifact; references of other callers stay. Removing a key that is not there succeeds as well.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
key | string | yes | up to 256 characters |
Responses: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'List artifacts
GET HEAD /api/v1/repositories/{repository}/artifacts
Access: Repository permission: artifact.list; file keys: read · Retry: Safe to repeat (read)
Lists the published artifacts of the repository ordered by ID, limit per page (1–100, default 50); continue with after set to next. next is set whenever a page is full, so the last page may be empty. Each item carries the descriptor given at upload; current labels and metadata are in getAnnotations.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | query | string (uuid) | no | — |
limit | query | integer | no | 1–100; default 50 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | no | — |
items[].id | string (uuid) | yes | — |
items[].repository | string | yes | — |
items[].status | string | yes | one of pending, available, cancelled |
items[].createdAt | string (date-time) | yes | — |
items[].expiresAt | string (date-time) | yes | — |
items[].descriptor | object | yes | — |
items[].descriptor.name | string | yes | 1–240 characters |
items[].descriptor.size | string | yes | a whole number in decimal digits, sent as a string |
items[].descriptor.sha256 | string | yes | SHA-256: 64 lowercase hexadecimal digits |
items[].descriptor.labels | array of string | no | up to 32 items; each: up to 64 characters |
items[].descriptor.metadata | map of string | no | up to 32 entries |
next | string | no | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Get an artifact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
Access: Repository permission: artifact.read; file keys: read · Retry: Safe to repeat (read)
Returns a published artifact: its ID, repository, status, creation time and the descriptor given at upload (name, size, SHA-256, original labels and metadata). Pending, cancelled and deleted artifacts answer 404. To read the bytes use downloadArtifact.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | yes | — |
repository | string | yes | — |
status | string | yes | one of pending, available, cancelled |
createdAt | string (date-time) | yes | — |
expiresAt | string (date-time) | yes | — |
descriptor | object | yes | — |
descriptor.name | string | yes | 1–240 characters |
descriptor.size | string | yes | a whole number in decimal digits, sent as a string |
descriptor.sha256 | string | yes | SHA-256: 64 lowercase hexadecimal digits |
descriptor.labels | array of string | no | up to 32 items; each: up to 64 characters |
descriptor.metadata | map of string | no | up to 32 entries |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Delete an artifact
DELETE /api/v1/repositories/{repository}/artifacts/{id}
Access: Repository permission: artifact.delete · Retry: Safe to repeat: the same request has the same effect
Logically deletes a published artifact: it disappears from lists, searches and downloads at once, and its bytes are reclaimed by the repository's online cleanup (setCleanup, off by default) after its grace period. expectedAnnotationRevision must equal the current annotation revision. The answer is 200 with an outcome: deleted, already_deleted, changed (the revision differs), not_found, or protected with the blockers that keep it (a reference, a file path revision, a build attachment or a promotion stage). Check beforehand with inspectArtifactDeletion.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
expectedAnnotationRevision | integer | yes | 0–2147483647 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | yes | — |
outcome | string | yes | one of deleted, already_deleted, protected, changed, not_eligible, not_found |
blockers | array of string | yes | up to 4 items; no repeated items; each: one of reference, asset_history, attachment_history, protected_label, promotion_stage |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'Download an artifact
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
Access: Repository permission: content.read; file keys: read · Retry: Safe to repeat (read)
Streams the original bytes with Content-Length, Content-Disposition (the artifact name) and a strong ETag ("sha256:<hex>"). A single Range gives 206 (an unsatisfiable one 416); If-Range with the ETag resumes safely, and If-None-Match answers 304. HEAD returns the same headers without a body and ignores Range. Instead of an Authorization header the request may carry a download link from createDownloadLink as token; downloads wait for a free slot of the server's download admission.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Range | header | string | no | — |
If-Range | header | string | no | — |
If-None-Match | header | string | no | — |
Arkvory-Download-Id | header | string | no | matches ^[A-Za-z0-9_-]{16,64}$; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time. |
Arkvory-Queue-Ticket | header | string | no | up to 80 characters; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored. |
Arkvory-Download-Class | header | string | no | one of interactive, release, bulk, background; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied. |
token | query | string | no | matches ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
Responses: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileRead the fleet overview
GET HEAD /api/v1/fleet/overview
Access: Administrator · Retry: Safe to repeat (read)
Alerts across the managed sites and this installation, most severe first (critical, warning, info), and the mirror links between them. Built from the last background reads, at most once per 5 seconds. A source no managed site answers at is external:<origin>; this installation is self and meets the links to it only when ARKVORY_SITE_URL is set. Answered by the writer only.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
generatedAt | string (date-time) | yes | — |
self | object | yes | — |
self.name | string | yes | — |
self.version | string | yes | — |
self.url | string | yes | may be null |
alerts | array of object | yes | — |
alerts[].site | string | yes | — |
alerts[].name | string | yes | — |
alerts[].kind | string | yes | one of unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew |
alerts[].severity | string | yes | one of critical, warning, info |
alerts[].subject | string | yes | may be null |
alerts[].since | string (date-time) | yes | may be null |
links | array of object | yes | — |
links[].from | string | yes | — |
links[].to | string | yes | — |
links[].repository | string | yes | — |
links[].sourceRepository | string | yes | — |
links[].mode | string | yes | one of mirror, import |
links[].lagChanges | string | yes | a whole number in decimal digits, sent as a string; may be null |
links[].failing | boolean | yes | — |
links[].stale | boolean | no | — |
external | array of string | yes | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"List the managed sites
GET HEAD /api/v1/fleet/sites
Access: Administrator · Retry: Safe to repeat (read)
Lists the sites this installation manages (ADR 0077) with what each last reported: state (ok, or why it was not read: unreachable, certificate, revoked, invalid, refused), when it was last seen, and its last topology. Sites are read every 30 seconds in the background. A site key is never returned.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 256 items |
items[].id | string (uuid) | yes | — |
items[].name | string | yes | — |
items[].url | string | yes | — |
items[].fingerprint | string | yes | matches ^[0-9a-f]{64}$; may be null |
items[].addedBy | string | yes | — |
items[].addedAt | string (date-time) | yes | — |
items[].seenAt | string (date-time) | yes | may be null |
items[].state | string | yes | one of pending, ok, unreachable, certificate, revoked, invalid, refused |
items[].error | string | yes | may be null |
items[].topology | object | yes | may be null |
items[].topology.collectedAt | string (date-time) | yes | — |
items[].topology.site | object | yes | — |
items[].topology.health | object | yes | — |
items[].topology.replication | object | yes | may be null |
items[].topology.gateways | array of object | yes | up to 16 items |
items[].topology.mirrors | array of object | yes | up to 64 items |
items[].topology.updates | object | yes | may be null |
items[].topology.downloads | object | yes | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Pair with a site
POST /api/v1/fleet/sites
Access: Administrator · Retry: Do not repeat automatically
Pairs with a site: the controller connects again, the certificate must still have the fingerprint the administrator confirmed (null for HTTP on loopback), the pairing code made on the site is traded for a key, and the key is sealed with ARKVORY_FLEET_KEY_FILE. The site is read once before the answer. Without the key file the answer is 503.
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
url | string | yes | — |
fingerprint | string | yes | matches ^[0-9a-f]{64}$; may be null |
code | string | yes | up to 32 characters |
Response 201
| Field | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | yes | — |
name | string | yes | — |
url | string | yes | — |
fingerprint | string | yes | matches ^[0-9a-f]{64}$; may be null |
addedBy | string | yes | — |
addedAt | string (date-time) | yes | — |
seenAt | string (date-time) | yes | may be null |
state | string | yes | one of pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | yes | may be null |
topology | object | yes | may be null |
topology.collectedAt | string (date-time) | yes | — |
topology.site | object | yes | — |
topology.site.name | string | yes | — |
topology.site.version | string | yes | — |
topology.site.schema | integer | yes | at least 0 |
topology.site.role | string | yes | one of api, reader |
topology.health | object | yes | — |
topology.health.available | boolean | yes | — |
topology.health.writable | boolean | yes | — |
topology.health.draining | boolean | yes | — |
topology.replication | object | yes | may be null |
topology.replication.copies | integer | yes | 0–16 |
topology.replication.required | integer | yes | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | yes | may be null |
topology.replication.node | string | no | up to 63 characters |
topology.replication.profile | string | no | one of ha-2, ha-3 |
topology.replication.peers | array of object | no | up to 16 items |
topology.gateways | array of object | yes | up to 16 items |
topology.gateways[].slot | integer | yes | at least 0 |
topology.gateways[].active | boolean | yes | — |
topology.gateways[].expiresAt | string (date-time) | yes | — |
topology.mirrors | array of object | yes | up to 64 items |
topology.mirrors[].repository | string | yes | — |
topology.mirrors[].mode | string | yes | one of mirror, import |
topology.mirrors[].upstream | string | yes | — |
topology.mirrors[].sourceRepository | string | yes | — |
topology.mirrors[].phase | string | yes | — |
topology.mirrors[].errorCode | string | yes | may be null |
topology.mirrors[].checkedAt | string (date-time) | yes | may be null |
topology.mirrors[].syncedAt | string (date-time) | yes | may be null |
topology.mirrors[].lagChanges | string | yes | a whole number in decimal digits, sent as a string; may be null |
topology.mirrors[].copiedArtifacts | integer | yes | at least 0 |
topology.mirrors[].copiedBytes | string | yes | a whole number in decimal digits, sent as a string |
topology.updates | object | yes | may be null |
topology.updates.currentVersion | string | yes | — |
topology.updates.latest | string | yes | may be null |
topology.updates.phase | string | yes | — |
topology.updates.error | string | yes | may be null |
topology.updates.automatic | boolean | yes | — |
topology.updates.heartbeatAt | string (date-time) | yes | — |
topology.downloads | object | yes | — |
topology.downloads.strategy | string | yes | one of ordered, smallest-first, shared |
topology.downloads.sessions | integer | yes | at least 0 |
topology.downloads.active | integer | yes | at least 0 |
topology.downloads.waiting | integer | yes | at least 0 |
topology.downloads.oldestWaitSeconds | integer | yes | at least 0 |
topology.downloads.bytesPerSecond | integer | yes | at least 0 |
Responses: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>","fingerprint":"<fingerprint>","code":"<code>"}'Read the certificate of a site
POST /api/v1/fleet/sites/probe
Access: Administrator · Retry: Safe to repeat: the same request has the same effect
Connects to the address and reads the certificate the site presents, without sending anything: compare its fingerprint with the one the site's administrator sees before you pair.
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
url | string | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
url | string | yes | — |
certificate | object | yes | may be null |
certificate.fingerprint | string | yes | matches ^[0-9a-f]{64}$ |
certificate.subject | string | yes | — |
certificate.issuer | string | yes | — |
certificate.validTo | string (date-time) | yes | — |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'Forget a site
DELETE /api/v1/fleet/sites/{id}
Access: Administrator · Retry: Safe to repeat: the same request has the same effect
Forgets a site and its sealed key here. Revoke this controller on the site as well; until then the key stays valid there.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Responses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Read the catalog of a site
GET HEAD /api/v1/fleet/sites/{id}/read
Access: Administrator · Retry: Safe to repeat (read)
Passes one catalog read to a managed site and returns its answer unchanged: repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state. path is the site route with its query. Other routes and file bytes are refused with 400.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
path | query | string | yes | matches ^/api/v1/; up to 2048 characters; A read route of the site with its query, from a fixed list: catalog metadata (repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state), download queue settings and update state. Never file bytes. |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Change a setting of a site
POST /api/v1/fleet/sites/{id}/change
Access: Administrator · Retry: Do not repeat automatically
Passes one change to a managed site and returns its answer unchanged. path is one of: /api/v1/system/downloads/settings (download queue settings, sent as PUT) or /api/v1/system/updates/requests (an update request, sent as POST). The body goes to the site as it is; the site checks the revision or request id, so a repeated change does not apply twice. Other paths are refused with 400.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
path | query | string | yes | matches ^/api/v1/; up to 2048 characters; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
Request body (application/json)
Responses: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Read a site now
POST /api/v1/fleet/sites/{id}/refresh
Access: Administrator · Retry: Safe to repeat: the same request has the same effect
Reads the site now instead of waiting for the next round and returns it with the new state.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | yes | — |
name | string | yes | — |
url | string | yes | — |
fingerprint | string | yes | matches ^[0-9a-f]{64}$; may be null |
addedBy | string | yes | — |
addedAt | string (date-time) | yes | — |
seenAt | string (date-time) | yes | may be null |
state | string | yes | one of pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | yes | may be null |
topology | object | yes | may be null |
topology.collectedAt | string (date-time) | yes | — |
topology.site | object | yes | — |
topology.site.name | string | yes | — |
topology.site.version | string | yes | — |
topology.site.schema | integer | yes | at least 0 |
topology.site.role | string | yes | one of api, reader |
topology.health | object | yes | — |
topology.health.available | boolean | yes | — |
topology.health.writable | boolean | yes | — |
topology.health.draining | boolean | yes | — |
topology.replication | object | yes | may be null |
topology.replication.copies | integer | yes | 0–16 |
topology.replication.required | integer | yes | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | yes | may be null |
topology.replication.node | string | no | up to 63 characters |
topology.replication.profile | string | no | one of ha-2, ha-3 |
topology.replication.peers | array of object | no | up to 16 items |
topology.gateways | array of object | yes | up to 16 items |
topology.gateways[].slot | integer | yes | at least 0 |
topology.gateways[].active | boolean | yes | — |
topology.gateways[].expiresAt | string (date-time) | yes | — |
topology.mirrors | array of object | yes | up to 64 items |
topology.mirrors[].repository | string | yes | — |
topology.mirrors[].mode | string | yes | one of mirror, import |
topology.mirrors[].upstream | string | yes | — |
topology.mirrors[].sourceRepository | string | yes | — |
topology.mirrors[].phase | string | yes | — |
topology.mirrors[].errorCode | string | yes | may be null |
topology.mirrors[].checkedAt | string (date-time) | yes | may be null |
topology.mirrors[].syncedAt | string (date-time) | yes | may be null |
topology.mirrors[].lagChanges | string | yes | a whole number in decimal digits, sent as a string; may be null |
topology.mirrors[].copiedArtifacts | integer | yes | at least 0 |
topology.mirrors[].copiedBytes | string | yes | a whole number in decimal digits, sent as a string |
topology.updates | object | yes | may be null |
topology.updates.currentVersion | string | yes | — |
topology.updates.latest | string | yes | may be null |
topology.updates.phase | string | yes | — |
topology.updates.error | string | yes | may be null |
topology.updates.automatic | boolean | yes | — |
topology.updates.heartbeatAt | string (date-time) | yes | — |
topology.downloads | object | yes | — |
topology.downloads.strategy | string | yes | one of ordered, smallest-first, shared |
topology.downloads.sessions | integer | yes | at least 0 |
topology.downloads.active | integer | yes | at least 0 |
topology.downloads.waiting | integer | yes | at least 0 |
topology.downloads.oldestWaitSeconds | integer | yes | at least 0 |
topology.downloads.bytesPerSecond | integer | yes | at least 0 |
Responses: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Make a pairing code
POST /api/v1/system/fleet/pairings
Access: Administrator · Retry: Do not repeat automatically
Makes a one-time code, valid ten minutes, that the administrator of a controller types in to manage this site. The code is shown once; it is stored only as a hash. Only the global administrator of the site may make one.
Response 201
| Field | Type | Required | Rules |
|---|---|---|---|
code | string | yes | matches ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$ |
expiresAt | string (date-time) | yes | — |
fingerprint | string | yes | matches ^[0-9a-f]{64}$; may be null |
Responses: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"List the controllers of this site
GET HEAD /api/v1/system/fleet/controllers
Access: Administrator · Retry: Safe to repeat (read)
Lists the controllers that may manage this site: their name, who paired them, when, and when their key was last used.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 100 items |
items[].id | string (uuid) | yes | — |
items[].name | string | yes | — |
items[].pairedBy | string | yes | — |
items[].pairedAt | string (date-time) | yes | — |
items[].usedAt | string (date-time) | yes | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Revoke a controller
DELETE /api/v1/system/fleet/controllers/{id}
Access: Administrator · Retry: Safe to repeat: the same request has the same effect
Revokes a controller: its fleet key is refused at once. To manage the site again it must pair with a new code.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
id | path | string (uuid) | yes | — |
Responses: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Pair with a controller
POST /api/v1/system/fleet/enrollment
Access: Anyone, without a key · Retry: Do not repeat automatically
Trades a live pairing code for a fleet key, once. The controller calls it over TLS it has pinned to the fingerprint the administrator confirmed. The key is returned once and reaches only the routes a controller needs.
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
code | string | yes | up to 32 characters |
name | string | yes | 1–63 characters |
Response 201
| Field | Type | Required | Rules |
|---|---|---|---|
key | string | yes | matches ^afk_[A-Za-z0-9_-]{43}$ |
site | object | yes | — |
site.name | string | yes | — |
site.version | string | yes | — |
Responses: 201, 400, 403, 405, 413, 415, 503
Example
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'Get this site for the fleet console
GET HEAD /api/v1/system/topology
Access: Administrator · Retry: Safe to repeat (read)
Returns this installation as one site of a fleet (ADR 0077): its name, version, schema and role, whether it is available and writable, the HA copies and nodes, the read gateways from their leases, every mirror and import with its phase, last sync and lagChanges (changes of the source not applied yet), the host updater state and the download queue. Only the global administrator of the site or a controller paired with it may read it.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
collectedAt | string (date-time) | yes | — |
site | object | yes | — |
site.name | string | yes | — |
site.version | string | yes | — |
site.schema | integer | yes | at least 0 |
site.role | string | yes | one of api, reader |
health | object | yes | — |
health.available | boolean | yes | — |
health.writable | boolean | yes | — |
health.draining | boolean | yes | — |
replication | object | yes | may be null |
replication.copies | integer | yes | 0–16 |
replication.required | integer | yes | 1–16 |
replication.singleCopyUntil | string (date-time) | yes | may be null |
replication.node | string | no | up to 63 characters |
replication.profile | string | no | one of ha-2, ha-3 |
replication.peers | array of object | no | up to 16 items |
replication.peers[].name | string | yes | up to 63 characters |
replication.peers[].connected | boolean | yes | — |
replication.peers[].disk | string | yes | up to 24 characters |
replication.peers[].complete | boolean | yes | — |
replication.peers[].witness | boolean | yes | — |
gateways | array of object | yes | up to 16 items |
gateways[].slot | integer | yes | at least 0 |
gateways[].active | boolean | yes | — |
gateways[].expiresAt | string (date-time) | yes | — |
mirrors | array of object | yes | up to 64 items |
mirrors[].repository | string | yes | — |
mirrors[].mode | string | yes | one of mirror, import |
mirrors[].upstream | string | yes | — |
mirrors[].sourceRepository | string | yes | — |
mirrors[].phase | string | yes | — |
mirrors[].errorCode | string | yes | may be null |
mirrors[].checkedAt | string (date-time) | yes | may be null |
mirrors[].syncedAt | string (date-time) | yes | may be null |
mirrors[].lagChanges | string | yes | a whole number in decimal digits, sent as a string; may be null |
mirrors[].copiedArtifacts | integer | yes | at least 0 |
mirrors[].copiedBytes | string | yes | a whole number in decimal digits, sent as a string |
updates | object | yes | may be null |
updates.currentVersion | string | yes | — |
updates.latest | string | yes | may be null |
updates.phase | string | yes | — |
updates.error | string | yes | may be null |
updates.automatic | boolean | yes | — |
updates.heartbeatAt | string (date-time) | yes | — |
downloads | object | yes | — |
downloads.strategy | string | yes | one of ordered, smallest-first, shared |
downloads.sessions | integer | yes | at least 0 |
downloads.active | integer | yes | at least 0 |
downloads.waiting | integer | yes | at least 0 |
downloads.oldestWaitSeconds | integer | yes | at least 0 |
downloads.bytesPerSecond | integer | yes | at least 0 |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Read download queue settings
GET HEAD /api/v1/system/downloads/settings
Access: Administrator · Retry: Safe to repeat (read)
Returns the changed values (overrides), what the environment of the server sets (defaults) and what the queue uses now (effective), with the revision to pass back when changing. problem names why saved settings do not fit this server; the queue then runs on the defaults.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
revision | integer | yes | 0–9007199254740991 |
overrides | object | yes | — |
overrides.strategy | string | no | one of ordered, smallest-first, shared |
overrides.sessions | integer | no | 1–1024 |
overrides.reserve | integer | no | 0–1023 |
overrides.perPrincipal | integer | no | 1–1024 |
overrides.weights | object | no | — |
overrides.weights.interactive | integer | yes | 1–1000 |
overrides.weights.release | integer | yes | 1–1000 |
overrides.weights.bulk | integer | yes | 1–1000 |
overrides.weights.background | integer | yes | 1–1000 |
overrides.sessionMinBytes | integer | no | 0–9007199254740991 |
overrides.idleSeconds | integer | no | 1–3600 |
overrides.agingMinutes | integer | no | 0–10080 |
overrides.preempt | boolean | no | — |
overrides.rangesPerSession | integer | no | 1–64 |
defaults | object | yes | — |
defaults.strategy | string | yes | one of ordered, smallest-first, shared |
defaults.sessions | integer | yes | 1–1024 |
defaults.reserve | integer | yes | 0–1023 |
defaults.perPrincipal | integer | yes | 1–1024 |
defaults.weights | object | yes | — |
defaults.weights.interactive | integer | yes | 1–1000 |
defaults.weights.release | integer | yes | 1–1000 |
defaults.weights.bulk | integer | yes | 1–1000 |
defaults.weights.background | integer | yes | 1–1000 |
defaults.sessionMinBytes | integer | yes | 0–9007199254740991 |
defaults.idleSeconds | integer | yes | 1–3600 |
defaults.agingMinutes | integer | yes | 0–10080 |
defaults.preempt | boolean | yes | — |
defaults.rangesPerSession | integer | yes | 1–64 |
effective | object | yes | — |
effective.strategy | string | yes | one of ordered, smallest-first, shared |
effective.sessions | integer | yes | 1–1024 |
effective.reserve | integer | yes | 0–1023 |
effective.perPrincipal | integer | yes | 1–1024 |
effective.weights | object | yes | — |
effective.weights.interactive | integer | yes | 1–1000 |
effective.weights.release | integer | yes | 1–1000 |
effective.weights.bulk | integer | yes | 1–1000 |
effective.weights.background | integer | yes | 1–1000 |
effective.sessionMinBytes | integer | yes | 0–9007199254740991 |
effective.idleSeconds | integer | yes | 1–3600 |
effective.agingMinutes | integer | yes | 0–10080 |
effective.preempt | boolean | yes | — |
effective.rangesPerSession | integer | yes | 1–64 |
admission | string | yes | one of sessions, per-request |
updatedAt | string (date-time) | yes | may be null |
updatedBy | string | yes | may be null |
actor | string | yes | may be null |
problem | string | yes | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Change download queue settings
PUT /api/v1/system/downloads/settings
Access: Administrator · Retry: Repeat only with the expected revision (compare-and-swap)
Saves overrides over the environment of the server and applies them without a restart: new decisions follow them at once, active downloads keep their places. The values given replace all earlier changes; {} returns to the environment. Settings that cannot run here are refused with 400 naming the field; a stale expectedRevision gets 409. Read gateways keep their environment.
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
expectedRevision | integer | yes | 0–9007199254740991 |
overrides | object | yes | — |
overrides.strategy | string | no | one of ordered, smallest-first, shared |
overrides.sessions | integer | no | 1–1024 |
overrides.reserve | integer | no | 0–1023 |
overrides.perPrincipal | integer | no | 1–1024 |
overrides.weights | object | no | — |
overrides.weights.interactive | integer | yes | 1–1000 |
overrides.weights.release | integer | yes | 1–1000 |
overrides.weights.bulk | integer | yes | 1–1000 |
overrides.weights.background | integer | yes | 1–1000 |
overrides.sessionMinBytes | integer | no | 0–9007199254740991 |
overrides.idleSeconds | integer | no | 1–3600 |
overrides.agingMinutes | integer | no | 0–10080 |
overrides.preempt | boolean | no | — |
overrides.rangesPerSession | integer | no | 1–64 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
revision | integer | yes | 0–9007199254740991 |
overrides | object | yes | — |
overrides.strategy | string | no | one of ordered, smallest-first, shared |
overrides.sessions | integer | no | 1–1024 |
overrides.reserve | integer | no | 0–1023 |
overrides.perPrincipal | integer | no | 1–1024 |
overrides.weights | object | no | — |
overrides.weights.interactive | integer | yes | 1–1000 |
overrides.weights.release | integer | yes | 1–1000 |
overrides.weights.bulk | integer | yes | 1–1000 |
overrides.weights.background | integer | yes | 1–1000 |
overrides.sessionMinBytes | integer | no | 0–9007199254740991 |
overrides.idleSeconds | integer | no | 1–3600 |
overrides.agingMinutes | integer | no | 0–10080 |
overrides.preempt | boolean | no | — |
overrides.rangesPerSession | integer | no | 1–64 |
defaults | object | yes | — |
defaults.strategy | string | yes | one of ordered, smallest-first, shared |
defaults.sessions | integer | yes | 1–1024 |
defaults.reserve | integer | yes | 0–1023 |
defaults.perPrincipal | integer | yes | 1–1024 |
defaults.weights | object | yes | — |
defaults.weights.interactive | integer | yes | 1–1000 |
defaults.weights.release | integer | yes | 1–1000 |
defaults.weights.bulk | integer | yes | 1–1000 |
defaults.weights.background | integer | yes | 1–1000 |
defaults.sessionMinBytes | integer | yes | 0–9007199254740991 |
defaults.idleSeconds | integer | yes | 1–3600 |
defaults.agingMinutes | integer | yes | 0–10080 |
defaults.preempt | boolean | yes | — |
defaults.rangesPerSession | integer | yes | 1–64 |
effective | object | yes | — |
effective.strategy | string | yes | one of ordered, smallest-first, shared |
effective.sessions | integer | yes | 1–1024 |
effective.reserve | integer | yes | 0–1023 |
effective.perPrincipal | integer | yes | 1–1024 |
effective.weights | object | yes | — |
effective.weights.interactive | integer | yes | 1–1000 |
effective.weights.release | integer | yes | 1–1000 |
effective.weights.bulk | integer | yes | 1–1000 |
effective.weights.background | integer | yes | 1–1000 |
effective.sessionMinBytes | integer | yes | 0–9007199254740991 |
effective.idleSeconds | integer | yes | 1–3600 |
effective.agingMinutes | integer | yes | 0–10080 |
effective.preempt | boolean | yes | — |
effective.rangesPerSession | integer | yes | 1–64 |
admission | string | yes | one of sessions, per-request |
updatedAt | string (date-time) | yes | may be null |
updatedBy | string | yes | may be null |
actor | string | yes | may be null |
problem | string | yes | may be null |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'Read site changes
GET HEAD /api/v1/system/changes
Access: Administrator · Retry: Safe to repeat (read)
Returns whether the site’s agent reports in (agent), the pending request and the 20 newest with their state: pending, applying, done or failed with a reason. Source keys never appear here.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
agent | boolean | yes | — |
updating | boolean | yes | — |
blocked | string | yes | one of expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; may be null |
pending | object | yes | may be null |
pending.id | string (uuid) | yes | — |
pending.kind | string | yes | one of mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
pending.actor | string | yes | up to 200 characters |
pending.requestedAt | string (date-time) | yes | — |
recent | array of object | yes | up to 20 items |
recent[].id | string (uuid) | yes | — |
recent[].digest | string | yes | matches ^[0-9a-f]{64}$ |
recent[].kind | string | yes | one of mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
recent[].state | string | yes | one of pending, applying, done, failed |
recent[].error | string | yes | one of expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; may be null |
recent[].actor | string | yes | up to 200 characters |
recent[].requestedAt | string (date-time) | yes | — |
recent[].finishedAt | string (date-time) | yes | may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Queue a site change
POST /api/v1/system/changes
Access: Administrator · Retry: Safe to repeat: the same request has the same effect
Queues one change for the site’s agent, which applies it within a minute with the checks and rollback of arkvory configure and cluster-*: attach a mirror or an import, replace its source key, detach mirrors, switch the active HA node (the node name typed twice) or decide single-copy writes. id is chosen by the client; repeating it does not queue the change again. key is the source key of mirror-attach and mirror-key only: it goes to the agent in its own 0600 file and is never returned. 202 means queued, not applied.
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | yes | — |
change | object | yes | — |
change.kind | string | yes | one of mirror-attach |
change.repository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.upstream | string | yes | up to 255 characters |
change.sourceRepository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.stages | array of string | no | 1–16 items; each: matches ^[a-z0-9][a-z0-9_.-]{0,31}$; may be null |
change.repositories | array of string | yes | 1–64 items; each: matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.node | string | yes | matches ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.confirm | string | yes | matches ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.until | string (date-time) | yes | may be null |
change.reason | string | yes | 1–200 characters |
key | string | no | 16–4000 characters |
Response 202
| Field | Type | Required | Rules |
|---|---|---|---|
id | string (uuid) | yes | — |
Responses: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"00000000-0000-4000-8000-000000000000","change":{"kind":"mirror-attach","repository":"<repository>","upstream":"<upstream>","sourceRepository":"<sourceRepository>"}}'Follow the change feed of a repository
GET HEAD /api/v1/repositories/{repository}/changes
Access: Repository permission: artifact.list; file keys: read · Retry: Safe to repeat (read)
Returns, in commit order, up to limit changes (1–100, default 100) after the sequence after (default 0): action, artifact and, for file paths and stages, the path or stage in detail; actors are left out, so list access is enough. head is the newest sequence of the repository, next the cursor of the following page or null when the page reached the head. A mirror stores the last sequence it applied and polls from there.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | query | string | no | a whole number in decimal digits, sent as a string; Sequence cursor, default 0 |
limit | query | integer | no | 1–100 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | — |
items[].sequence | string | yes | a whole number in decimal digits, sent as a string |
items[].action | string | yes | — |
items[].artifactId | string (uuid) | yes | — |
items[].detail | string | yes | may be null |
head | string | yes | a whole number in decimal digits, sent as a string |
next | string | yes | a whole number in decimal digits, sent as a string; may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Create a download link
POST /api/v1/repositories/{repository}/artifacts/{id}/links
Access: Repository permission: content.read; file keys: read · Retry: Do not repeat automatically
Returns a secret token, a url relative to the API origin and expiresAt for downloadArtifact of this one artifact without a key; ttlSeconds sets the lifetime (60 seconds to one day, default one hour). The token is shown only in this answer and cannot be revoked: it stops working when it expires or the artifact is deleted, and downloads through it count against the creator's transfer limits. A caller may hold 1000 live links (507 token_limit), and a download link cannot create further links.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | path | string (uuid) | yes | — |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
ttlSeconds | integer | no | 60–86400; default 3600 |
Response 201
| Field | Type | Required | Rules |
|---|---|---|---|
token | string | yes | matches ^dtl_[A-Za-z0-9_-]{43}$ |
url | string | yes | — |
expiresAt | string (date-time) | yes | — |
Responses: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'