Create a secure share link

Mints a secure share link over one object you own and returns its shareUrl (a viewer page) and downloadUrl.

Endpoint

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

Mints a secure share link over one object you own and returns its shareUrl (a viewer page) and downloadUrl. The object must have passed its malware scan (clean or skipped); a pending, infected, or failed object returns 409. password gates the viewer page (8–256 characters, used exactly as typed — nothing is trimmed), maxUses caps total downloads (set 1 for a one-time link, up to 1000000), and expiresAt is a future RFC 3339 timestamp after which the link stops working (omit for a link that never expires); a value outside these rules is a 400. The link token is returned only once, inside these URLs, and every open is logged. 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/objects/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_*).
`objectId`	string (uuid)	yes	Storage object identifier.

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