Skip to content
Runbear Docs
GitHub

Files

Upload documents and images through the REST API and attach them to a message so the agent can read them.

On this page
What you needUploading a fileSupported file typesAttaching a file to a messageLimitsRelated

An agent can read files a user sends with a message: a contract to review, a spreadsheet to summarize, a screenshot to explain. Through the REST API, you upload the file first, then attach the result to the message.

What you need#

  • An API key with the chat capability. See Authentication and API keys.
  • A thread. Uploads belong to a thread, so create one with POST /v1/threads before uploading. See Chat.

Uploading a file#

POST /v1/files/upload takes a multipart/form-data body with three fields, all required:

FieldValue
fileThe file, up to 50 MB
assistant_idThe agent's id
thread_idThe thread the file is for
curl -s https://api.runbear.io/v1/files/upload \
  -H "Authorization: Bearer $RUNBEAR_API_KEY" \
  -F "file=@q3-report.pdf" \
  -F "assistant_id=$AGENT_ID" \
  -F "thread_id=$THREAD_ID"

The response describes the stored file:

{
  "url": "https://storage.googleapis.com/...",
  "name": "attachments/<agent id>/<thread id>/<id>-q3-report.pdf",
  "contentType": "application/pdf"
}

Supported file types#

KindTypes
DocumentsPDF, Word (.docx, .doc), Excel (.xlsx, .xls), PowerPoint (.pptx, .ppt)
Text and dataCSV, plain text, Markdown, Python (text/x-python), JSON, XML (application/xml, text/xml)
ImagesPNG, JPEG, GIF, WebP, SVG

The file's own content type decides whether it is accepted. When the client sends application/octet-stream, application/zip, or no type at all, Runbear infers the type from the file name's extension instead, which is how Office files that some clients label as zip archives are recognized. Any other type is refused with 400.

Attaching a file to a message#

Pass the upload response as an entry of the message's attachments, on a run or a chat completion:

{
  "assistant_id": "<agent id>",
  "messages": [
    {
      "role": "user",
      "content": "What are the three biggest risks in this report?",
      "attachments": [
        {
          "name": "q3-report.pdf",
          "url": "https://storage.googleapis.com/...",
          "contentType": "application/pdf"
        }
      ]
    }
  ]
}

Send the message soon after the upload, while the link is still valid. For a file you need again later, upload it again.

Limits#

  • 50 MB per file.
  • 10 attachments per message on Claude Agent SDK agents. A message with more is refused with 422 before the turn starts. Other agent types have no per-message count limit from Runbear.
  • Each upload counts against the chat rate limit for its agent.
  • Uploading isn't available with a Web SDK session pass. It needs an API key.
  • A thread that doesn't exist, or belongs to another organization, answers 404.