Skip to main content
POST/storage/buckets/{bucketName}/objects/sign

Create Signed URL

Mints a pre-authenticated GET URL for one object in the bucket.

expiresIn is required (no default, R-15) and is accepted from 1 to 604800 seconds (7 days); a value outside that range is 400 K9O_INVALID_FIELD_VALUE.

The URL itself is valid for at most 900 seconds: a longer request is clamped to 900, not refused.

The response's expiresIn is the effective lifetime, so read it from the response rather than assuming the requested value.

A URL minted with an extension token never outlives that token.

A read role on the bucket suffices.

Parameters
bucketName *path

The bucket's name.

It is unique within the project.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
path *string

The object's path in the bucket, 1 to 1024 characters.

It may contain slashes.

expiresIn *integer

Requested lifetime in seconds (required, no default).

Accepted 1..604800; the URL is clamped to 900 s, and the response's expiresIn is the effective value.

downloadboolean

True to have the URL serve the object as an attachment (Content-Disposition: attachment).

Default false.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEexpiresIn is required and must be an integer in 1..604800 seconds (R-15: no default expiry).
401K9O_UNAUTHENTICATEDAuthentication is required.
403K9O_RBAC_DENYThe caller's project role does not permit this object operation.
403K9O_ACCESS_DENIEDThe bucket's storage policy does not allow read (signed URL) for this caller (context.reason storage_policy_denied). Checked after the role and IAM checks; a bucket with no policy is unaffected.
404K9O_BUCKET_NOT_FOUNDNo bucket with this name exists in the project.
404K9O_NOT_FOUNDThe object is past the bucket's deleteAfterDays age (counted from its last upload), so it reads as not found.
Response body (200)
data *object

The signed URL and how long it lasts.

signedUrl *string

A URL that reads the object without other credentials until it expires.

Scoped to this one object.

expiresIn *integer

Seconds the URL is valid for: the requested expiresIn, capped at 900, and for an extension token also at the token's remaining life.

meta *any

Request metadata: cost, timing and correlation ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.from('<collection>').createSignedUrl()

Showing example in TypeScript

Request example
{
  "path": "string",
  "expiresIn": 0,
  "download": false
}
Response example (200)
{
  "data": {
    "signedUrl": "string",
    "expiresIn": 0
  }
}

More in Storage & Schema