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

{
  "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"
  }
}

{
  "error": "User is not part of any organization"
}

{
  "error": "Unauthorized"
}

{
  "error": "Internal Server Error"
}

Files API

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:

Call this endpoint to get a presigned URL and metadata
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 --request POST \
  --url https://asteragents.com/api/upload/presigned \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "quarterly-report.pdf",
  "contentType": "application/pdf"
}
'

{
  "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"
  }
}

{
  "error": "User is not part of any organization"
}

{
  "error": "Unauthorized"
}

{
  "error": "Internal Server Error"
}

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

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

API Documentation

Admin API

Files API

Agents API

Tools API

Agent Tags API

Knowledge Bases API

Skills API

Conversations API

Scheduled Tasks API

Other Endpoints

Legacy Endpoints (Deprecated)

Get presigned upload URL

Authorizations

Body

Response