Upload Session File

POST/v1/agents/sessions/{session_id}/files

SandBase extension. Upload one file (multipart field file, up to 5 MiB) into the Session workspace. Idempotency-Key is required. Supported extensions: .txt, .md, .csv, .log, .json, .pdf, .png, .jpg, .jpeg, .webp; content must match the extension. File names use letters, digits, spaces, dots, underscores, and hyphens. If the transfer fails the response is still 201 with status failed and error_code attachment_unavailable. Send a ready file with POST /v1/agents/sessions/{session_id}/events using file_ids.

Path parameters

stringsession_idrequired

Session ID (ses_ prefix).

Headers

stringIdempotency-Keyrequired

1-128 characters, no leading or trailing whitespace. Reuse the same key and body when retrying; the same key with a different body returns 409.

Request body

multipart/form-data.

filefilerequired

Exactly one file part.

curl -X POST https://api.sandbase.ai/v1/agents/sessions/ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83/files \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Idempotency-Key: upload-q3-report" \
  -F "file=@q3-report.pdf;type=application/pdf"

Response201 Created

{
  "id": "fil_6d8f0a2c-4e6b-5d8f-a1c3-5e7a9c1e3b72",
  "session_id": "ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83",
  "name": "q3-report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 482113,
  "status": "ready",
  "created_at": "2026-10-06T08:10:00Z",
  "updated_at": "2026-10-06T08:10:02Z"
}