Get presigned upload URL

Get a presigned URL for uploading a file. This is the first step in a two-step upload flow.

Upload Flow:

1. Call this endpoint to get a presigned URL and metadata
2. PUT the file to the returned URL with the required headers

The presigned URL is signed with specific metadata headers. You must include these headers when uploading or the request will fail with SignatureDoesNotMatch.

Required headers for the PUT request:

• Content-Type: Use metadata.contentType from the response
• x-amz-meta-file-type: Use metadata.contentType from the response
• x-amz-meta-org-id: Use metadata.orgId from the response
• x-amz-meta-user-id: Use metadata.userId from the response

Presigned URLs expire after 10 minutes.

POST /upload/presigned

cURL

pdf

curl --request POST \
  --url https://www.asteragents.com/api/upload/presigned \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "quarterly-report.pdf",
  "contentType": "application/pdf"
}
'

200

{
  "url": "https://account-id.r2.cloudflarestorage.com/bucket/org_xxx/uploads/file-uuid/report.pdf?X-Amz-Algorithm=...",
  "method": "PUT",
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "key": "org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/report.pdf",
  "contentKey": "org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md",
  "metadata": {
    "contentType": "application/pdf",
    "orgId": "org_xxx",
    "userId": "user_xxx"
  }
}

Authorizations

Authorization · string · header · required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Body

application/json

filename · string · required

The name of the file being uploaded

Example:

"report.pdf"

contentType · string · required

The MIME type of the file

Example:

"application/pdf"

Response

200

application/json

Presigned URL generated successfully

url · string<uri> · required

The presigned URL to upload the file to

Example:

"https://account-id.r2.cloudflarestorage.com/bucket/..."

method · enum<string> · required

The HTTP method to use (always PUT)

Available options: PUT

Example:

"PUT"

fileId · string<uuid> · required

Unique identifier for the uploaded file

Example:

"550e8400-e29b-41d4-a716-446655440000"

key · string · required

The storage key/path where the file will be stored

Example:

"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/report.pdf"

contentKey · string · required

The storage key for extracted text content (for documents)

Example:

"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md"

metadata · object · required

Values that MUST be included as headers when uploading to the presigned URL

Show child attributes