Developer API

Integra Alhelí en tu producto.

Si construyes un backend, agente o app que necesita consultar la legislación y jurisprudencia de LATAM, autentica con una API key sobre el mismo endpoint MCP. Empiezas con 10 consultas gratis cada mes; después, $0.01 por llamada con saldo prepagado (recarga mínima $5.00, el saldo no expira).

Precio

llamadas gratis / mes calendario UTC

$0.01

por llamada exitosa tras el límite gratis

$5.00

recarga mínima — el saldo no expira

Solo se cobra status="ok". Errores del servidor y excepciones se reembolsan automáticamente al saldo.
Tienes Pro/Estudio? Las llamadas con API key cuentan contra tu cuota mensual del plan, no contra el saldo.
Cobro upfront atómico. Reservamos el costo antes de ejecutar; nunca te quedas con balance negativo.
Movimientos auditables. Cada top-up, debit y refund queda en tu ledger visible en el panel.

Tres pasos.

01
Crea una API key
En /dashboard/api. Le pones un nombre (ej. "backend prod") y copias el secreto — sólo se muestra una vez.
02
(Opcional) Recarga saldo
Las primeras 10 llamadas del mes son gratis. Si vas a superar, recarga desde $5.00 con Stripe Checkout.
03
Envía requests JSON-RPC
Mismo wire format que usan Claude / ChatGPT / Gemini. Sin SDK específico — cualquier cliente HTTP sirve.

Endpoint y autenticación

Bearer alh_live_…

https://connector.alheli.ai/api/mcp

Header obligatorio: Authorization: Bearer alh_live_…
Content-Type: application/json
Protocolo: MCP 2026-03-26
Método: POST (JSON-RPC 2.0)

Ejemplos.

1 · Listar tools disponibles

curl -X POST https://connector.alheli.ai/api/mcp \
  -H "Authorization: Bearer $ALHELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

2 · Llamar a un tool (search_normativa)

curl -X POST https://connector.alheli.ai/api/mcp \
  -H "Authorization: Bearer $ALHELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"ec_legislacion_search_normativa",
      "arguments":{"query":"prescripción extintiva en materia civil"}
    }
  }'

3 · Python (httpx)

import os, httpx

API = "https://connector.alheli.ai/api/mcp"
headers = {"Authorization": f"Bearer {os.environ['ALHELI_API_KEY']}"}

def call_tool(name: str, arguments: dict):
    payload = {
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": name, "arguments": arguments},
    }
    r = httpx.post(API, headers=headers, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["result"]

result = call_tool(
    "ec_legislacion_search_jurisprudencia",
    {"query": "responsabilidad extracontractual del Estado"},
)
for chunk in result["structuredContent"]["chunks"]:
    print(chunk["numero"], "—", chunk["resumen"][:120])

4 · Node.js (fetch nativo)

const API = "https://connector.alheli.ai/api/mcp";

async function callTool(name, args) {
  const res = await fetch(API, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.ALHELI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0", id: 1, method: "tools/call",
      params: { name, arguments: args },
    }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const { result, error } = await res.json();
  if (error) throw new Error(error.message);
  return result;
}

const out = await callTool("ec_legislacion_search_normativa", {
  query: "requisitos para divorcio por mutuo consentimiento",
});
console.log(out.structuredContent.chunks);

Forma de la respuesta

Chunks rankeados con metadata.

Cada tool devuelve un bloque content de texto (para clientes MCP genéricos) y un structuredContent con los chunks tipados — eso es lo que probablemente quieres consumir. Detalle de campos por tool en Referencia MCP.

{
  "jsonrpc": "2.0", "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "3 fragmentos…" }],
    "structuredContent": {
      "count": 3,
      "chunks": [
        {
          "rank": 1, "score": 0.214,
          "legislation_title": "Código Civil",
          "article_text": "Art. 2414.- La prescripción…"
        }
      ]
    }
  }
}

Errores

Códigos y qué hacer.

HTTP / JSON-RPC	Significado	Qué hacer
401 invalid_token	Bearer ausente / mal formado / revocado.	Revisa el header. Si la key fue revocada, crea otra.
isError + insufficient_credits	Sin saldo y sin free calls.	Recarga desde $5.00 en /dashboard/api.
isError + quota_exceeded	Solo en tier Pro/Estudio agotado.	Espera al ciclo siguiente o sube de plan.
-32601 method not found	Método JSON-RPC inválido.	Solo usamos tools/list, tools/call, initialize, ping.
-32603 internal error	Falla del servidor / tool.	Reintenta. El saldo NO se debita en error.

Buenas prácticas

Producción.

Una key por entorno. Separa dev / staging / prod para revocar quirúrgicamente si algo se filtra. Máximo 10 keys activas por cuenta.
Nunca embebas la key en el cliente. Siempre proxy desde tu backend; expón endpoints de tu propio dominio.
Cachea según query. Las respuestas son estables salvo cambios normativos — cachear consultas idénticas por horas baja tu costo a un fracción.
Monitorea el saldo. El panel /dashboard/api muestra balance y ledger. Para automatizar alertas, recarga cuando el saldo esté por debajo de un umbral cómodo.
Reintentos con backoff. Si recibes 5xx, reintenta con backoff exponencial. Los errores no debitan saldo, así que reintentar es seguro.