API de integração

URL base

O host do servidor de API em produção é https://api.vectorhub.ramme.dev/. Os endpoints desta referência usam o prefixo /api/v1 a partir desse host.

URL base completa da API de integração:

https://api.vectorhub.ramme.dev/api/v1

Em ambientes dedicados ou homologação, a sua equipe pode indicar outro host; a estrutura dos caminhos permanece a mesma.

Autenticação

Envie o token de API no cabeçalho Authorization:

Authorization: Bearer <seu-token-de-api>

Tokens são criados no console pelo administrador. O valor completo do token é mostrado apenas na criação; guarde-o em local seguro (variável de ambiente, cofre de segredos, etc.).

Em caso de falha de autenticação, a API responde com 401 e um JSON com error e message (por exemplo, token ausente, inválido ou desativado).

O que o token permite

Cada token opera dentro dos limites definidos no console:

Ações (jobs): só é possível solicitar ações cujo módulo foi liberado para aquele token. O nome da ação segue o padrão módulo.operação (ex.: print.send); apenas a parte antes do primeiro ponto conta como módulo.
Recursos: os tipos query e template só aparecem na API se tiverem sido autorizados para o token. Caso contrário, listagens e leituras não os incluem e gravações podem retornar 403.

Jobs

Um job representa uma solicitação de execução de uma ação no ambiente dos agents. Através desta API, cada token vê apenas os jobs que ele mesmo criou.

POST /jobs

Cria um job e o envia para execução. O modo de resposta depende dos campos opcionais sync e callbackUrl — veja Modos de resposta.

Corpo JSON

Campo	Obrigatório	Descrição
`action`	sim	Nome da ação (ex.: `data.query`). Deve ser permitida para o token.
`params`	não	Objeto JSON enviado ao agent. Padrão `{}`.
`agentId`	não	Agente que deve executar a tarefa. Se omitido, o sistema escolhe um agente disponível capaz de executar a ação.
`timeout`	não	Limite de tempo em milissegundos para a execução no agent.
`priority`	não	`low`, `normal` ou `high`. Padrão `normal`.
`sync`	não	Se `true`, o servidor aguarda a conclusão do job e retorna o resultado na própria resposta. Veja Modos de resposta.
`syncTimeout`	não	Tempo máximo de espera em milissegundos no modo síncrono. Padrão `30000`, máximo `60000`.
`callbackUrl`	não	URL para notificação via webhook quando o job terminar. Veja Modos de resposta.

400 se action estiver ausente; 403 se a ação não for permitida; 408 se o timeout síncrono expirar; 500 em falha ao processar a solicitação.

GET /jobs

Lista os jobs criados por este token. Cada item tem o mesmo formato do objeto retornado por GET /jobs/:jobId (estado na hora da listagem). Resposta { "jobs": [ ... ] }.

GET /jobs/:jobId

Retorna o job atual pelo identificador, com { "job": { ... } }. 404 se não existir ou não estiver acessível com este token.

Quando a execução termina com sucesso (status completed), o objeto inclui o campo result com o retorno da ação no agent (objeto JSON, lista, texto, etc., conforme o módulo e a ação). Enquanto o job está pending, dispatched ou running, result em geral ainda não vem preenchido; durante running podem aparecer progress e progressMessage.

Se a execução falha ou é interrompida de forma terminal (failed, cancelled, timeout, agent_disconnected, entre outros), o objeto pode trazer error com code, message e, quando aplicável, details.

Jobs em estado terminal (completed, failed, cancelled, timeout, agent_disconnected, etc.) são removidos da memória do servidor 1 hora após o instante de conclusão (em geral o campo completedAt). Depois disso, GET /jobs/:jobId responde 404 e o job deixa de aparecer em GET /jobs. Enquanto estiver pending, dispatched ou running, não há expiração por esse prazo. Um reinício do serviço também apaga todos os jobs em memória. Para histórico duradouro, guarde result ou error no seu sistema assim que o job estiver terminal.

Modos de resposta

Por padrão o endpoint é assíncrono: retorna 202 Accepted imediatamente e o resultado deve ser consultado em GET /jobs/:jobId (polling). Dois campos opcionais alteram esse comportamento:

Modo síncrono (`sync: true`)

O servidor aguarda a conclusão do job antes de responder. Útil quando o resultado é necessário na sequência da chamada e a latência esperada é baixa.

Quando o job termina dentro do prazo: resposta 200 OK com { "job": { ... } } e o campo result já preenchido.
Quando o prazo expira antes de o job terminar: resposta 408 Request Timeout com { "job": { ... }, "error": "sync_timeout" }. O job continua rodando no servidor; você ainda pode consultá-lo via GET /jobs/:jobId.

Use syncTimeout para definir o prazo máximo (padrão 30 s, máximo 60 s). Defina um valor compatível com o tempo esperado de execução da ação para evitar timeouts desnecessários.

curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"data.query","params":{"resourceId":"minha-consulta"},"sync":true,"syncTimeout":10000}'

Modo webhook (`callbackUrl`)

O endpoint retorna 202 Accepted imediatamente. Quando o job atinge um estado terminal (sucesso, falha, timeout, desconexão do agent, etc.), o servidor faz um POST para a URL informada com o objeto do job no corpo.

O corpo enviado ao webhook é { "job": { ... } } com Content-Type: application/json.
O servidor tenta a entrega uma única vez (timeout de 10 s). Falhas de entrega são registradas em log, mas não alteram o status do job.
Recomenda-se que o endpoint do webhook responda com 2xx em até 10 s. Para processar o resultado de forma assíncrona, enfileire internamente assim que receber a chamada.

curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"print.send","params":{"document":"rel-abril.pdf"},"callbackUrl":"https://meuservico.com/webhook/jobs"}'

Campos úteis no objeto de job

id, action, params, status
priority, timeout, agentId (preenchido após o encaminhamento)
Instantes em milissegundos: createdAt, dispatchedAt, startedAt, completedAt
result — preenchido quando status é completed; formato depende da ação executada
error — em estados de falha, com code, message e opcionalmente details
progress, progressMessage — durante a execução, quando o agent reporta andamento

Valores típicos de status: pending, dispatched, running, completed, failed, cancelled, timeout, agent_disconnected.

Recursos

Recursos são itens configuráveis (por exemplo, consultas SQL ou templates) associados à sua conta. A API lista e altera apenas o que o token pode acessar.

GET /resources

Lista recursos permitidos para o token.

Parâmetros de consulta

?type=query ou ?type=template — filtra por tipo. Se o tipo não estiver autorizado para o token, a resposta é 403.

Resposta: { "resources": [ ... ] }.

GET /resources/:resourceId

Obtém um recurso pelo identificador. 404 se não existir; 403 se o tipo não for permitido.

PUT /resources/:resourceId

Cria ou atualiza o recurso com o identificador informado. Resposta { "resource": { ... } }.

Corpo JSON

Campo	Obrigatório	Descrição
`type`	sim	`query` ou `template`, conforme autorizado para o token.
`data`	sim	Texto (string) ou objeto JSON (não array).
`description`	não	Descrição legível.
`paramOrder`	não	Lista ordenada de nomes de parâmetros (strings).
`params`	não	Objeto com metadados dos parâmetros.
`targetAgentId`	não	Agente preferencial para execução; use `"*"` ou omita para não restringir a um agente específico.

400 se type ou data forem inválidos; 403 se o tipo não for permitido.

Campos comuns na resposta

resourceId, type, data, updatedAt, updatedBy
Opcionais: description, paramOrder, params, targetAgentId

Erros

As respostas de erro seguem em geral o formato JSON com error e, quando aplicável, message.

HTTP	Significado
`400`	Requisição malformada ou campos obrigatórios ausentes.
`401`	Autenticação ausente ou inválida.
`403`	Operação não permitida para este token.
`404`	Recurso ou job inexistente, ou não visível com este token.
`408`	Timeout síncrono expirou antes do job terminar. O job continua rodando; consulte `GET /jobs/:jobId`.
`500`	Erro no processamento da solicitação.

Exemplo

curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"data.query","params":{"resourceId":"exemplo-consulta"}}'

Voltar ao site

VectorHub

API `/api/v1`

URL base

Autenticação

O que o token permite

Jobs

Corpo JSON

Modos de resposta

Modo síncrono (`sync: true`)

Modo webhook (`callbackUrl`)

Campos úteis no objeto de job

Recursos

Parâmetros de consulta

Corpo JSON

Campos comuns na resposta

Erros

Exemplo

API /api/v1

URL base

Autenticação

O que o token permite

Jobs

Corpo JSON

Modos de resposta

Modo síncrono (sync: true)

Modo webhook (callbackUrl)

Campos úteis no objeto de job

Recursos

Parâmetros de consulta

Corpo JSON

Campos comuns na resposta

Erros

Exemplo

API `/api/v1`

Modo síncrono (`sync: true`)

Modo webhook (`callbackUrl`)