Share Object
Generate an unauthenticated link to download an object, time-limited or permanent.
| Endpoint | Method | Admin Required |
|---|---|---|
/api/v1/objects/share | POST | No |
Generates a link that anyone can use to download an object, with no credentials required - time-limited by default, or non-expiring when expiresInSeconds is omitted. The link is an opaque, unguessable token mapped to the object server-side - it never contains the bucket name, key, or any access key.
Request Body
bucket
string required
Name of the bucket. Must be owned by the authenticated user.
key
string required
Object key to share.
expiresInSeconds
integer
How long the link stays valid, in seconds. Must be between
1 and 604800 (7 days) when given. Omit it (or send null) for a link that never expires - it then works until explicitly revoked.Example
{
"bucket": "my-bucket",
"key": "report.pdf",
"expiresInSeconds": 3600
}
Response
{
"url": "https://api.example.com/api/v1/shared/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"expiresAt": "2025-01-15T13:00:00Z"
}
url
string
The public, unauthenticated URL. Fetching it with
GET returns the object's contents directly, with a Content-Disposition header set to the object's original filename.expiresAt
string
ISO 8601 timestamp of when the link stops working. Absent for a non-expiring link.
A time-limited link is revoked automatically once it expires - a background task removes expired links roughly once a minute. A non-expiring link is never auto-removed; it works until you revoke it yourself. To revoke any link early, see Revoke Shared Link. To see all of your active links, see List Shared Links.
Errors
| Status | Reason |
|---|---|
400 | expiresInSeconds was given but is outside the 1-604800 range |
404 | Bucket not found (or not owned by you), or object not found |