Create a share bundle

Endpoint

POST https://api.dairo.app/v1/buckets/{bucketId}/share-links

Mints one secure share link over many objects in a bucket, returning a single shareUrl whose viewer page lists every file plus a per-file downloadUrl in files. objectIds is required, must contain no duplicates, and is capped at 50 files; each object must belong to this bucket and have passed its malware scan (clean or skipped) or the call returns 409. password (8–256 characters, used exactly as typed) and maxUses (up to 1000000) apply to the whole bundle exactly as they do for a single-object link. A bundle always expires: without expiresAt it lasts 7 days, and expiresAt (RFC 3339) must lie in the future and at most 30 days ahead, otherwise the call is a 400; the expiry applies to every file's link too. List bundles with GET /v1/share-links/bundles and revoke one with DELETE /v1/share-links/{bundleId}. See secure share links. 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/share-links" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

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

Body

Optional, application/json: CreateShareLinkRequest.

Options for a secure share link over a stored object.

Field	Type	Required	Description
`password`	string	no	Optional password the recipient must enter on the /s/ page: 8-256 characters, used exactly as given (never trimmed) and without a NUL character. An empty string means no password. (min length 8, max length 256)
`maxUses`	integer	no	Optional use cap. 1 = one-time (the /d/ download returns 410 Gone after the first use). (minimum 1)
`expiresAt`	string (date-time)	no	Optional absolute expiry (RFC3339). Must be in the future.

Response

201 Created. Body: application/json, ShareLink.

Field	Type	Required	Description
`object`	string	no
`id`	string	no	Share-link id (shr_*).
`objectId`	string (uuid)	no
`shareUrl`	string	no	Branded /s/ share page URL (returned only at create time).
`downloadUrl`	string	no	Branded /d/ download URL (returned only at create time).
`hasPassword`	boolean	no
`maxUses`	integer or null	no
`oneTime`	boolean	no
`usesCount`	integer	no
`expiresAt`	string (date-time) or null	no
`revoked`	boolean	no
`createdAt`	string (date-time)	no

201

{
  "object": "share_link",
  "id": "string",
  "objectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "shareUrl": "string",
  "downloadUrl": "string",
  "hasPassword": true,
  "maxUses": null,
  "oneTime": true,
  "usesCount": 0,
  "expiresAt": "2026-10-19T09:30:00Z",
  "revoked": true,
  "createdAt": "2026-10-19T09:30:00Z"
}

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