Files by path
Files addressed by a path in the repository: revisions, history, restore, and raw files in one request.
Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).
Operations
List file paths by prefix
GET HEAD /api/v1/repositories/{repository}/assets
Access: Repository permission: asset.read; file keys: read · Retry: Safe to repeat (read)
Returns every file path that starts with prefix (literal, not a pattern; empty for all), ordered by path, each with its current revision and artifact ID. There is no paging: more than 1000 matches is a 400 asking for a narrower prefix, so prefer listAssetPage for large trees.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
prefix | query | string | no | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | no | — |
items[].path | string | yes | — |
items[].revision | integer | yes | 1–2147483647 |
items[].artifactId | string (uuid) | yes | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets" \
-H "Authorization: Bearer $ARKVORY_TOKEN"List file paths page by page
GET HEAD /api/v1/repositories/{repository}/assets/page
Access: Repository permission: asset.read; file keys: read · Retry: Safe to repeat (read)
Returns the current file paths that start with prefix (literal; empty for all) in UTF-8 byte order, each with its current revision and artifact ID. Pages hold limit items (1–100, default 50); continue with after set to the opaque next. Pages are not a snapshot: paths changed between requests can appear with their newer revision or be missed until the next pass.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
prefix | query | string | no | up to 1024 characters; default ``; Case-sensitive literal prefix; % and _ are ordinary characters. |
after | query | string | no | matches ^[A-Za-z0-9_-]+$; 1–8192 characters |
limit | query | integer | no | 1–100; default 50 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 100 items |
items[].path | string | yes | — |
items[].revision | integer | yes | 1–2147483647 |
items[].artifactId | string (uuid) | yes | — |
next | string | yes | matches ^[A-Za-z0-9_-]+$; 1–8192 characters; may be null; Opaque cursor bound to repository and prefix; null at end. Never grants access. |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Get the current revision of a file path
GET HEAD /api/v1/repositories/{repository}/asset
Access: Repository permission: asset.read; file keys: read · Retry: Safe to repeat (read)
Returns the current revision of path and the ID of the artifact it points to; an unknown path is a 404. A path has 1–1024 characters in /-separated segments, without empty, . or .. segments, \, : or control characters. Download the bytes with downloadAssetContent, or pass the revision to setAsset as expectedRevision.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | query | string | yes | — |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
revision | integer | yes | 1–2147483647 |
artifactId | string (uuid) | yes | — |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Point a file path at an artifact
PUT /api/v1/repositories/{repository}/asset
Access: Repository permission: asset.write, artifact.read; file keys: read, write · Retry: Repeat only with the expected revision (compare-and-swap)
Makes path name a published artifact of the same repository as its new revision; expectedRevision is 0 to create the path and the current revision to replace it, otherwise 409 revision_mismatch. Earlier revisions stay in the history and keep their artifacts from being deleted. To store bytes and name them in one request, use putRawFile.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
artifactId | string (uuid) | yes | — |
expectedRevision | integer | yes | 0–2147483646 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
revision | integer | yes | 1–2147483647 |
artifactId | string (uuid) | yes | — |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'List the revisions of a file path
GET HEAD /api/v1/repositories/{repository}/asset/history
Access: Repository permission: asset.read; file keys: read · Retry: Safe to repeat (read)
Returns the revisions of path, newest first, 50 per page, each with its artifact, the actor, the time and, for a restore, the sourceRevision it copied (actor and time are null for revisions recorded by early server versions). Continue with before set to next. An unknown path is a 404.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | query | string | yes | — |
before | query | integer | no | 1–2147483647; Only revisions strictly smaller than this value |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
items | array of object | yes | up to 50 items |
items[].path | string | yes | — |
items[].revision | integer | yes | 1–2147483647 |
items[].artifactId | string (uuid) | yes | — |
items[].actor | string | yes | may be null; Null for history recorded before migration 4 |
items[].createdAt | string (date-time) | yes | may be null; Null for history recorded before migration 4 |
items[].sourceRevision | integer | yes | 1–2147483647; may be null; Restored revision; null for ordinary replacement |
next | integer | yes | 1–2147483647; may be null; Exclusive before cursor; null at end |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Get one revision of a file path
GET HEAD /api/v1/repositories/{repository}/asset/revision
Access: Repository permission: asset.read; file keys: read · Retry: Safe to repeat (read)
Returns revision revision of path with its artifact ID, actor, time and restore source. Revisions never change, so the artifact ID can be cached; download it with downloadArtifact. A missing path or revision is a 404.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | query | string | yes | — |
revision | query | integer | yes | 1–2147483647 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
revision | integer | yes | 1–2147483647 |
artifactId | string (uuid) | yes | — |
actor | string | yes | may be null; Null for history recorded before migration 4 |
createdAt | string (date-time) | yes | may be null; Null for history recorded before migration 4 |
sourceRevision | integer | yes | 1–2147483647; may be null; Restored revision; null for ordinary replacement |
Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Restore an earlier revision of a file path
POST /api/v1/repositories/{repository}/asset/restore
Access: Repository permission: asset.restore, asset.read, artifact.read; file keys: read, write · Retry: Repeat only with the expected revision (compare-and-swap)
Adds a new revision of path that points at the artifact of sourceRevision; nothing is copied and no revision is removed. expectedRevision must be the current revision (at least 1), otherwise 409 revision_mismatch — so repeating a restore that already succeeded is a 409, not a second restore. The new revision records sourceRevision, and the change is audited in the same transaction.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
Request body (application/json)
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
sourceRevision | integer | yes | 1–2147483647 |
expectedRevision | integer | yes | 1–2147483646 |
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
revision | integer | yes | 1–2147483647 |
artifactId | string (uuid) | yes | — |
Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Example
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'Download a file by path
GET HEAD /api/v1/repositories/{repository}/asset/content
Access: Repository permission: content.read; file keys: read · Retry: Safe to repeat (read)
Resolves path to its current revision and streams that artifact like downloadArtifact, with Range, If-Range, If-None-Match and HEAD. The path is resolved on every request, so resume with If-Range set to the returned ETag: after the path moved on, the answer is the whole new file instead of a mixed one. downloadRawFile does the same with the path in the URL.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
Range | header | string | no | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | header | string | no | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | header | string | no | Matching ETag returns 304, including HEAD. |
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. |
path | query | string | yes | — |
Responses: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileUpload a file to a path in one request
PUT /api/v1/repositories/{repository}/raw/{assetPath}
Access: Repository permission: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; file keys: write · Retry: Safe to repeat: the same request has the same effect
Stores the request body, of any media type, as the new revision of the path in the URL, for scripts and CI (curl -T); the answer is 201 with the path, revision and artifact. With X-Checksum-Sha256 and Content-Length the bytes stream straight to storage and are verified; without them they are staged and hashed first (422 if the body does not match a given checksum). The same bytes as the current revision add nothing and answer 200 with created: false, If-None-Match: * only creates (409 already_exists), and a concurrent writer of the same path gets 409 revision_mismatch. For very large files prefer the resumable upload sessions.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
assetPath | path | string | yes | 1–1024 characters; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
X-Checksum-Sha256 | header | string | no | matches ^[a-fA-F0-9]{64}$; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422). |
If-None-Match | header | string | no | one of *; "*": store only when the path does not exist yet (409 already_exists). |
Request body (application/octet-stream)
Response 200
| Field | Type | Required | Rules |
|---|---|---|---|
path | string | yes | — |
revision | integer | yes | at least 1 |
created | boolean | yes | — |
artifact | object | yes | — |
artifact.id | string (uuid) | yes | — |
artifact.size | string | yes | a whole number in decimal digits, sent as a string |
artifact.sha256 | string | yes | SHA-256: 64 lowercase hexadecimal digits |
Responses: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
Example
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileDownload a file by its URL path
GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}
Access: Repository permission: content.read; file keys: read · Retry: Safe to repeat (read)
Streams the current revision of the path in the URL like downloadArtifact, with Range, If-Range, If-None-Match, HEAD and X-Arkvory-Artifact-Id naming the artifact. The path is resolved on every request, so resume with If-Range set to the returned ETag, or download the artifact by ID.
Parameters
| Name | In | Type | Required | Rules |
|---|---|---|---|---|
repository | path | string | yes | matches ^[a-z0-9][a-z0-9_-]{0,63}$ |
assetPath | path | string | yes | 1–1024 characters; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
Range | header | string | no | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | header | string | no | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | header | string | no | Matching ETag returns 304, including HEAD. |
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. |
Responses: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Example
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file