Files

POST `/files/upload-url`

Get a presigned URL to upload a file to. PUT the file's bytes to uploadUrl, then pass the returned key to whichever endpoint consumes the file, such as brand assets or import jobs.

Requires the settings:write permission.

Body Parameters

fileNamestringrequired

The file's name, including its extension.

accesspublic | privaterequired

Whether the uploaded file is served from a public URL or kept private and reachable only through signed links.

sizeBytesinteger

Size of the file in bytes, if you know it up front.

contentTypestring

The file's MIME type, such as image/jpeg. Stored alongside the file so anything displaying it knows what it is.

Request

curl \
  -X POST \
  "https://api.cascade.dev/files/upload-url" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "string",
  "access": "public",
  "sizeBytes": 0,
  "contentType": "string"
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { postFilesUploadUrl } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postFilesUploadUrl({
  body: {
    fileName: "string",
    access: "public",
    sizeBytes: 0,
    contentType: "string",
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/files/upload-url")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "fileName": "string",
    "access": "public",
    "sizeBytes": 0,
    "contentType": "string"
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "fileName": "string",
  "access": "public",
  "sizeBytes": 0,
  "contentType": "string"
}"""

req = Request(
    "https://api.cascade.dev/files/upload-url",
    data=body.encode(),
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "key": "string",
  "uploadUrl": "https://example.com",
  "expiresAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "The storage key for the file. Pass this to the endpoint that consumes it."
    },
    "uploadUrl": {
      "type": "string",
      "format": "uri",
      "description": "PUT the file's bytes to this URL before the expiry."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the upload URL stops working."
    }
  },
  "required": ["key", "uploadUrl", "expiresAt"],
  "additionalProperties": false
}

#Files

POST /files/upload-url

Body Parameters

Files

POST `/files/upload-url`