Para Builders

API REST

A API REST e a porta principal para integrar o Daguito ao seu codigo. Voce se autentica com um token Bearer e, dependendo da credencial que usar, pode fazer deploy de fluxos de forma idempotente, alimentar e consultar bases de conhecimento e ler a analise de uso da sua organizacao. Esta pagina documenta apenas os endpoints publicos e verificados.

URL base e autenticacao

Todas as chamadas vao para um unico endpoint de producao:

https://api.daguito.com

Cada requisicao se autentica com um token Bearer no cabecalho Authorization:

Authorization: Bearer <credencial>

Existem tres tipos de credencial, cada uma com seu proprio prefixo:

• dgsk_acc_ — chave de conta, com escopo para toda a organizacao. Use para fazer deploy de fluxos e ler a analise de uso.
• dgpk_flow_ — chave publica de fluxo, restrita a um fluxo especifico.
• dgsk_wh_ — token de webhook, efemero e vinculado a um webhook para streaming no cliente.

O formato de cada token e o prefixo mais 32 caracteres aleatorios em base62. O Daguito guarda apenas o hash SHA-256, nunca o valor em texto puro.

Gestao de chaves de conta

As chaves de conta sao criadas e revogadas pelo painel, nao com outra chave de API. Os endpoints a seguir sao os mesmos que o painel chama: eles se autenticam com a sua sessao de administrador (um JWT de proprietario da organizacao no cabecalho Authorization), nao com um token dgsk_acc_. Cada organizacao pode ter ate 10 chaves ativas.

Listar chaves

Retorna as chaves da organizacao sem o valor em texto puro:

curl -X GET https://api.daguito.com/v1/account/api-keys \
  -H 'Authorization: Bearer <session-jwt>' \
  -H 'Content-Type: application/json'

Criar uma chave

Crie uma chave com um name e, opcionalmente, um monthly_budget_micro_usd (limite de gasto mensal em micro-USD). Responde com 201 e inclui o valor em texto puro uma unica vez.

curl -X POST https://api.daguito.com/v1/account/api-keys \
  -H 'Authorization: Bearer <session-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "production", "monthly_budget_micro_usd": 100000000}'

No exemplo, 100.000.000 micro-USD equivalem a um orcamento mensal de 100 USD.

Revogar uma chave

Revoga uma chave pelo seu id. Responde com 204 sem corpo.

curl -X DELETE https://api.daguito.com/v1/account/api-keys/<id> \
  -H 'Authorization: Bearer <session-jwt>'

Formato da resposta

Cada chave e representada assim (sem o valor em texto puro). key_prefix sao os primeiros 14 caracteres do token — suficientes para identifica-lo em uma lista sem expor o valor inteiro:

{
  "id": "uuid",
  "name": "production",
  "key_prefix": "dgsk_acc_AbC1x",
  "monthly_budget_micro_usd": 100000000,
  "current_mtd_micro_usd": 45230000,
  "created_at": "2026-01-15T10:30:00Z",
  "last_used_at": "2026-06-07T14:22:15Z",
  "revoked_at": null
}

API de Fluxos

Faca deploy de fluxos de forma idempotente a partir do seu codigo ou do seu pipeline de CI. Reenviar o mesmo slug atualiza o fluxo em vez de duplica-lo.

Criar ou atualizar um agente

POST /v1/flows/upsert-agent cria um agente com seu trigger a partir de um modelo (slug, provider, model, system_prompt, ferramentas). Requer uma chave dgsk_acc_.

curl -X POST https://api.daguito.com/v1/flows/upsert-agent \
  -H 'Authorization: Bearer dgsk_acc_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my_agent",
    "name": "My Agent",
    "model": "meta-llama/llama-3.3-70b-instruct",
    "system_prompt": "You are a helpful assistant",
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Enviar um fluxo personalizado

POST /v1/flows/upsert envia um grafo completo. O corpo leva slug, name e um objeto graph com nodes e edges (e um trigger_type opcional). Aceita uma chave dgsk_acc_ ou uma chave sk_dgt_ com escopo flow:admin.

Resolver o webhook de um fluxo

GET /api/sdk/flows?slug=<slug> retorna o flow_id e o token de webhook que seu cliente usa para streaming. Requer uma chave sk_dgt_ com escopo flow:run.

curl -X GET 'https://api.daguito.com/api/sdk/flows?slug=my_agent' \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json'

API de Conhecimento

Alimente suas bases de conhecimento e consulte-as com o mesmo pipeline da Base de Conhecimento que a plataforma usa. O org_id sempre e derivado do token, nunca do corpo da requisicao.

Ingerir texto

POST /api/sdk/knowledge/sources/:id/text ingere texto com metadata opcional. Requer uma chave sk_dgt_ com escopo kb:write.

curl -X POST https://api.daguito.com/api/sdk/knowledge/sources/<id>/text \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Devoluciones en 30 dias.", "metadata": {"lang": "es"}}'

Buscar em uma base

POST /api/sdk/knowledge/search recupera trechos relevantes com query, session_id e opcionais source_ids, top_k, enable_rewrite, enable_rerank e enable_cache. Requer uma chave sk_dgt_ com escopo kb:read.

curl -X POST https://api.daguito.com/api/sdk/knowledge/search \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "how to reset password",
    "top_k": 5,
    "enable_rerank": true,
    "enable_cache": true
  }'

O escopo por recurso e aplicado em cada endpoint: a chave deve ter a permissao de acao correta e estar autorizada para as bases solicitadas. Se uma fonte nao existe ou pertence a outra organizacao, a resposta e 404 (para nao vazar sua existencia); se a chave nao tem escopo, e 403.

Monitoramento e uso

GET /v1/org/analytics retorna um instantaneo de uso da sua organizacao (contadores do dia atual mais a contagem de mensagens enviadas nas ultimas 24 horas). Requer uma chave dgsk_acc_.

curl -X GET https://api.daguito.com/v1/org/analytics \
  -H 'Authorization: Bearer dgsk_acc_...' \
  -H 'Content-Type: application/json'

A resposta inclui:

• LLM — requisicoes, tokens e custo em USD.
• Mensagens — recebidas no dia atual e enviadas nas ultimas 24 horas.
• HTTP — total de chamadas e detalhamento por rota.
• Orcamento — limites e gasto do mes corrente, no nivel da organizacao e da chave.

Tratamento de erros

Os erros sempre retornam como JSON com um unico campo de texto:

{
  "error": "API key required"
}

Codigos de status:

• 400 — falha de validacao (por exemplo, slug mal formado, nome longo demais ou JSON invalido).
• 401 — chave ausente, invalida ou expirada.
• 403 — chave valida mas sem o escopo necessario (de acao ou de recurso).
• 404 — recurso nao encontrado ou acesso negado pela organizacao (para nao revelar sua existencia).
• 500 — erro inesperado do servidor.

Limites de taxa

Os limites de taxa aplicam-se apenas aos endpoints de widget (chat, formulario, carrinho):

• 10 mensagens a cada 60 segundos por sessao.
• 100 mensagens a cada 3600 segundos por IP.

Sao implementados com contadores de janela deslizante. Quando o limite e ultrapassado, a resposta informa quanto esperar, em milissegundos:

{
  "allowed": false,
  "retry_after_ms": 4200
}

Os endpoints de SDK e de administracao nao tem limites por requisicao publicados; o controle e feito por orcamento de gasto.

Credenciais e permissoes

Cada credencial tem um proposito e um escopo distintos:

• Chaves de conta (dgsk_acc_): escopo para toda a organizacao, criadas pelo proprietario. Usadas para fazer deploy de fluxos (upsert-agent / upsert) e ler a analise de uso.
• Chaves de SDK (sk_dgt_): restritas a um fluxo ou a uma base, criadas pelo painel. Sao as chaves que operam sobre o conhecimento e resolvem webhooks. Declaram seu escopo por acao (kb:read, kb:write, flow:run, flow:admin) e por recurso.
• Tokens de webhook (dgsk_wh_): efemeros e vinculados a um webhook especifico, para streaming no cliente sem embutir credenciais sensiveis.

O escopo e aplicado em duas camadas: o middleware verifica o escopo por acao, e o handler confere o escopo por recurso depois que o recurso de destino e resolvido (um valor null equivale a todos os recursos da organizacao).

O que vem agora?