System and health
Liveness, readiness, metrics, the OpenAPI document and the server's capabilities.
Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).
Operations
Check detailed readiness
GET HEAD /health/ready
Access: Any valid key or session · Retry: Safe to repeat (read)
Answers ready when the database and storage respond, with this node's role (api or reader), whether it accepts writes now (writable is false on a read gateway and while the disk keeps its free-space reserve), the shared download slot of a read gateway and aggregate upload and download admission and bandwidth counters. While the server drains or a dependency is unavailable it answers 503 with Retry-After. It does not count against the request budget; for a load balancer without a key use getReadinessStatus.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
role | string | yes | one of api, reader |
sharedDownloads | object | yes | may be null |
sharedDownloads.slot | integer | yes | at least 0 |
sharedDownloads.slots | integer | yes | at least 0 |
sharedDownloads.active | boolean | yes | — |
sharedDownloads.leaseSeconds | integer | yes | at least 0 |
status | string | yes | one of ready |
writable | boolean | yes | — |
replication | object | no | 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 | — |
transfers | object | yes | — |
transfers.uploads | object | yes | — |
transfers.uploads.admission | object | yes | — |
transfers.uploads.bandwidth | object | yes | — |
transfers.uploads.sessions | object | no | — |
transfers.downloads | object | yes | — |
transfers.downloads.admission | object | yes | — |
transfers.downloads.bandwidth | object | yes | — |
transfers.downloads.sessions | object | no | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/health/ready" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Get server capabilities and limits
GET HEAD /api/v1/capabilities
Access: Any valid key or session · Retry: Safe to repeat (read)
Returns the API versions, the gateway role, feature flags (for example selfRegistration or mirrorFeed) and the limits a client adapts to: the largest object (maxObjectBytes, a decimal string), the smallest and largest multipart segment, the largest number of parts and the largest page size. Read it once when a client starts; it lists no resources.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
apiVersions | array of string | yes | — |
gatewayRole | string | yes | one of api, reader |
features | map of boolean | yes | — |
limits | object | yes | — |
limits.maxObjectBytes | string | no | a whole number in decimal digits, sent as a string |
limits.partBytes | integer | no | Smallest multipart segment. |
limits.maxPartBytes | integer | no | — |
limits.maxParts | integer | no | — |
limits.maxPageSize | integer | no | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Check readiness for a load balancer
GET HEAD /health/status
Access: Anyone, without a key · Retry: Safe to repeat (read)
Needs no key and returns no details: 200 with {"status":"ready"}, or 503 with unavailable or draining and Retry-After. The dependency check is shared and cached for one second, so frequent probes do not load the database, and the probe does not count against the request budget.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
status | string | yes | one of ready, unavailable, draining |
Responses: 200, 400, 403, 503
Example
curl -X GET "$ARKVORY_URL/health/status"Check that the process is alive
GET HEAD /health/live
Access: Anyone, without a key · Retry: Safe to repeat (read)
Returns 200 with {"status":"ok"} while the process answers HTTP. It checks no dependency, so use it to decide on a restart and getReadinessStatus to decide on traffic.
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
status | string | yes | one of ok |
Responses: 200, 400, 403, 503
Example
curl -X GET "$ARKVORY_URL/health/live"Get the OpenAPI document
GET HEAD /api/v1/openapi.json
Access: Any valid key or session · Retry: Safe to repeat (read)
Returns the OpenAPI 3.0 document of this deployment, with the x-arkvory-* extensions that describe each operation's access, retry and gateway rules. surface (discovery, identity, catalog, transfers, administration or operations) returns only that area; an unknown or repeated query parameter is a 400. The document is the same for every caller and grants nothing: to learn what this credential may call, use listVisibleOperations.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
surface | query | string | no | one of discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions. |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
openapi | string | yes | one of 3.0.3 |
info | object | yes | — |
paths | object | yes | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Get Prometheus metrics
GET HEAD /health/metrics
Access: Any valid key or session · Retry: Safe to repeat (read)
Returns the process metrics in the Prometheus text format (text/plain; version=0.0.4) for a scraper. Counters and histograms belong to this process and start from zero after a restart (see arkvory_process_start_time_seconds); labels are limited to route template, method, status class and transfer direction and never name an artifact, key or account. The scrape does not count against the request budget.
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/health/metrics" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileList the operations this credential may call
GET HEAD /api/v1/operations
Access: Any valid key or session · Retry: Safe to repeat (read)
Lists the operations of this gateway the credential may call, ordered by operationId, each with its surface, retry rule, required actions and the conditions checked only at call time (such as resource-state or upload-owner). repository adds the operations of that repository (an unknown or foreign repository is a 404), surface narrows the list to one area; pages hold limit items (1–100, default 50), continue with after set to next. The answer is advisory: build menus from it, but every real request is authorized again, and a read gateway lists no changing methods.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | query | string | no | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
surface | query | string | no | one of discovery, identity, catalog, transfers, administration, operations |
after | query | string | no | matches ^[A-Za-z][A-Za-z0-9]{0,95}$ |
limit | query | integer | no | 1–100; default 50 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
apiVersion | string | yes | one of v1 |
documentVersion | string | yes | matches ^\d+\.\d+\.\d+$ |
gatewayRole | string | yes | one of api, reader |
repository | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$; may be null |
advisory | boolean | yes | one of true |
items | array of object | yes | up to 100 items |
items[].operationId | string | yes | matches ^[A-Za-z][A-Za-z0-9]{0,95}$ |
items[].method | string | yes | one of get, head, post, put, patch, delete |
items[].path | string | yes | matches ^/; up to 512 characters |
items[].summary | string | yes | up to 1024 characters |
items[].surface | string | yes | one of discovery, identity, catalog, transfers, administration, operations |
items[].visibility | string | yes | one of public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator |
items[].retry | string | yes | one of read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job |
items[].requiredActions | array of string | yes | up to 33 items; no repeated items; each: one of repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage |
items[].conditions | array of string | yes | up to 6 items; no repeated items; each: one of resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key |
next | string | yes | matches ^[A-Za-z][A-Za-z0-9]{0,95}$; may be null |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/operations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"