FlowModels

Gerenciar e excluir usuários finais pela API: metadados, exclusão e comprovante de exclusão

Publicado em 11. novembro 2026

Quando uma pessoa encerra a conta na sua aplicação ou pede a exclusão dos dados dela, você também precisa remover esses dados no FlowModels. Isso pode ser feito pela interface ou de forma automatizada pela API. Para cada exclusão, você recebe um comprovante de exclusão, com o qual pode provar depois o que foi removido.

Listar e consultar usuários finais

Tarefa Chamada
todos os usuários finais GET /v1/end-users
criar ou obter um existente POST /v1/end-users
consultar um usuário final GET /v1/end-users/{id}
alterar metadados ou memórias PATCH /v1/end-users/{id}
excluir DELETE /v1/end-users/{id}

A lista retorna até 100 entradas por página. Se has_more estiver como true, busque a próxima página com after e o UUID de last_id.

Cada entrada contém o id, o seu external_identifier e o metadata. Em todas as chamadas com {id}, você precisa do id, e não do seu próprio identificador. Se você só tiver o seu identificador, POST /end-users com esse identificador retorna o usuário final existente junto com o id, sem criar um segundo.

Manter metadados

Com metadata, você guarda informações próprias sobre o usuário final, por exemplo o plano no seu sistema:

curl -X PATCH https://api.flowmodels.one/v1/end-users/018f1234-5678-7abc-9def-0123456789ab \
  -H "Authorization: Bearer at_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"plano": "business"}}'

Os valores novos são mesclados com os existentes. São permitidas no máximo 50 entradas, chaves de até 64 caracteres e valores como texto de até 1.000 caracteres ou null. Na mesma chamada, você pode ativar ou desativar as memórias automáticas com memory_extraction_enabled. O external_identifier não pode ser alterado.

Excluir um usuário final

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

Com isso, você remove as conversas, os arquivos e as memórias dessa pessoa. Isso não pode ser desfeito. As linhas de faturamento e consumo são mantidas por motivos de retenção, para que suas faturas continuem corretas.

A resposta "deleted": true confirma que a exclusão foi iniciada e que os dados não são mais usados. Os arquivos armazenados são removidos em seguida, em segundo plano. O comprovante de exclusão mostra se isso já foi concluído.

Consultar o comprovante de exclusão

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

Aqui também, atenção ao sublinhado em end_users. Os comprovantes continuam disponíveis depois da exclusão, porque é justamente nessa hora que você precisa da prova. Um comprovante específico é consultado com GET /end_users/{id}/erasures/{comprovante}.

{
  "id": "018f9a2b-…",
  "object": "end_user.erasure",
  "status": "completed",
  "requested_at": "2026-11-05T08:15:00+00:00",
  "completed_at": "2026-11-05T08:15:04+00:00",
  "manifest_summary": {
    "resources": {
      "memories": {"before": 12, "after": 0},
      "end_user_files": {"before": 3, "after": 0}
    },
    "objects_remaining": 0
  }
}
  • status: pending (criada), objects_pending (arquivos ainda sendo removidos), completed (concluída), objects_partial (parcialmente concluída) ou failed (falhou)
  • completed_at: momento da conclusão, null enquanto ainda houver arquivos sendo removidos
  • manifest_summary.resources: para cada tipo de dado, a quantidade antes e depois da exclusão
  • objects_remaining: quantos objetos armazenados ainda estão pendentes

O comprovante contém apenas números, nenhum texto, nome de arquivo ou identificador. Portanto, você pode guardá-lo sem preocupação no seu próprio registro de exclusões.

Na interface

Em Usuários finais › Ver detalhes, você exclui um usuário final digitando o identificador dele para confirmar e clicando em Eliminar utilizador final. A área Execuções de eliminação, abaixo da lista de usuários finais e nos detalhes, mostra cada execução com Iniciada, Estado, Motivo, Objetos pendentes e Conclusão. Os detalhes estão em Gerenciar os usuários finais da sua aplicação.

Uma execução concluída remove o usuário final da lista, e a prova continua visível na área Execuções de eliminação, inclusive para exclusões feitas pela API.

Quando algo não funciona

  • 404 end_user_not_found: o id não existe ou pertence a outra equipe. Verifique se você não usou por engano o seu external_identifier em vez do id.
  • Status objects_partial ou failed: parte dos arquivos ainda não pôde ser removida. Erros temporários de armazenamento são tentados novamente. Se o status continuar assim, fale com o suporte informando o id do usuário final.

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP