Documentação do Lumo
Buscar K

Aparência

Abrir no Claude Abrir no ChatGPT

Spec completo ​

Tipo
Referência
Para
Desenvolvedor, Parceiro whitelabel

Todas as operações da API numa página só, na ordem do menu. Autenticação, erros e limite de pedidos estão em API. O arquivo OpenAPI fica em /api.yml.

v1.1.0

API do Lumo​

Baixar Documento OpenAPI

API REST para integrar um sistema ao Lumo: criar e administrar Tenants, usuários, grupos e acesso a dados, disparar cargas do HorusETL, conversar com o Chat com Dados e guardar arquivos. A visão geral, com autenticação, erros e limites, está em API.

Autenticação

Todo pedido leva um token no header Authorization: Bearer <token>. São dois:

Token Onde pegar Rotas
Client Token Cadastro do Cliente no HEC, aba Desenvolvedor /tenants
Tenant Token Cadastro do Tenant no HEC, aba Desenvolvedor, ou o token de cada Tenant em GET /tenants /tenant

Token ausente ou inválido responde HTTP 401 com o texto Unauthorized, sem JSON.

Erros

Toda resposta de erro em JSON traz code, um código fixo ao lado de message (ex.: TENANT_NAME_TAKEN, USER_NOT_FOUND, VALIDATION_ERROR). Decida pelo code: a mensagem pode mudar de redação, o código não. Nas rotas /tenant, o status HTTP segue a causa (400, 403, 404, 409); até 28/10/2026, parte desses erros voltava com HTTP 200 e success: false. Nas rotas /tenants, criar, alterar e excluir recusam com HTTP 400. Erro sem código próprio recebe um genérico pelo status: VALIDATION_ERROR (400), NOT_FOUND (404), INTERNAL_ERROR (500) e REQUEST_FAILED (os demais). A lista completa está em API › Códigos.

Limite de pedidos

Até 100 pedidos por segundo por endereço IP. Acima disso, HTTP 429 com o texto Too Many Requests e o header Retry-After, com os segundos até liberar: espere esse tempo e repita.

Servidores​

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

Tenants​

Criar, listar, alterar e excluir os Tenants do Cliente. Usa o Client Token.

Operações​

GET/tenantsPUT/tenantsPOST/tenantsDELETE/tenantsPOST/tenants/deleteGET/tenants/templates

Listar Tenants​

GET
/tenants

Lista os Tenants do Cliente do token.

Com ?external_id=, retorna só o tenant com esse ID do seu sistema (lista vazia se não houver).

Paginação

page_size (1 a 100) liga a paginação, com page a partir de 1. A resposta traz a página em data, ordenada por id, e pagination com page, page_size e total. Sem page_size, a lista vem inteira e page é ignorado. include_users=false deixa sys_users_tenants de fora, com ou sem paginação.

O campo token de cada tenant é o Tenant Token dele, o que autentica as rotas /tenant. Os dois tokens estão em Autenticação.

Campos

Campo Descrição
id ID interno do tenant
nome Nome do tenant
external_id ID do tenant no seu sistema, se informado na criação
token Tenant Token para autenticar em /tenant/*
status, statusDetail Estado do tenant: provisioning, failed, awaiting_credentials, loading ou ready
dominio Domínio de acesso (ex: empresa.horusbi.com.br)
ativo Se o tenant está ativo
development_variables Variáveis globais do ETL, sempre como lista. Variável protegida vem sem value
config Configurações do tenant
dw_desks, bi_desks Mesas de Dados e Mesas de Aplicação
bi_apps Aplicações DataViz
dw_tables Tabelas do HorusDW
sys_users_tenants Usuários vinculados

Autorizações​

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Parâmetros​

Query Parameters

external_id

Filtra pelo ID do tenant no seu sistema

Tipostring
Example"1234"
page_size

Tenants por página. Liga a paginação

Tipointeger
Example50
Minimum1
Maximum100
page

Número da página, a partir de 1. Ignorado sem page_size

Tipointeger
Example1
Minimum1
Default1
include_users

Com false, cada tenant vem sem sys_users_tenants. Outro valor é ignorado

Tipoboolean
Examplefalse

Respostas​

Tenants do Cliente

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Alterar um Tenant​

PUT
/tenants

Altera um Tenant do Cliente, identificado por id. Só os campos enviados mudam, mas ativo é obrigatório em toda chamada. Mudança em development_variables fica no histórico do Tenant.

ativo: false tranca o login de todos os usuários e pode ser revertido. O efeito na cobrança está em Recursos e cobrança.

Variáveis globais

development_variables aceita objeto {"NOME": "valor"} ou lista, e substitui a lista inteira: variável que não vier é removida do tenant.

Uma variável que continua guarda o que você não mandou dela: descrição, proteção e valores por agente. Trocar o valor de uma protegida mantém a proteção.

Na lista, cada item aceita key, value, description, is_secret e agent_overrides. Variável protegida mandada sem value mantém o valor gravado.

[
  {"key": "DB_HOST", "value": "10.0.0.5",
   "agent_overrides": [{"tokenId": 852, "value": "10.9.0.7"}]},
  {"key": "DB_PWD", "is_secret": true}
]

agent_overrides dá um valor próprio a um Agente ETL: o agente 852 recebe 10.9.0.7, e os outros recebem 10.0.0.5. tokenId é o id do agente, o mesmo de agent.id na resposta da criação, e o agente precisa estar ligado ao tenant. Item sem agent_overrides mantém os valores por agente gravados; lista vazia remove todos.

Campos

Campo Descrição
nome Nome do tenant
ativo false tranca o login; true libera
dominio Domínio de acesso
development_variables Variáveis globais do ETL
config Configurações do tenant

Mensagens de erro

Mensagem Causa
Tenant not found ID não existe ou não pertence ao cliente
Invalid development_variables format... Variável sem key ou com value nulo
Invalid development_variables agent_overrides... agent_overrides fora do formato [{tokenId, value}]
Agente ETL ... não está ligado a este tenant. tokenId de agente que não atende o tenant

Autorizações​

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Tenant alterado

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Criar um Tenant​

POST
/tenants

Cria um Tenant no Cliente do token e, se houver template, aplica o template nele. O passo a passo do provisionamento completo está em Tenant automático.

Comportamento

  1. Com external_id de um tenant que já existe no cliente, a chamada devolve esse tenant com created: false e não cria outro
  2. O tenant é criado e vinculado ao cliente do token
  3. Se token for informado, o Agente ETL dono desse token é vinculado ao tenant
  4. Se templateId for informado, o template é aplicado. Com templateGroupId, vale a versão vigente da Linha de Produto. Sem os dois, vale o Template Padrão do cliente, se houver
  5. A resposta traz o tenant criado, com o Tenant Token em data.token, o agente em agent e o que o template deixou vazio

A chamada é síncrona: só responde depois de aplicar o template inteiro, o que pode levar dezenas de segundos. Configure o timeout do seu cliente HTTP para pelo menos 2 minutos.

A criação não dispara carga. As tabelas do template nascem vazias e ficam assim até o primeiro horário dos agendamentos. Para carregar na hora, use POST /tenant/etl-schedules/run com o Tenant Token devolvido.

O campo token (Agente ETL)

token é o token de um Agente ETL já instalado, o mesmo que aparece em HorusETL › Agentes. Esse agente passa a executar as cargas do tenant novo. Use para um agente na nuvem que atende todos os seus tenants, mandando o mesmo token em todas as criações.

Sem token, o apply do template cria um agente novo só para o tenant, e os Dataflows ficam presos a ele. É o caminho para a origem num banco na rede do cliente final: a resposta traz esse agente em agent, com dedicado: true e o token dele em agent.token, para você instalá-lo lá. Até ele ser instalado, a carga disparada pela API fecha com AGENT_OFFLINE.

Variáveis globais

development_variables preenche as variáveis globais que os Dataflows do template leem ({API_KEY}, {CNPJ_EMPRESA}). Aceita objeto ou lista:

{ "API_KEY": "chave-da-api-deste-cliente", "CNPJ_EMPRESA": "12345678000190" }

[
  {"key": "API_KEY", "value": "chave-da-api-deste-cliente"},
  {"key": "CNPJ_EMPRESA", "value": "12345678000190"}
]

Cada variável precisa de valor: 0 e texto vazio são aceitos, null recusa a criação. Variável do template que não vier aqui entra no tenant vazia e aparece em variaveisVazias.

Na lista, cada item aceita também description e is_secret. Com is_secret: true a variável é protegida: o valor não volta mais nas leituras, nem pela API nem na tela. Valor por agente (agent_overrides) só entra pelo PUT /tenants, depois que o tenant existe.

Template

Só template do cliente do token. templateId de template de outro cliente responde Template not found, igual a um id que não existe.

Nome e domínio

  • nome precisa ser único na plataforma inteira, não só no seu cliente. Inclua o ID do cliente final no seu sistema
  • Sem dominio, o tenant fica em dataviz.horusbi.com.br, e a URL de login transparente sai com esse endereço
  • Se o cliente tem domínio principal configurado no HEC, ele vence o dominio enviado

Falha no meio da criação

O tenant é gravado antes do template ser aplicado. Se o apply falhar, o tenant fica criado e incompleto, com status: failed e o passo em statusDetail.step.

Com external_id, repita a mesma chamada: ela devolve o tenant existente (created: false), inclusive quando duas chamadas chegam juntas. Sem external_id, uma nova tentativa com o mesmo nome é recusada; procure o tenant em GET /tenants. Nos dois casos, aplique o template nele com POST /tenant/templates/apply.

Mensagens de erro

Mensagem Causa
Nome do Tenant indisponível para uso... Já existe tenant com esse nome na plataforma
Token inválido! token não corresponde a nenhum Agente ETL
Invalid development_variables format... Variável sem key ou com valor null
Duplicated development_variables key: ... A mesma key duas vezes na lista
Template not found templateId não existe ou é de outro cliente
Envie templateId ou templateGroupId, não os dois. Os dois campos no mesmo pedido
Linha de Produto não encontrada ou sem versão vigente. templateGroupId não é do cliente ou a Linha não tem versão vigente

Autorizações​

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Tenant criado, ou o existente com o mesmo external_id

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Excluir um Tenant​

DELETE
/tenants

Exclui o tenant: ele é marcado como excluído, sai de GET /tenants e o Tenant Token dele para de valer. Não há como desfazer pela API.

Para só trancar o acesso, use PUT /tenants com ativo: false, que pode ser revertido. O efeito de cada um na cobrança está em Recursos e cobrança.

Mensagens de erro

Mensagem Causa
Tenant not found ID não existe ou não pertence ao cliente

Cliente HTTP que não manda DELETE com corpo pode usar POST /tenants/delete, com o mesmo corpo e o mesmo efeito.

Autorizações​

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Tenant excluído

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Excluir um Tenant por POST​

POST
/tenants/delete

O mesmo DELETE /tenants, por POST, para cliente HTTP que não manda DELETE com corpo. Mesmo corpo, mesmo efeito.

Autorizações​

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Tenant excluído

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Listar templates​

GET
/tenants/templates

Lista os templates do Cliente do token. O id vai em templateId de POST /tenants, na criação, ou de POST /tenant/templates/apply, num Tenant que já existe.

A lista traz todas as versões de cada Linha de Produto, inclusive as descontinuadas. vigente diz qual usar: numa Linha de Produto, é a versão corrente dela; fora de Linha, todo template que não foi descontinuado. Para sempre aplicar a vigente sem guardar id de versão, mande templateGroupId (o linha.id) em POST /tenants.

Autorizações​

clientBearerAuth

Token de acesso do cliente

TipoHTTP (bearer)

Respostas​

Templates do Cliente

application/json
JSON

Playground​

Autorização

Exemplos​

Tenant​

Dados do Tenant do token.

Operações​

GET/tenant

Ler o Tenant do token​

GET
/tenant

Devolve o Tenant do token, com os mesmos campos de cada item de GET /tenants. Usa o Tenant Token em vez do Client Token.

Campos

Campo Descrição
id ID interno do tenant
nome Nome do tenant
token O próprio Tenant Token
external_id ID do tenant no seu sistema, se informado na criação
status, statusDetail Estado do tenant (ver o schema Tenant)
dominio Domínio de acesso
ativo Se o login está liberado
development_variables Variáveis globais do ETL
config Configurações do tenant
dw_desks Mesas de Dados
bi_desks Mesas de Aplicação
bi_apps Aplicações DataViz
dw_tables Tabelas (resumo)
sys_users_tenants Usuários vinculados

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Respostas​

O Tenant do token

application/json
JSON

Playground​

Autorização

Exemplos​

Tabelas​

Tabelas do HorusDW do Tenant e o estado da última carga de cada uma.

Operações​

GET/tenant/tables

Listar tabelas​

GET
/tenant/tables

Lista as tabelas do HorusDW no Tenant, com as colunas de cada uma e o resultado da última carga. Tabela excluída e coluna excluída não aparecem.

O Tenant Token age pelo Tenant inteiro: a lista traz todas as tabelas, sem os bloqueios e o acesso à tabela de cada usuário.

Campos

Tabela

Campo Descrição
id ID da tabela
nome Nome técnico da tabela (ex: fat_vendas)
columns Colunas, na ordem de exibição
ultima_carga Data da última carga, do Dataflow ativo que alimenta a tabela e rodou por último. null se nenhum rodou
status_ultima_carga Resultado dessa carga (success, error)
linhas_ultima_carga Linhas que essa carga gravou, só quando ela teve sucesso. Numa carga Incremental, menos que o total
linhas Total atual de linhas. Só com ?linhas=true, que deixa a consulta mais lenta

Coluna

Campo Descrição
id ID da coluna
column_name Nome técnico da coluna
data_type Tipo de dado (STRING, NUMBER, DATE)
label Rótulo que aparece na tela
column_type column para coluna gravada na tabela, expression para coluna calculada

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Query Parameters

linhas

Com true, soma o total atual de linhas de cada tabela

Tipoboolean

Respostas​

Tabelas do Tenant

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Usuários​

Criar, alterar, listar e inativar usuários do Tenant.

Operações​

GET/tenant/usersPUT/tenant/usersPOST/tenant/usersDELETE/tenant/users/delete

Listar usuários​

GET
/tenant/users

Lista os usuários ativos do Tenant do token. O mesmo usuário pode estar em outros Tenants; aqui só aparece o vínculo com este.

Campos

Campo Descrição
login E-mail do usuário, único na plataforma
nome Nome que aparece na tela
ultimo_login Último acesso a este Tenant
groups IDs dos grupos do usuário
bi_desks IDs das Mesas de Aplicação liberadas para o usuário
apps_deny IDs das Aplicações Bloqueadas para o usuário

Conferir se um e-mail existe

Passe email (ou login, que é o mesmo campo) para buscar um usuário só. data vazio quer dizer que o e-mail não está vinculado a este tenant, e é o sinal para criar o usuário com POST /tenant/users.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Query Parameters

email

Filtra pelo login (e-mail) exato do usuário

Tipostring
Example"ana.souza@cliente.com.br"
login

Mesmo efeito de email

Tipostring
id

Filtra pelo ID do usuário

Tipointeger

Respostas​

Usuários do Tenant

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Editar usuário​

PUT
/tenant/users

Altera um usuário do Tenant, identificado por login, que não muda. Só os campos enviados mudam.

Cada lista enviada substitui a anterior inteira:

Campo Efeito
groups Grupos do usuário. O grupo Administradores e os grupos administrados pelo fornecedor da plataforma ficam, mesmo fora da lista
bi_desks Mesas de Aplicação liberadas
apps_deny Aplicações Bloqueadas
tables Tabelas liberadas ao usuário, com filtro de linha. Tabela fora da lista perde a liberação; num item já liberado, campo omitido mantém o valor

O filtro de linha vai em tables: cada item libera uma tabela, com os filtros, as colunas ocultas e a permissão de exportar. Não precisa de Datamart, e a liberação feita por Datamart não muda com este campo. Exemplos em Filtrar as linhas de cada usuário.

Mensagens de erro

Mensagem Causa
Usuário não encontrado Login não existe ou não está vinculado ao tenant
Este usuário é administrado pelo fornecedor da plataforma... Usuário que a API não altera (403)
Este grupo é administrado pelo fornecedor da plataforma... ID em groups de um grupo que a API não altera (403)
O grupo de administrador não pode ser atribuído pela API. groups inclui o grupo Administradores (403)
App {id} não encontrado ID em apps_deny não existe no tenant
Mesa de aplicação {id} não encontrada ID em bi_desks não existe
Grupo {id} não encontrado ID em groups não existe no tenant
Liberação de tabela inválida: ... Item de tables com coluna de outra tabela, operador sem o valor que pede ou tabela que não é do tenant (400, TABLE_ACCESS_INVALID)

Os não encontrados respondem 404. A alteração para no primeiro erro, e o que veio antes dele no corpo já ficou gravado.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Usuário alterado

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Criar usuário​

POST
/tenant/users

Cria o usuário e o põe no Tenant. Login que já está neste Tenant é recusado.

O usuário é um só na plataforma: login que já existe em outro tenant é vinculado a este, sem criar outro. Nesse caso password é ignorado (vale a senha atual) e nome muda o nome do usuário em todos os tenants dele.

Sem password, o usuário nasce sem senha e entra só pelo login transparente (POST /tenant/login).

O grupo de administrador não pode ser atribuído pela API.

O vínculo com o tenant é gravado antes das permissões. Se um ID de groups, bi_desks ou apps_deny for recusado, a resposta é de erro, mas o usuário já está no tenant: repetir a chamada responde Login já está cadastrado. Corrija com PUT /tenant/users.

Acessos iniciais

Campo Descrição
groups IDs dos grupos
bi_desks IDs das Mesas de Aplicação a liberar
apps_deny IDs das Aplicações a bloquear
tables Tabelas a liberar, com filtro de linha

O filtro de linha vai em tables: cada item libera uma tabela, com os filtros, as colunas ocultas e a permissão de exportar. Não precisa de Datamart, e a liberação feita por Datamart não muda com este campo. Exemplos em Filtrar as linhas de cada usuário.

Mensagens de erro

Mensagem Causa
Login já está cadastrado Usuário já vinculado ao tenant
O grupo de administrador não pode ser atribuído pela API. groups inclui o grupo administrador
Limite de N usuário(s) atingido... Franquia de usuários do tenant esgotada. Volta como HTTP 409 (até 28/10/2026, 500 com a mensagem só no campo error)
App {id} não encontrado ID em apps_deny não existe
Mesa de aplicação {id} não encontrada ID em bi_desks não existe
Grupo {id} não encontrado ID em groups não existe
Liberação de tabela inválida: ... Item de tables com coluna de outra tabela, operador sem o valor que pede ou tabela que não é do tenant (400, TABLE_ACCESS_INVALID)

Os não encontrados respondem 404; o grupo Administradores, 403.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Inativar usuário​

DELETE
/tenant/users/delete

Tira o usuário do tenant: o vínculo é marcado como excluído e as sessões dele neste tenant são encerradas (a aba aberta cai no próximo pedido). O usuário continua na plataforma e nos outros tenants dele.

Mensagens de erro

Mensagem Causa
Usuário não encontrado Login não existe ou não está vinculado ao tenant (404)
Este usuário é administrado pelo fornecedor da plataforma... Usuário que a API não altera (403)

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Gravar as funções de um grupo​

POST
/tenant/groups/functions

Grava as suítes e as Funções do Sistema de um grupo. O que cada função libera está em Papéis.

  • suites, quando vem com itens, vira a lista do grupo: a suíte que ficou de fora sai, e as funções dela saem junto. Ausente ou vazia, as suítes ficam como estão
  • permissionMatrix, quando vem com itens, vira a lista do grupo: a função que ficou de fora sai. Ausente ou vazia, as funções ficam como estão
  • Com read: false, create, update, delete e publish são gravados como false
  • alias de função que não existe é ignorado, sem erro
  • A gravação é inteira ou nada
Alias da suíte Suíte
dw HorusDW
bi DataViz
etl HorusETL
hec HEC

Mensagens de erro

Corpo inválido responde 400. Os outros erros voltam com HTTP 200, em data.success: false e data.message.

Mensagem Causa
Tenant não encontrado Tenant inativo
Grupo não encontrado ID não existe ou não pertence ao tenant
Este grupo é administrado pelo fornecedor da plataforma... Grupo que a API não altera

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Pedido processado. Confira data.success

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Listar as funções de um grupo​

POST
/tenant/groups/functions/list

Devolve as suítes e as Funções do Sistema de um grupo, no formato que POST /tenant/groups/functions aceita de volta.

suites traz os alias das suítes do grupo. permissions traz as funções gravadas e, com tudo false, as funções ainda não gravadas das suítes do grupo, em ordem de suite_alias e alias.

Campos de permissions

Campo Descrição
alias Identificador da função
nome Nome da função na tela
suite_alias Suíte da função
read, create, update, delete, publish Ver, Criar, Editar, Excluir e Publicar
is_blocked Função bloqueada

Mensagens de erro

Voltam com HTTP 200, em data.success: false.

Mensagem Causa
Grupo não encontrado ID não existe ou não pertence ao tenant

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Funções do grupo. Confira data.success

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Listar grupos​

GET
/tenant/groups

Lista os grupos ativos do Tenant, com membros e acessos. Os acessos de um grupo valem para todos os membros; a regra está em Acesso a dados.

Grupo administrado pelo fornecedor da plataforma não aparece, e usuário administrado pelo fornecedor não aparece em users.

Campos

Campo Descrição
id ID do grupo
nome Nome do grupo
bi_desks IDs das Mesas de Aplicação liberadas
apps_deny IDs das Aplicações Bloqueadas
users IDs dos membros

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Respostas​

Grupos do Tenant

application/json
JSON

Playground​

Autorização

Exemplos​

Editar grupo​

PUT
/tenant/groups

Altera um grupo do Tenant, identificado por id. Só os campos enviados mudam, e cada lista enviada substitui a anterior inteira.

Campo Efeito
nome Nome do grupo
bi_desks Mesas de Aplicação liberadas, por ID
apps_deny Aplicações Bloqueadas, por ID
users Membros, por login (e-mail). Só usuário que já está no Tenant
tables Tabelas liberadas ao grupo, com filtro de linha. Tabela fora da lista perde a liberação; num item já liberado, campo omitido mantém o valor

O filtro de linha vai em tables: cada item libera uma tabela, com os filtros, as colunas ocultas e a permissão de exportar. Não precisa de Datamart, e a liberação feita por Datamart não muda com este campo. Exemplos em Filtrar as linhas de cada usuário.

Para pôr ou tirar um membro, mande a lista inteira com ou sem ele. Usuário administrado pelo fornecedor da plataforma continua no grupo mesmo fora da lista.

A API não altera o grupo Administradores nem grupo administrado pelo fornecedor.

Mensagens de erro

A alteração para no primeiro erro, e o que veio antes dele no corpo já ficou gravado.

Mensagem Status Causa
ID do grupo é obrigatório 400 Campo id não enviado
Grupo não encontrado 404 ID não existe ou não pertence ao tenant
O grupo de administrador não pode ser editado pela API. 403 Grupo Administradores
Este grupo é administrado pelo fornecedor da plataforma... 403 Grupo que a API não altera
App {id} não encontrado 404 ID em apps_deny não existe
Mesa de aplicação {id} não encontrada 404 ID em bi_desks não existe
Usuário {login} não encontrado 404 Login não existe ou não está no tenant
O usuário {login} é administrado pelo fornecedor da plataforma... 403 Login de usuário que a API não altera
Liberação de tabela inválida: ... 400 Item de tables com coluna de outra tabela, operador sem o valor que pede ou tabela que não é do tenant (TABLE_ACCESS_INVALID)

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Criar grupo​

POST
/tenant/groups

Cria um grupo no Tenant. Só nome é obrigatório; id é recusado, porque a plataforma gera o seu.

Os outros campos dão os acessos e os membros iniciais, com as mesmas regras de PUT /tenant/groups. O grupo é gravado antes deles: se um ID ou login for recusado, a resposta é de erro, mas o grupo já existe com o nome. Pegue o id em GET /tenant/groups e corrija com PUT /tenant/groups, em vez de repetir a criação.

Mensagens de erro

Mensagem Status Causa
Não é possível criar um grupo com um ID específico 400 Campo id foi enviado
Nome do grupo é obrigatório 400 Campo nome vazio ou não enviado
App {id} não encontrado 404 ID em apps_deny não existe
Mesa de aplicação {id} não encontrada 404 ID em bi_desks não existe
Usuário {login} não encontrado 404 Login não existe ou não está no tenant
Liberação de tabela inválida: ... 400 Item de tables com coluna de outra tabela, operador sem o valor que pede ou tabela que não é do tenant (TABLE_ACCESS_INVALID)

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Inativar grupo​

POST
/tenant/groups/delete

Marca o grupo como excluído. Ele sai de GET /tenant/groups, e os membros deixam de receber os acessos dele; os acessos que vêm de outros grupos ou do cadastro de cada usuário ficam. Não há como restaurar pela API.

Mensagens de erro

Mensagem Status Causa
ID do grupo é obrigatório 400 Campo id não enviado
Grupo não encontrado 404 ID não existe, não é do tenant ou já foi excluído
Este grupo é administrado pelo fornecedor da plataforma... 403 Grupo que a API não altera

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Autenticação​

Login transparente, para abrir o Lumo dentro do seu sistema.

Operações​

POST/tenant/login

Gerar a URL de login transparente​

POST
/tenant/login

Gera a URL de login transparente de um usuário do tenant: quem já entrou no seu sistema abre o Lumo sem digitar senha. O passo a passo está em Login transparente.

O token é um JWT que vale 1 hora a partir de quando foi gerado e pode ser usado mais de uma vez nesse prazo. A sessão aberta pela URL acaba junto com ele, mesmo com o usuário navegando. Gere uma URL nova cada vez que o usuário abrir o Lumo no seu sistema e, em sessão longa, recarregue o iframe com uma URL nova antes de completar 1 hora.

A sessão fica presa a este tenant e a este usuário: dentro dela não é possível trocar de tenant nem acessar como outro usuário.

A resposta vem sem o envelope status/data. O host da url é o domínio do tenant. Se o domínio do tenant tem mais de um endereço separado por vírgula, monte a URL com o seu domínio: https://<dominio>/auth/api/<token>?showMenu=0.

Campos

Campo Descrição
success true quando a URL foi gerada
token O JWT de login
url URL para iframe, redirecionamento ou WebView

Parâmetros da URL

Valem para a sessão inteira, não só para a primeira página.

Parâmetro Valores Descrição
showMenu 0 / 1 0 esconde o menu principal. Padrão 1; a url já vem com 0
showDesksIcon 0 / 1 0 esconde o ícone de Mesas. Padrão 1
forceTheme light / dark Força o tema claro ou escuro
ref Base64 Rota que abre depois do login, em ASCII codificado em Base64

Com ref, a rota /app/report/1 vira L2FwcC9yZXBvcnQvMQ==:

https://[dominio]/auth/api/[token]?showMenu=0&ref=L2FwcC9yZXBvcnQvMQ==

Os jeitos de abrir a URL e como montar um menu próprio com showMenu=0 estão em Login transparente.

Mensagens de erro

Status Mensagem Causa
404 Usuário não encontrado Login não existe ou não está vinculado ao tenant
403 Este usuário não pode entrar pela API do tenant. Usuário da equipe da plataforma

As duas falhas trazem success: false. Até 28/10/2026 elas voltavam com HTTP 200.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Templates​

Aplicar um template no Tenant e recarregar as tabelas reconstruídas.

Operações​

POST/tenant/templates/applyPOST/tenant/templates/reload

Aplicar um template​

POST
/tenant/templates/apply

Aplica um template do Cliente no Tenant do token. É o caminho para instalar um template num Tenant que já existe, ou reaplicar uma versão nova; na criação, mande templateId em POST /tenants. Os templates do Cliente estão em GET /tenants/templates.

O template traz tabelas do HorusDW, Dataflows, agendamentos, Aplicações com Dashboards, os nomes das variáveis globais (o valor fica no Tenant) e as conexões, que nascem vazias e se preenchem em PUT /tenant/credentials/{id}.

Por padrão o apply só acrescenta: nada que já existe no Tenant é removido. Com espelhar=true, ele também poda o conteúdo de produto que não está no template; use dryRun=true para ver a poda antes.

Prévia (preview)

Com preview: true, nada é gravado. A resposta diz, por mesa, conexão, variável, tabela, Dataflow, agendamento e aplicação, se o apply vai criar (create), reescrever (update) ou manter (keep), e lista em rebuilds as tabelas que serão recriadas e ficarão vazias até a próxima carga. Com espelhar: true junto, traz também o plano do espelho em plan.

dryRun continua como sempre: com espelhar, devolve o plano do espelho; sem espelhar, instala o template de verdade. Para ver antes sem instalar, use preview.

Recarga depois do apply (reloadPlan)

Tabela criada ou reconstruída pelo apply fica vazia até a próxima carga. A resposta traz em reloadPlan essas tabelas, em ordem de dependência; para carregar na hora, mande os itens em POST /tenant/templates/reload.

A resposta também traz credenciaisVazias, variaveisVazias e tabelasVazias: o que o template criou sem valor ou sem carga.

Mensagens de erro

Mensagem Causa
Tenant not found Tenant não existe ou foi excluído
Template not found Não existe template ativo com esse templateId, ou ele é de outro cliente

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Operação processada

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Recarregar as tabelas depois do apply​

POST
/tenant/templates/reload

Dispara as cargas dos Dataflows do reloadPlan devolvido por POST /tenant/templates/apply, em lote e em ordem de dependência. Serve para encher na hora as tabelas que o apply criou ou reconstruiu, que ficam vazias até a próxima carga.

As cargas vão para os agentes, agrupadas por agente. A resposta traz o executionId para acompanhar em GET /tenant/executions/{id}. Os Dataflows de um agente offline falham na execução com AGENT_OFFLINE, sem abortar o lote. Lote com Dataflow que ainda está rodando pela API devolve a execução aberta, com alreadyRunning: true.

Só Dataflow do próprio tenant: flowId de outro tenant, inativo ou inexistente responde 404 com FLOW_NOT_FOUND. Item cujo Agente ETL (o tokenId dele, o do Dataflow ou o agente padrão do tenant) não está ativo no tenant responde 409 com AGENT_OFFLINE, e nada é disparado.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Lote enfileirado

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Flows​

Listar e disparar Dataflows do HorusETL.

Operações​

GET/tenant/flowsPOST/tenant/flows/run

Listar Dataflows​

GET
/tenant/flows

Lista os Dataflows ativos do Tenant. Cada Dataflow é uma carga do HorusETL, da origem até uma tabela do HorusDW.

Campos

Campo Descrição
id ID do Dataflow, o flowId de POST /tenant/flows/run
nome Nome do Dataflow
deskId Mesa de Dados do Dataflow
tableId Tabela de destino, quando há
load_type Extração: Total, Incremental ou Temporal (na tela, Janela)
versao Versão atual do Dataflow

O que cada Extração faz está em Tipos de carga.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Respostas​

Dataflows ativos do Tenant

application/json
JSON

Playground​

Autorização

Exemplos​

Executar um Dataflow​

POST
/tenant/flows/run

Dispara agora um Dataflow do Tenant. A resposta volta antes da carga terminar.

data: true só confirma o pedido. Se a carga terminou e se o agente estava online, você acompanha pelo executionId em GET /tenant/executions/{id}: agente offline ou recusa aparecem lá, com errorCode, e o status HTTP continua 200.

Disparar de novo um Dataflow que ainda está rodando pela API não começa outra carga: a resposta traz o executionId da execução aberta, com alreadyRunning: true.

O campo context

context é obrigatório e diz o que esta execução traz da origem. Fora do Total, o que a carga faz com a tabela depende da Gravação do Dataflow; as regras estão em Tipos de carga.

context O que traz
Total A origem inteira. Troca toda a parte do Dataflow na tabela, qualquer que seja a Gravação
Incremental O que mudou desde a última carga
Temporal:* Um intervalo de datas (na tela, Janela)

A janela vai no formato Temporal:tipo:valor:

Formato Exemplo Janela
Temporal:Days:N Temporal:Days:30 Últimos N dias
Temporal:Future:N Temporal:Future:7 Próximos N dias
Temporal:Year:AAAA Temporal:Year:2024 O ano inteiro
Temporal:Month:MM-AAAA Temporal:Month:01-2024 O mês inteiro

Mensagens de erro

code Status Causa
FLOW_NOT_FOUND 404 O id não existe neste Tenant ou o Dataflow está inativo

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Pedido aceito. O resultado fica na execução

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Schedules​

Listar e disparar agendamentos do HorusETL.

Operações​

GET/tenant/etl-schedulesPOST/tenant/etl-schedules/run

Listar agendamentos​

GET
/tenant/etl-schedules

Lista os agendamentos do HorusETL no Tenant, ativos e inativos, com os Dataflows e os gatilhos de cada um. Agendamento excluído não aparece; de cada um, só vêm os Dataflows e os gatilhos ativos.

Campos

Campo Descrição
id ID do agendamento, o scheduleId de POST /tenant/etl-schedules/run
nome Nome do agendamento
ativo Se o agendamento está ativo
flows Dataflows do agendamento, na ordem em que rodam
triggers Gatilhos: quando o agendamento roda

Campos do gatilho

Campo Descrição
type Tipo de gatilho
period Intervalo em minutos, no gatilho periódico
start_time Hora de início (HH:MM)
end_time Hora de término (HH:MM)
start_when Data e hora a partir das quais o gatilho vale

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Respostas​

Agendamentos do Tenant

application/json
JSON

Playground​

Autorização

Exemplos​

Executar um agendamento​

POST
/tenant/etl-schedules/run

Dispara agora um agendamento do Tenant, mesmo inativo: os Dataflows ativos dele rodam um depois do outro, na ordem do agendamento. A resposta volta antes das cargas terminarem. Para um Dataflow só, com a Extração escolhida, use POST /tenant/flows/run.

data: true só confirma o pedido. Se os Dataflows terminaram, você acompanha pelo executionId em GET /tenant/executions/{id}: agente offline ou recusa aparecem lá, com errorCode, e o status HTTP continua 200.

Disparar de novo um agendamento que ainda está rodando pela API não começa outra carga: a resposta traz o executionId da execução aberta, com alreadyRunning: true.

Mensagens de erro

code Status Causa
SCHEDULE_NOT_FOUND 404 O id não existe neste Tenant ou o agendamento foi excluído

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Pedido aceito. O resultado fica na execução

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Execuções​

Estado de uma carga disparada pela API.

Operações​

GET/tenant/executions/{id}

Estado de uma execução​

GET
/tenant/executions/{id}

Estado de uma carga disparada por POST /tenant/flows/run, POST /tenant/etl-schedules/run ou POST /tenant/templates/reload, pelo executionId que veio na resposta do disparo.

Estados

status Significado
queued O agente ainda não começou
running Algum Dataflow começou ou terminou, e algum ainda está aberto
succeeded Todos os Dataflows terminaram com sucesso
failed A execução falhou; o motivo está em errorCode e message

Cada Dataflow tem o seu estado em flows, com rows (linhas gravadas), rowsIn e rowsOut.

Códigos de erro

errorCode Causa
AGENT_OFFLINE Nenhum Agente ETL ativo para o tenant, ou o agente estava offline. Nada foi disparado
AGENT_REJECTED O agente recusou o comando
FLOW_FAILED Um Dataflow falhou. O texto do agente está em message
SCHEDULE_FAILED O agendamento terminou com algum Dataflow em falha
NOT_STARTED O agente não começou a carga em 2 horas
TIMEOUT A carga começou e não terminou em 24 horas

Só execução do próprio tenant. id de outro tenant ou inexistente responde 404.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

O executionId devolvido pelo disparo

Tipostring
Obrigatório
Format"uuid"

Respostas​

Estado da execução

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Credenciais​

Conexões de banco do Tenant, para preencher pela API.

Operações​

GET/tenant/credentialsPUT/tenant/credentials/{id}

Listar conexões​

GET
/tenant/credentials

Lista as conexões de banco ativas do Tenant. O template cria a conexão vazia no tenant novo; filled diz se ela já tem algum campo preenchido.

A leitura nunca devolve password, e segredos dentro de connection string voltam como ******. Os campos dependem do tipo (type); no PostgreSQL são hostname, database, username, password e extra (opcional).

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Respostas​

Conexões do tenant

application/json
JSON

Playground​

Autorização

Exemplos​

Preencher conexão​

PUT
/tenant/credentials/{id}

Grava os campos de uma conexão do tenant, cifrados como no HorusETL.

  • Senha omitida, ou segredo mandado de volta como ******, mantém o valor gravado
  • Os outros campos são substituídos pelo objeto enviado
  • Depois de gravar, o agente relê as conexões do tenant, e a próxima carga já usa os valores novos
  • A gravação fica na trilha de auditoria do tenant

Responde com a conexão gravada, no mesmo formato da listagem.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

ID da conexão, de GET /tenant/credentials

Tipointeger
Obrigatório

Corpo da Requisição​

application/json
JSON

Respostas​

Conexão gravada

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor
Corpo

Exemplos​

Listar Datamarts​

GET
/tenant/datamart

Lista os Datamarts do Tenant, com as tabelas e os donos de cada um. O Datamart agrupa tabelas por assunto, e é nele que o dono libera o acesso a cada tabela; o conceito está em Acesso a dados.

O acesso de usuários e grupos às tabelas de um Datamart está em GET /tenant/datamart/{id}/user e GET /tenant/datamart/{id}/group.

Campos

Campo Descrição
id ID do Datamart
nome Nome do Datamart
dm_tables Tabelas do Datamart, com as colunas. Tabela excluída não aparece
owners Donos do Datamart

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Respostas​

Datamarts do Tenant

application/json
JSON

Playground​

Autorização

Exemplos​

Criar ou alterar um Datamart​

POST
/tenant/datamart

Cria um Datamart, quando o corpo vem sem id, ou altera o Datamart desse id. nome, dm_tables e owners são obrigatórios nos dois casos.

Na alteração, dm_tables e owners viram as listas do Datamart: o que ficou de fora sai, o que é novo entra.

Campo De onde vem o ID
dm_tables[].tableId GET /tenant/tables. Tabela não excluída do Tenant
owners[].userId GET /tenant/users. Usuário do Tenant

Mensagens de erro

Os IDs são conferidos antes de gravar: com erro, nada muda.

Mensagem Status Causa
Invalid userId 404 Usuário não existe ou não é do tenant
Invalid tableId 404 Tabela não existe, não é do tenant ou foi excluída
Datamart not found 404 id que não existe neste tenant (na alteração)

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Datamart gravado

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Listar o acesso de usuários num Datamart​

GET
/tenant/datamart/{id}/user

Lista o acesso às tabelas de um Datamart dado a cada usuário. Um registro por usuário e tabela. Usuário excluído, tabela excluída e usuário administrado pelo fornecedor da plataforma não aparecem. O acesso dado a grupos está em GET /tenant/datamart/{id}/group.

O que cada recorte faz está em Acesso a dados.

Campos

Campo Descrição
userId, user O usuário (id, nome, login)
tableId, table A tabela (id, nome)
allowed true dá acesso à tabela
allow_export Pode exportar a tabela
expires_in Data em que o acesso vence. null sem validade
hidden_columns IDs das colunas escondidas
filters Filtros de linha

Datamart not found (404) quando o id não é de um Datamart deste tenant.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

ID do Datamart

Tipointeger
Obrigatório
Example1

Respostas​

Acesso de usuários às tabelas do Datamart

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Dar acesso a um usuário​

POST
/tenant/datamart/{id}/user

Grava o acesso de um usuário a uma tabela, no Datamart do id. Há um registro por Datamart, tabela e usuário: se ele já existe, é substituído; senão, é criado. O que cada recorte faz está em Acesso a dados.

Campo Regra
userId Usuário ativo no Tenant. Obrigatório
tableId Tabela não excluída do Tenant. Obrigatório
allowed true dá acesso; false grava o registro sem acesso. Obrigatório
allow_export Libera exportar a tabela. Obrigatório
expires_in Data e hora em que o acesso vence. Não aceita null
hidden_columns IDs das colunas a esconder (o id de columns em GET /tenant/tables)
filters Filtros de linha: column com column_id (ID da coluna) e expression (AGP para o valor da coluna), operator (como = ou IN) e value, em texto

Na troca de um registro que já existe, campo opcional que não vier mantém o valor gravado. Por isso uma validade gravada não se tira por aqui: expires_in não aceita null.

Mensagens de erro

Mensagem Status Causa
Datamart not found 404 id que não é de um Datamart deste tenant
Table not found 404 tableId não existe no tenant
Invalid userId 404 Usuário não existe ou não está ativo no tenant
User is managed by the platform provider... 403 Usuário que a API não altera

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

ID do Datamart

Tipointeger
Obrigatório
Example1

Corpo da Requisição​

application/json
JSON

Respostas​

Acesso gravado

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor
Corpo

Exemplos​

Listar o acesso de grupos num Datamart​

GET
/tenant/datamart/{id}/group

Lista o acesso às tabelas de um Datamart dado a cada grupo. Os campos são os de GET /tenant/datamart/{id}/user, com groupId e group no lugar de userId e user.

Os acessos de um grupo valem para todos os membros. Como o acesso de grupo e o de usuário se combinam está em Acesso a dados.

Datamart not found (404) quando o id não é de um Datamart deste tenant.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

ID do Datamart

Tipointeger
Obrigatório
Example1

Respostas​

Acesso de grupos às tabelas do Datamart

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Dar acesso a um grupo​

POST
/tenant/datamart/{id}/group

Grava o acesso de um grupo a uma tabela, no Datamart do id. Funciona como POST /tenant/datamart/{id}/user, com groupId no lugar de userId: um registro por Datamart, tabela e grupo, substituído se já existe, e campo opcional que não vier mantém o valor gravado.

Mensagens de erro

Mensagem Status Causa
Datamart not found 404 id que não é de um Datamart deste tenant
Table not found 404 tableId não existe no tenant
Invalid groupId 404 Grupo não existe ou foi excluído
This group is managed by the platform provider... 403 Grupo que a API não altera

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

ID do Datamart

Tipointeger
Obrigatório
Example1

Corpo da Requisição​

application/json
JSON

Respostas​

Acesso gravado

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor
Corpo

Exemplos​

Chat com Dados​

Conversar com o assistente de IA em nome de um usuário, com resposta em streaming (SSE) ou JSON.

Operações​

POST/tenant/ai/chatGET/tenant/ai/limitGET/tenant/ai/threadsPOST/tenant/ai/threadsGET/tenant/ai/threads/{threadId}/messagesPOST/tenant/ai/threads/{threadId}/cancel

Enviar mensagem ao assistente​

POST
/tenant/ai/chat

Manda uma pergunta ao assistente do Chat com Dados em nome de um usuário do Tenant e devolve a resposta. O assistente consulta os dados com o acesso desse usuário: só vê as Aplicações e tabelas que ele vê, com as mesmas restrições de linha e coluna.

A resposta vem em streaming (SSE) por padrão. Para receber tudo de uma vez em JSON, mande ?stream=false ou o header Accept: application/json. O formato dos eventos, com exemplos em Node.js e Python, está em Streaming do chat.

Sem threadId, a mensagem abre uma conversa nova, e o id dela chega no evento thread (ou em threadId, no modo JSON). Mande esse id nas próximas mensagens para o assistente lembrar o que já foi dito.

O userId precisa ser de um usuário ativo no Tenant e com permissão de IA. Para achar o id a partir do e-mail, use GET /tenant/users?email=.

Erros

No modo SSE, só a validação do corpo responde com status de erro (400). O resto chega como evento error dentro de uma resposta HTTP 200. No modo JSON:

Status code Causa
400 VALIDATION_ERROR Corpo inválido
403 REQUEST_FAILED Usuário fora do Tenant, inativo ou sem permissão de IA
404 NOT_FOUND threadId que não existe, ou de outro usuário
500 INTERNAL_ERROR Falha ao gerar a resposta

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Query Parameters

stream

Com false, a resposta vem em JSON de uma vez. Com true, vem em SSE mesmo com Accept: application/json

Tipostring
Valid values
"true""false"
Example"false"

Corpo da Requisição​

application/json
JSON

Respostas​

Resposta do assistente, em SSE ou JSON

JSON

Playground​

Autorização
Variáveis
Chave
Valor
Corpo

Exemplos​

Consultar o limite de IA​

GET
/tenant/ai/limit

Diz se o Tenant está perto ou além do limite mensal de IA, sem gastar crédito. Consulte antes de mandar mensagens para avisar o usuário em vez de deixar a pergunta falhar. A regra do limite está em Créditos de IA.

state Quer dizer
ok Abaixo de 90% do limite
warn 90% ou mais, ou além do limite num Tenant que não bloqueia
block Além do limite: novas mensagens são recusadas

Com userId, actions traz o que aquele usuário pode fazer para liberar (contratar créditos ou configurar uma chave de IA própria no HEC). Sem userId, actions vem vazio. Se a consulta falhar, a resposta é ok.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Query Parameters

userId

Usuário para quem calcular as ações possíveis

Tipointeger
Example123

Respostas​

Estado do limite

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Listar conversas do usuário​

GET
/tenant/ai/threads

Lista as conversas de um usuário, da mais nova para a mais antiga. Por padrão, só as abertas por esta API (origin=api); as conversas do chat na tela não entram.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Query Parameters

userId*

Dono das conversas

Tipointeger
Obrigatório
Example123
origin

Origem das conversas

Tipostring
Default"api"

Respostas​

Conversas do usuário

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Abrir conversa vazia​

POST
/tenant/ai/threads

Abre uma conversa sem mensagens e devolve o id. Use quando precisar do threadId antes da primeira pergunta; senão, mande a mensagem sem threadId e a conversa nasce junto.

Esta rota não confere se o usuário é do Tenant. A conferência acontece no envio da mensagem.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Conversa aberta

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Ler o histórico de uma conversa​

GET
/tenant/ai/threads/{threadId}/messages

Devolve as mensagens de uma conversa aberta pela API, da mais antiga para a mais nova. A conversa precisa ser do userId informado; de outro usuário ou outro Tenant, a resposta é 404.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

threadId*
Tipostring
Obrigatório
Example"bi_3f6a1c2e-8b4d-4e7a-9c1f-2d5e8a7b4c10"

Query Parameters

userId*

Dono da conversa

Tipointeger
Obrigatório
Example123

Respostas​

Mensagens da conversa

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Cancelar resposta (sem efeito)​

POST
/tenant/ai/threads/{threadId}/cancel

Responde sempre {"cancelled": true} e não interrompe nada. Existe só para compatibilidade.

Para parar de receber uma resposta, feche a conexão SSE. O servidor para de mandar eventos, mas o assistente termina a resposta mesmo assim, e o consumo de IA conta inteiro.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

threadId*
Tipostring
Obrigatório

Respostas​

Sempre esta resposta

application/json

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Listar arquivos​

GET
/tenant/files

Lista os arquivos do Tenant, paginados. Arquivo excluído e upload por URL pré-assinada que não foi confirmado não aparecem.

total e totalBytes contam todos os arquivos que passam no filtro, não só os da página.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Query Parameters

limit

Arquivos por página. Acima de 200, vale 200

Tipointeger
Default50
Maximum200
offset

Quantos arquivos pular

Tipointeger
Default0
origin

Só arquivos desta origem. Outro valor é ignorado

Tipostring
Valid values
"api""hec""dw""etl"
search

Parte do nome do arquivo, sem diferença de maiúscula e minúscula

Tipostring
Example"vendas"
sortBy

Ordem por nome, tamanho ou data de criação

Tipostring
Valid values
"name""size""date"
Default"date"
sortDir
Tipostring
Valid values
"asc""desc"
Default"desc"

Respostas​

Página de arquivos

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Consultar um arquivo​

GET
/tenant/files/{id}

Devolve os dados de um arquivo do Tenant.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

Id do arquivo

Tipostring
Obrigatório
Example"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Format"uuid"

Respostas​

Dados do arquivo

application/json
JSON

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Excluir arquivo​

DELETE
/tenant/files/{id}

O arquivo some da lista e para de abrir na hora. O conteúdo é apagado do armazenamento 7 dias depois, e não há como restaurar pela API.

Imagem enviada por um Cadastro que ainda aparece em algum registro, ou no histórico dele, não pode ser excluída.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

Id do arquivo

Tipostring
Obrigatório
Example"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Format"uuid"

Respostas​

Arquivo excluído

application/json

Playground​

Autorização
Variáveis
Chave
Valor

Exemplos​

Tornar arquivo público ou privado​

PATCH
/tenant/files/{id}

Arquivo público abre pela url sem token. Arquivo privado só abre com um link assinado (POST /tenant/files/{id}/sign).

Sem o campo public no corpo, o arquivo fica privado.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros​

Parâmetros de Caminho

id*

Id do arquivo

Tipostring
Obrigatório
Example"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Format"uuid"

Corpo da Requisição​

application/json
JSON

Respostas​

Visibilidade alterada

application/json

Playground​

Autorização
Variáveis
Chave
Valor
Corpo

Exemplos​

Enviar arquivo (multipart)​

POST
/tenant/files/upload

Envia um arquivo de até 200 MiB num pedido só. Acima disso, a resposta é HTTP 413 com o texto File size limit has been reached, e o arquivo precisa ir pela URL pré-assinada (POST /tenant/files/presign), que aceita até 2 GB. O passo a passo está em Upload grande.

O arquivo entra privado, com origin: api. Se já existe um arquivo com o mesmo nome enviado por esta rota, o conteúdo dele é substituído e o id continua o mesmo.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

multipart/form-data
object

O arquivo. O campo precisa se chamar file

Format"binary"

Nome com que o arquivo fica guardado. Sem ele, vale o nome original

Respostas​

Arquivo guardado

application/json

Playground​

Autorização
Corpo

Exemplos​

Pedir URL de envio (arquivo grande)​

POST
/tenant/files/presign

Primeiro passo do envio de arquivo grande, até 2 GB. Devolve uma URL pré-assinada para você mandar os bytes direto ao armazenamento com PUT, sem passar pela API. A URL vale 15 minutos. Depois do PUT, chame POST /tenant/files/confirm.

O PUT precisa levar o header Content-Type igual ao mime mandado aqui (sem mime, application/octet-stream). Outro valor invalida a assinatura e o armazenamento responde 403.

O arquivo entra privado, com origin: hec. O passo a passo está em Upload grande.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

URL de envio

application/json

Playground​

Autorização
Corpo

Exemplos​

Confirmar envio (arquivo grande)​

POST
/tenant/files/confirm

Último passo do envio de arquivo grande. A API lê o tamanho real direto no armazenamento e recusa arquivo acima de 2 GB. Até a confirmação, o arquivo não aparece na lista, e o que não for confirmado em 24 horas é apagado.

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Corpo da Requisição​

application/json
JSON

Respostas​

Arquivo confirmado

application/json
JSON

Playground​

Autorização
Corpo

Exemplos​

Gerar link temporário​

POST
/tenant/files/{id}/sign

Gera um link que abre o arquivo sem login até expirar, mesmo que ele seja privado. Quem tiver o link abre o arquivo quantas vezes quiser dentro da validade.

ttl é a validade em segundos, de 60 (1 minuto) a 604800 (7 dias). Valor fora da faixa vira o limite mais próximo; sem ttl, ou com valor inválido, vale 3600 (1 hora).

Autorizações​

tenantBearerAuth

Token de acesso do tenant

TipoHTTP (bearer)

Parâmetros de Caminho

id*

Id do arquivo

Tipostring
Obrigatório
Example"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Format"uuid"

Corpo da Requisição​

application/json
JSON

Respostas​

Link gerado

application/json
Autorização
Variáveis
Chave
Valor
Corpo
Desenvolvido por VitePress OpenAPI