Stage a file so it can be attached to a Research Agent turn or imported into your library. This is a two-step, presigned upload:

1. POST /api/v2/files with the filename, MIME type, and exact byte size. The response returns a file_id and a short-lived presigned upload_url.
2. PUT the raw file bytes to upload_url with the same Content-Type and a Content-Length matching size_bytes. Do not send an Authorization header on the PUT — the URL is already signed.

Then either pass { "file_id": "..." } in the attachments array of a create-session or send-message request — attached files are made available to the agent exactly as uploads made in the web interface are — or pass the file_id in fileIds to POST /api/v2/library/imports to parse the PDF into your library. A staged file can be claimed by one session or one library import. Once attached to a session, the same file_id can be referenced again in later turns of that session, including after the staging expiry; it cannot be reused in another session or import.

The request/response fields for this endpoint are deliberately snake_case (content_type, size_bytes, file_id, upload_url, expires_at), unlike the camelCase used elsewhere in the v2 surface. Files are capped at 30 MB, and a session accepts at most 100 distinct files totaling 10GB across all turns. Upload the bytes and make the first claim within 30 minutes: upload_url and an unclaimed file_id expire at expires_at. A claimed attachment is not subject to that staging expiry.

Example

# 1. Register the upload
curl -X POST https://elicit.com/api/v2/files \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename":"trial-results.pdf","content_type":"application/pdf","size_bytes":245678}'

# 2. Upload the bytes to the returned upload_url
curl -X PUT "{upload_url}" \
  -H "Content-Type: application/pdf" \
  --data-binary @trial-results.pdf

# 3. Attach {"file_id": "..."} to a create-session or /messages request,
#    or import it with POST /library/imports {"fileIds": ["..."]}

{
  "filename": "trial-results.pdf",
  "content_type": "application/pdf",
  "size_bytes": 245678
}

{
  "file_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "expires_at": "2026-07-23T15:00:00.000Z"
}