Presign Upload

Generates a presigned upload URL for a new asset. The upload follows a two-step flow: first obtain the presigned URL, then PUT the file directly to object storage.

POST /v1/assets/presign

assets:write

Query Parameters

Parameter	Type	Required	Default	Description
filename	string	Yes	—	Original filename including extension (e.g. logo.png).
content_type	string	No	application/octet-stream	MIME type of the file being uploaded.
file_size	integer	Yes	—	Size of the file in bytes. Maximum 25 MB (26,214,400 bytes).

Two-step upload flow

Uploading an asset requires three steps:

1. Request a presigned URL using this endpoint.
2. PUT the file directly to the returned upload_url with the specified headers.
3. Confirm the upload by calling POST /v1/assets/presign/{asset_id}/confirm.

The asset will remain in pending status until the upload is confirmed.

Request Examples

curl

# Step 1: Get presigned URL
curl -X POST "https://xqr.co/api/v1/assets/presign?filename=logo.png&content_type=image/png&file_size=48210" \
  -H "Authorization: Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Step 2: Upload file to the returned URL
curl -X PUT "https://storage.example.com/presigned-url..." \
  -H "Content-Type: image/png" \
  --data-binary @logo.png

TypeScript

// Step 1: Get presigned URL
const params = new URLSearchParams({
  filename: "logo.png",
  content_type: "image/png",
  file_size: "48210",
});

const presignResponse = await fetch(
  `https://xqr.co/api/v1/assets/presign?${params}`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
  },
);

const { data } = await presignResponse.json();

// Step 2: Upload file directly to storage
await fetch(data.upload_url, {
  method: data.method, // "PUT"
  headers: data.headers,
  body: fileBuffer,
});

console.log(`Asset ${data.asset_id} uploaded, now confirm it.`);

Python

import httpx

# Step 1: Get presigned URL
presign_response = httpx.post(
    "https://xqr.co/api/v1/assets/presign",
    headers={
        "Authorization": "Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
    params={
        "filename": "logo.png",
        "content_type": "image/png",
        "file_size": 48210,
    },
)

data = presign_response.json()["data"]

# Step 2: Upload file directly to storage
with open("logo.png", "rb") as f:
    httpx.put(data["upload_url"], headers=data["headers"], content=f.read())

print(f"Asset {data['asset_id']} uploaded, now confirm it.")

Response

200 OK

The presigned upload details.

{
  "data": {
    "asset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "upload_url": "https://us-east-1.linodeobjects.com/xqr-private/tenants/ws_abc/originals/a1b2c3d4.png?X-Amz-Algorithm=...",
    "method": "PUT",
    "headers": {
      "Content-Type": "image/png"
    }
  },
  "meta": {
    "request_id": "req_2b3c4d5e6f7a8b90",
    "rate_limit": {
      "limit": 600,
      "remaining": 596,
      "reset": 1742572800
    }
  }
}