File uploads.

JSON webhooks cap at 1 MiB. For anything bigger — CSVs, PDFs, audio, video — stream the file through the upload endpoint first, then reference the returned fi_* id from your webhook body.

When to use this

• You need to send a file larger than 1 MiB.
• You'd rather store the file with Olbrain and reference it by id than embed it as base64.
• The receiving agent or workflow expects a signed URL it can fetch lazily.

For inline payloads under 1 MiB, send them directly in the trigger request — you don't need this endpoint.

Request

Headers

Body

A multipart form with exactly one part named file. The upload is streamed, so multi-GiB files don't need to fit in memory on either end.

curl -X POST https://webhook.olbrain.com/api/agents/agt_01HAKZ.../upload \
  -H "Authorization: Bearer ak_<your-access-key>" \
  -F "file=@./customers.csv"

Response

{
  "file_id": "fi_a1b2c3d4e5f6...32-hex-chars...",
  "size_bytes": 4823104,
  "content_type": "text/csv",
  "filename": "customers.csv"
}

The file_id is opaque — treat it as a token. It is scoped to your organization and the agent you uploaded it for; only that agent can use it.

Using the file_id

Reference the id from inside your webhook trigger body. Your agent fetches the file contents lazily — you don't pass URLs or credentials around.

POST https://webhook.olbrain.com/api/agents/webhook/agt_01HAKZ...
Authorization: Bearer ak_<your-access-key>
Content-Type: application/json

{
  "inputs": {
    "csv_file": "fi_a1b2c3d4e5f6...",
    "operation": "bulk-import"
  }
}

Size limits

Errors