voltarAthelium · docs
Suporte técnico
Documentação

HTTP direto

Endpoints REST com auth via API key. Adequado pra automações server-side, jobs, microsserviços. Use /compose pra levar o contexto pra qualquer LLM (recomendado), ou /serve pra obter resposta direta sem outro LLM downstream.

Autenticação

Três formas, em ordem de recomendação. Detalhes e boas práticas em autenticação.

http
# 1. Header Bearer (recomendado)
Authorization: Bearer <sua_api_key>

# 2. Header customizado
X-API-Key: <sua_api_key>

# 3. Query param (último recurso)
?api_key=<sua_api_key>

POST /api/v1/compose

Devolve o contexto curado relevante ao intent, estruturado em markdown.

curlbash
curl -X POST https://gateway.athelium.com.br/api/v1/compose \
  -H "Authorization: Bearer <sua_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Como qualifico um lead inbound?"
  }'

Retorna:

json
{
  "execution_id": "904add19-b7b1-4c9f-...",
  "composed_context": "## Contexto da empresa\n\n### Perfil\n...\n_fonte: skill_id=...",
  "skills_used": ["af499ec8-...", "51e7c053-..."],
  "tokens_in": 1185,
  "tokens_out": 1264,
  "cached": false,
  "latency_ms": 1820
}
  • composed_context — string markdown pronta pra dropar no LLM
  • skills_used — IDs das skills incluídas (proveniência)
  • execution_id — guarde se quer mandar feedback depois
  • cached — true se a resposta veio do cache (latência baixa)
  • latency_ms — tempo de resposta do framework

POST /api/v1/serve

Conveniência: compose + resposta gerada pelo modelo do framework numa chamada. Use quando o objetivo é resposta direta, sem mandar contexto pra outro LLM downstream.

curlbash
curl -X POST https://gateway.athelium.com.br/api/v1/serve \
  -H "Authorization: Bearer <sua_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Como qualifico um lead inbound?"
  }'

Retorna o mesmo shape do compose, mais answer (resposta formatada) e serve_execution_id.

Python (httpx)

compose.pypython
import os
import httpx

API_KEY = os.environ["SKILLS_API_KEY"]
GATEWAY = os.environ.get("SKILLS_GATEWAY", "https://gateway.athelium.com.br")

async def compose_context(intent: str) -> str:
    async with httpx.AsyncClient(timeout=60) as client:
        r = await client.post(
            f"{GATEWAY}/api/v1/compose",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"intent": intent},
        )
        r.raise_for_status()
        return r.json()["composed_context"]

# Use o contexto em qualquer LLM:
context = await compose_context("Como qualifico um lead?")
# → manda para Claude / GPT / Gemini com seu prompt do sistema

Node (fetch)

compose.jsjavascript
const API_KEY = process.env.SKILLS_API_KEY;
const GATEWAY = process.env.SKILLS_GATEWAY ?? "https://gateway.athelium.com.br";

async function composeContext(intent) {
  const r = await fetch(`${GATEWAY}/api/v1/compose`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ intent }),
  });
  if (!r.ok) throw new Error(`compose failed ${r.status}`);
  const { composed_context } = await r.json();
  return composed_context;
}

Limites e cache

60 requests/min por API key. Excedeu → 429 Too Many Requests com header Retry-After.

Chamadas idênticas (mesmo intent + mesma seleção de skills) saem do cache em <100ms dentro de 1h. Detalhes completos em erros & limites.

Erros mais comuns

Tabela completa em erros & limites. Os mais frequentes:

StatusQuando
400Sem cobertura de skills para essa intent. Reescreva com mais especificidade ou reporte à curadoria.
401API key ausente ou inválida.
403empresa_id no body não bate com o dono da key (defesa multi-tenant).
429Rate limit estourado. Aguarde e tente novamente.

Próximos passos