FlowModels

Enviar documentos para um usuário final e usá-los como contexto

Publicado em 11. novembro 2026

Se sua aplicação precisa responder perguntas sobre os documentos de um cliente específico, como o contrato ou a tabela de preços dele, faça o upload desses documentos para o usuário final. Nas requisições seguintes dessa mesma pessoa, o Brain busca automaticamente os trechos relevantes e os entrega ao modelo. Você não precisa criar uma busca própria nem embeddings próprios.

Passo 1: criar o usuário final

Para o upload, você precisa do id do usuário final, e não do seu próprio identificador. Você o obtém com POST /v1/end-users:

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

Se o usuário final já existir, você recebe o registro existente. Use o id da resposta no próximo passo.

Passo 2: enviar o arquivo

Atenção ao caminho: aqui é end_users com sublinhado, enquanto o gerenciamento de usuários finais usa end-users com hífen.

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

purpose é sempre user_data. O Content-Type com boundary é definido pelo seu cliente HTTP em multipart/form-data.

Passo 3: esperar o arquivo ficar pronto

O upload responde com HTTP 201 e status: "pending". Nesse momento o arquivo está salvo, mas ainda não pode ser usado. Extraímos o texto e o preparamos para a busca. Só depois disso as requisições seguintes encontram os trechos relevantes. Você acompanha o andamento com:

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

Repetimos por conta própria quando há erros temporários no processamento. Um documento do qual não seja possível extrair texto, como uma digitalização sem camada de texto, pode falhar de forma definitiva.

Passo 4: fazer perguntas

Envie sua requisição normalmente, com o mesmo external_identifier. O Brain recorre aos trechos relevantes dos arquivos dessa pessoa, veja Usar o Brain: salvar e continuar conversas por usuário final. Os arquivos de um usuário final são vistos apenas por esse usuário final, nunca por outro.

Tipos de arquivo e limites

  • PDF, Word (DOCX, DOC), RTF, Excel (XLSX), PowerPoint (PPTX), texto (TXT), Markdown e CSV
  • no máximo 32 MiB por arquivo
  • no máximo 100 arquivos por usuário final
  • no máximo 5 GiB para todos os arquivos de usuários finais da sua equipe somados
  • nomes de arquivo de até 255 caracteres

O que define o tipo é a extensão do arquivo. A API recusa outras extensões com a indicação unsupported_file_type e arquivos grandes demais com file_too_large.

Verificar e excluir arquivos individualmente

Tarefa Chamada
todos os arquivos de um usuário final, os mais recentes primeiro GET /end_users/{id}/files
um arquivo, sem o conteúdo GET /end_users/{id}/files/{arquivo}
excluir um arquivo DELETE /end_users/{id}/files/{arquivo}

Ao excluir, removemos o arquivo e todos os trechos de texto extraídos dele. Depois disso, o Brain não pode mais usá-lo. Para a cobrança do armazenamento já utilizado, fica um registro sem nome de arquivo e sem conteúdo, que não aparece em nenhuma lista. Um arquivo desconhecido ou de terceiros retorna 404 file_not_found.

Na interface, você vê os arquivos em Usuários finais › Ver detalhes, com nome, tamanho e data.

Quanto custa

No momento, não há taxa mensal pelo armazenamento. O processamento no upload, por exemplo a geração dos embeddings, é cobrado como consumo de modelo. Nas requisições seguintes, a busca nos arquivos também custa um pouco, e isso entra em usage.cost da respectiva resposta.

Diferença em relação a outros arquivos

Arquivos de usuário final são conhecimento que o Brain acessa quando precisa. Eles são separados dos arquivos em /files, que você anexa diretamente a uma mensagem individual. Um ID de arquivo de usuário final não funciona como file_id em uma mensagem. Mais sobre anexos em Enviar imagens, PDFs e áudio para um modelo.

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP