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.

Endpoint

POST https://api.dairo.app/v1/buckets/{bucketId}/objects

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. The URL expires after 300 seconds (expiresInSeconds). filename and contentType are required; expectedBytes is optional and advisory only — the true size is measured at finalize. Nothing is recorded and no storage is consumed until you finalize the object. A retry simply begins another upload; an upload that is never finalized records nothing. Requires buckets:write.

Scope: buckets:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X POST "https://api.dairo.app/v1/buckets/3fa85f64-5717-4562-b3fc-2c963f66afa6/objects" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "string",
    "contentType": "string"
  }'

Path parameters

Name	Type	Required	Description
`bucketId`	string	yes	Bucket identifier (buk_*).

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Optional idempotency key for safe retries of side-effecting operations. (max length 128)

Body

Required, application/json: CreateBucketObjectRequest.

Field	Type	Required	Description
`filename`	string	yes	(min length 1, max length 1024)
`contentType`	string	yes	(min length 1, max length 256)
`expectedBytes`	integer or null	no	Optional client-declared size; the true size is verified on finalize. (minimum 0)
`metadata`	object or null	no

Response

200 Success. Body: application/json, PresignedUpload.

Field	Type	Required	Description
`objectId`	string (uuid)	yes
`uploadUrl`	string (uri)	yes	Presigned S3 PUT URL.
`method`	`"PUT"`	yes
`headers`	map of string	yes	Headers that MUST be sent with the PUT, exactly as given: the stored Content-Type, the declared type as x-amz-meta-content-type and the filename as x-amz-meta-filename (finalize records both).
`expiresInSeconds`	integer	yes	(minimum 1, maximum 604800)

200

{
  "objectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uploadUrl": "https://example.com",
  "method": "PUT",
  "headers": {},
  "expiresInSeconds": 1
}

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`).