API

Tipo

Visão geral

Para

Desenvolvedor, Parceiro whitelabel

A API REST do Lumo deixa outro sistema fazer, sem tela, o que a equipe faria no HEC (Horus Enterprise Control, a suíte de administração) e nas outras suítes: criar Tenants e usuários, liberar acesso a dados, disparar cargas do HorusETL, conversar com o Chat com Dados e guardar arquivos. Esta página cobre o que vale para todas as rotas: endereço, os dois tokens, erros e limite de pedidos. Cada operação tem a própria página no menu, gerada da especificação OpenAPI, e o spec completo junta todas.

Para abrir o Lumo dentro do seu sistema, com o usuário entrando sem tela de login, o caminho inteiro (Tenant, usuário, login e carga) está em Embed.

Base URL

https://api.horusbi.com.br/v1

Todo caminho do menu é relativo a ela: GET /tenant/users é https://api.horusbi.com.br/v1/tenant/users.

Autenticação

Todo pedido leva um token no header Authorization:

Authorization: Bearer SEU_TOKEN

São dois tokens, com escopos diferentes:

Token	Para quê	Rotas	Onde pegar
Client Token	Administrar os Tenants do Cliente (a empresa que contrata o Lumo, como o parceiro whitelabel)	/tenants	Cadastro do Cliente no HEC, aba Desenvolvedor, campo Chave de API
Tenant Token	Operar dentro de um Tenant	/tenant	Cadastro do Tenant no HEC, aba Desenvolvedor, ou o campo token de cada Tenant em GET /tenants

A aba Desenvolvedor só aparece para quem tem a permissão de desenvolvedor. O botão Gerar Novo Token desativa o token atual na hora: toda integração que usa o antigo passa a receber 401.

O Tenant Token só vale com o Tenant ativo. Tenant inativo ou excluído responde 401, igual a um token errado: a resposta não diz qual dos dois foi. Antes de trocar o token, confira o campo ativo do Tenant em GET /tenants, com o Client Token.

O Tenant Token age em nome de qualquer usuário ativo do Tenant. No Chat com Dados, por exemplo, você escolhe o usuário pelo userId e o assistente responde com o acesso dele. Guarde o token só no servidor, nunca no navegador.

Erros

Toda resposta de erro em JSON traz code, um código fixo ao lado de message:

{ "status": "error", "message": "Template not found", "code": "TEMPLATE_NOT_FOUND" }

Decida pelo code. A mensagem pode mudar de redação; o código não muda. Os campos que as respostas de erro já tinham antes do code (status, success, message, error) continuam no corpo.

Nas rotas /tenant (Tenant Token), o status HTTP segue a causa. Nas rotas /tenants (Client Token), criar, alterar e excluir recusam com 400, qualquer que seja a causa. Erro interno é sempre 500.

NOTE

Até 28/10/2026, parte dos erros das rotas /tenant voltava com HTTP 200 e "success": false, e a franquia de usuários voltava 500. Integração que só olhava success agora recebe esses erros como 4xx.

Duas respostas não têm JSON nem code: o 401, com o texto Unauthorized, e o 429 do limite de pedidos. O envio de arquivo acima de 200 MiB também responde em texto, com 413 (veja Upload grande).

Códigos

code	Status	Quando
VALIDATION_ERROR	400	Corpo ou parâmetro inválido
INVALID_VARIABLES	400	development_variables em formato inválido, como null
AGENT_TOKEN_INVALID	400	Token de Agente ETL que não existe
TENANT_NAME_TAKEN	400	Nome de Tenant já usado na plataforma
TENANT_NOT_FOUND	404 (400 em /tenants)	Tenant que não existe ou não é do Cliente
TEMPLATE_NOT_FOUND, PRODUCT_LINE_NOT_FOUND	404 (400 em /tenants)	Template ou Linha de Produto que não existe, é de outro Cliente ou não tem versão vigente
USER_NOT_FOUND, USER_NOT_IN_TENANT	404	Usuário que não existe ou não está no Tenant
USER_LOGIN_TAKEN	409	Login já cadastrado
USER_QUOTA_EXCEEDED	409	Limite de usuários do Tenant atingido
USER_LOGIN_NOT_ALLOWED	403	Usuário da equipe da plataforma, que não entra pela API
MANAGED_BY_PROVIDER	403	Grupo administrado pelo Cliente (parceiro): invisível ao atribuir usuários, ou bloqueado para editar e excluir em /groups
ADMIN_GROUP_NOT_ALLOWED	403	Atribuir ou editar o grupo Administradores pela API
GROUP_NOT_FOUND	404	Grupo que não existe
TABLE_ACCESS_INVALID	400	Item de tables em usuário ou grupo com filtro, coluna ou tabela inválida. errors aponta o campo
APP_NOT_FOUND, DESK_NOT_FOUND, TABLE_NOT_FOUND, DATAMART_NOT_FOUND	404	Aplicação, Mesa, tabela ou Datamart citado no pedido não existe
FLOW_NOT_FOUND, SCHEDULE_NOT_FOUND	404	Dataflow ou agendamento que não existe ou está inativo
EXECUTION_NOT_FOUND	404	executionId que não é deste Tenant
CREDENTIAL_NOT_FOUND	404	Conexão que não existe
AGENT_OFFLINE	409	Em POST /tenant/templates/reload, item cujo Agente ETL não está ativo no Tenant. Nada é disparado
FILE_NOT_FOUND	404 em GET /tenant/files/{id}, 400 nas outras rotas de arquivo	Arquivo que não existe, foi excluído ou é de outro Tenant
FILE_IN_USE	400	Imagem de Cadastro que ainda aparece em algum registro
FILE_TOO_LARGE	400	Arquivo acima de 2 GB na confirmação do envio grande

Erro sem código próprio recebe um genérico pelo status: VALIDATION_ERROR (400), NOT_FOUND (404), INTERNAL_ERROR (500) e REQUEST_FAILED (qualquer outro). Código que a sua integração não conhece, trate pelo status HTTP.

Fora o AGENT_OFFLINE do POST /tenant/templates/reload, o disparo de uma carga volta 200 mesmo que ela venha a falhar. A falha (AGENT_OFFLINE, FLOW_FAILED e outros) aparece depois em errorCode, dentro de GET /tenant/executions/{id}. O limite de IA do chat chega como evento, descrito em Streaming do chat.

Limite de pedidos

A API aceita até 100 pedidos por segundo por endereço IP, contando todas as rotas. Acima disso, responde 429 com o texto Too Many Requests e o header Retry-After, com os segundos até liberar. Espere esse tempo e repita o pedido.

Cada processo da API conta à parte, então às vezes passa um pouco mais que 100. Não conte com essa folga: planeje a integração para ficar abaixo de 100.

O que tem nesta seção

Página	Para quê
Streaming do chat	Ler a resposta do Chat com Dados evento a evento (SSE), com exemplo em Node.js e Python
Upload grande	Enviar arquivo de até 2 GB por URL pré-assinada
Spec completo	Todas as operações numa página só

Cada grupo do menu (Tenants, Usuários, Chat com Dados, Arquivos e os outros) lista as operações com parâmetros, corpo, respostas e exemplos. O arquivo da especificação fica em /api.yml, para gerar cliente ou importar no Postman.