FlowModels

Upload documents for an end user and use them as context

Published on 11. November 2026

If your application needs to answer questions about a specific customer's documents, such as their contract or price list, upload those documents for the end user. For later requests from the same person, the Brain automatically finds the relevant passages and passes them to the model. You don't need to build your own search or your own embeddings for this.

Step 1: Create the end user

For the upload, you need the end user's id, not your own identifier. You get it with POST /v1/end-users:

curl -X POST https://api.flowmodels.one/v1/end-users \
  -H "Authorization: Bearer at_your_key" \
  -H "Content-Type: application/json" \
  -d '{"external_identifier": "customer-1042"}'

If the end user already exists, you get the existing record back. Use the id from the response in the next step.

Step 2: Upload the file

Pay attention to the path: here it's end_users with an underscore, while end-user management uses end-users with a hyphen.

curl -X POST https://api.flowmodels.one/v1/end_users/018f1234-5678-7abc-9def-0123456789ab/files \
  -H "Authorization: Bearer at_your_key" \
  -H "Accept: application/json" \
  -F "file=@quote-2026.pdf" \
  -F "purpose=user_data"

purpose is always user_data. Your HTTP client sets the Content-Type with the boundary itself for multipart/form-data.

Step 3: Wait until the file is ready

The upload responds with HTTP 201 and status: "pending". The file is then stored but not usable yet. We extract the text and prepare it for search. Only after that can later requests find the relevant passages. You can check the state with:

curl https://api.flowmodels.one/v1/end_users/018f1234-5678-7abc-9def-0123456789ab/files \
  -H "Authorization: Bearer at_your_key"

We retry temporary processing errors ourselves. A document from which no text can be read, such as a pure scan without a text layer, can fail permanently.

Step 4: Ask questions

Send your request as usual with the same external_identifier. The Brain draws on the relevant sections from this person's files, see Use the Brain: store and continue conversations per end user. An end user's files are only visible to that end user, never to another.

File types and limits

  • PDF, Word (DOCX, DOC), RTF, Excel (XLSX), PowerPoint (PPTX), text (TXT), Markdown and CSV
  • at most 32 MiB per file
  • at most 100 files per end user
  • at most 5 GiB for all of your team's end-user files combined
  • filenames up to 255 characters

The file extension determines the type. The API rejects other extensions with the note unsupported_file_type, and files that are too large with file_too_large.

Check and delete individual files

Task Call
all files of an end user, newest first GET /end_users/{id}/files
one file, without content GET /end_users/{id}/files/{file}
delete a file DELETE /end_users/{id}/files/{file}

When you delete a file, we remove it and all text sections derived from it. After that, the Brain can no longer use it. For billing of storage already used, an entry without filename or content remains, which doesn't appear in any list. We respond to an unknown file or one belonging to someone else with 404 file_not_found.

In the interface, you can see the files under End users › Show details with name, size and date.

What it costs

There is currently no monthly fee for storage. Processing during upload, for example generating the embeddings, is billed as model usage. For later requests, searching the files also costs a little, which is included in the usage.cost of the respective response.

How this differs from attachments

End-user files are knowledge the Brain accesses when needed. They're separate from the files under /files, which you attach directly to a single message. A file ID from end-user files doesn't work as file_id in a message. More on attachments in Send images, PDFs and audio to a model.

Was this article helpful?

Back to Webhooks, end users & MCP