Finalize an object upload
Call this after the upload PUT completes.
Call this after the upload PUT completes. Dairo measures the uploaded bytes for their true size, gates them against your account's storage limit (returning 429 and discarding the orphaned upload if it would exceed), records the object, and returns it with scanStatus: "pending". The returned object's id is not the upload objectId: download, share links and delete take this id. Finalizing is idempotent: re-finalizing an already-recorded object returns it unchanged and never re-charges storage. Finalizing before the PUT has landed returns 404, and reusing a one-time upload URL returns 409. The malware scan runs asynchronously; an object.scanned webhook fires when the verdict is ready. Requires buckets:write.
Scope: buckets:write. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
bucketId | string | yes | Bucket identifier (buk_*). |
objectId | string (uuid) | yes | Storage object identifier. |
Response
200 Success. Body: application/json, BucketObject.
| Field | Type | Required | Description |
|---|---|---|---|
object | "bucket_object" | yes | |
id | string (uuid) | yes | |
filename | string | yes | |
contentType | string or null | no | |
bytes | integer | yes | (minimum 0) |
scanStatus | "pending", "clean", "infected", "failed", "skipped" | yes | Async malware-scan verdict (W2.2). Objects start 'pending' (owner-only, not publicly served) and become 'clean' or 'infected'/'failed' once the scanner runs. Public links (/d/, /s/) and native attach require 'clean' (or trusted 'skipped'). |
createdAt | string (date-time) | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
409 | The resource already exists or its state does not allow this (duplicate_resource or a condition-specific code). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
Start an object upload
Begins an upload and returns an objectId (the upload id, used only to finalize this upload), a short-lived uploadUrl, the HTTP method to use (PUT), and a headers map you MUST echo on the upload request or it is rejected.
Get an object download URL
Returns a time-limited downloadUrl for the object, valid for 3600 seconds (expiresInSeconds).