Files

List ready files

GET /api/v1/apps/{appId}/buckets/{bucket}/files

The ready files the caller may read.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, bucket.

Response (200, JSON):

Field	Type	Required	Notes
files	array of object	yes
files[].bucket	string	yes
files[].contentType	string	yes
files[].createdAt	string	yes
files[].id	string	yes
files[].name	string	yes
files[].owner	string	yes
files[].size	integer	yes
files[].status	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/apps/{appId}/buckets/{bucket}/files" \
  -H "Authorization: Bearer $TOKEN"

Reserve an upload and presign PUT

POST /api/v1/apps/{appId}/buckets/{bucket}/files

Reserves an upload: name, size and content type, checked against the bucket’s limits and the account’s quota. The answer has a presigned PUT address, valid for 15 minutes. Upload the bytes there, then call finalize.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, bucket.

Request body (JSON):

Field	Type	Required	Notes
contentType	string	yes
name	string	yes
size	integer	yes

Response (200, JSON):

Field	Type	Required	Notes
expiresAt	string	yes
file	object	yes
file.bucket	string	yes
file.contentType	string	yes
file.createdAt	string	yes
file.id	string	yes
file.name	string	yes
file.owner	string	yes
file.size	integer	yes
file.status	string	yes
putUrl	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/buckets/{bucket}/files" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "size": 0, "contentType": "..."}'

File metadata with presigned GET

GET /api/v1/apps/{appId}/buckets/{bucket}/files/{id}

A file’s details, with a presigned GET address valid for 5 minutes.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, bucket, id.

Response (200, JSON):

Field	Type	Required	Notes
expiresAt	string	yes
file	object	yes
file.bucket	string	yes
file.contentType	string	yes
file.createdAt	string	yes
file.id	string	yes
file.name	string	yes
file.owner	string	yes
file.size	integer	yes
file.status	string	yes
getUrl	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/apps/{appId}/buckets/{bucket}/files/{id}" \
  -H "Authorization: Bearer $TOKEN"

Delete a file and its object

DELETE /api/v1/apps/{appId}/buckets/{bucket}/files/{id}

Deletes a file and its stored bytes.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, bucket, id.

Response: no body on success.

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X DELETE "https://node.example.com/api/v1/apps/{appId}/buckets/{bucket}/files/{id}" \
  -H "Authorization: Bearer $TOKEN"

Verify the upload and mark ready

POST /api/v1/apps/{appId}/buckets/{bucket}/files/{id}/finalize

Checks what was uploaded against the reservation and marks the file ready. A reservation nobody finalizes is released after a while, with whatever was uploaded for it.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, bucket, id.

Request body (JSON):

No fields.

Response (200, JSON):

Field	Type	Required	Notes
bucket	string	yes
contentType	string	yes
createdAt	string	yes
id	string	yes
name	string	yes
owner	string	yes
size	integer	yes
status	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/buckets/{bucket}/files/{id}/finalize" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'