Uploads

Uploads use signed URLs so your application does not proxy large files through your own server.

Flow

1. Request a signed upload URL.
2. Upload the file to the signed URL.
3. Request a short-lived view URL.
4. Pass the view URL in images, documents, or audios when running the agent.

Request an Upload URL

POST /api/v1/uploads/request

{
  "filename": "refund-policy.pdf",
  "contentType": "application/pdf",
  "purpose": "chat"
}

{
  "fileId": "file_123",
  "signedUrl": "https://storage.example/upload",
  "blobPath": "uploads/ephemeral/project_123/file_123/refund-policy.pdf"
}

Upload the File

curl "$SIGNED_URL" \
  -X PUT \
  -H "content-type: application/pdf" \
  --data-binary "@refund-policy.pdf"

Get a View URL

GET /api/v1/uploads/view-url?blobPath={blobPath}

{
  "viewUrl": "https://storage.example/read"
}

Use the File in a Run

{
  "query": "Summarize this policy for a customer.",
  "documents": ["https://storage.example/read"]
}

Limits To Document For Customers

For production embeds and APIs, publish clear limits for:

• Maximum file size.
• Allowed file types.
• File retention period.
• Number of files per message.
• Whether uploaded files are used for long-term knowledge or only the current conversation.