Empezar gratis →

SDK y CLI

@azothos/sdk y la API REST v1

Dos vías de entrada. Envía las llamadas a través de la pasarela gobernada con cualquier cliente compatible con OpenAI — la vía en la que se aplican las reglas y se sellan las decisiones — o notifica las llamadas hechas en otros lugares con los wrappers del SDK.

Instalación

npm install @azothos/sdk

Node.js 18 o posterior, y una clave API de Ajustes › Acceso (az_live_… o az_test_…). El SDK comprueba la forma de la clave antes de cualquier petición.

A través de la pasarela

Apunta un cliente de OpenAI a https://www.azothos.ai/api/v1 — o a tu propio host, si es autoalojado. azothGatewayHeaders construye las cabeceras de Azoth y lanza un error ante un valor que la pasarela rechazaría:

import OpenAI from 'openai';
import { azothGatewayHeaders } from '@azothos/sdk';

const openai = new OpenAI({
  baseURL: 'https://www.azothos.ai/api/v1',
  apiKey: process.env.AZOTH_API_KEY,
  defaultHeaders: azothGatewayHeaders({ usecaseId }),
});

await openai.chat.completions.create(body, {
  headers: azothGatewayHeaders({ decisionRef: creditFileId, subjectZone: 'FR' }),
});
X-Azoth-Usecase
usecaseId: el sistema (mandato) al que sirve la llamada
X-Azoth-Decision-Ref
decisionRef: la decisión de negocio, un id opaco
X-Azoth-Subject-Zone
subjectZone: dónde están las personas afectadas — FR, US-CA, EU…
X-Azoth-End-User
endUser: el visitante de un sistema público, un id opaco, nunca un correo electrónico
X-Azoth-Challenge-Passed
challengePassed: el nonce de una verificación que el visitante superó
X-Azoth-Locale
el idioma de un rechazo: en, fr, es, zh o ar
X-Azoth-On-Behalf-Of
la persona para quien se hace la llamada — su id SCIM o su e-mail —, con una clave de servicio autorizada a nombrar personas; ponla tú mismo (atribución humana)

Recibos

receiptOf(response | body | headers) lee un recibo, decodeReceipt(token) sus campos (claims) y verifyReceipt(token, jwks) comprueba su firma con WebCrypto. Desde el SDK 1.2.0 también rechaza un recibo firmado en el momento o después del compromiso declarado de su clave (el status y el compromised_at de la clave): las claves del espacio de trabajo y su estado se publican en /api/proof/keys/<workspaceId>.

Rechazos y dispensas

parseRefusal(err) lee el bloque de rechazo, formatRefusal da un texto para mostrar, alternativeRequest(option) las cabeceras y el cambio de cuerpo de una opción conforme, y requestException(…) pide al propietario de la regla una dispensa por tiempo limitado. Ante un 428, exhaustionChallengeOf(err) devuelve la verificación que hay que superar.

import { parseRefusal, formatRefusal, alternativeRequest, requestException } from '@azothos/sdk';

try {
  await openai.chat.completions.create(body, { headers: { 'X-Azoth-Locale': 'fr' } });
} catch (err) {
  const refusal = parseRefusal(err);
  if (!refusal) throw err;
  showToUser(formatRefusal(refusal));
  const option = refusal.alternatives[0];
  if (option) {
    const { headers, body: change } = alternativeRequest(option);
    await openai.chat.completions.create({ ...body, ...change }, { headers });   // governed again in full
  } else if (refusal.exception.available) {
    await requestException({
      apiKey: process.env.AZOTH_API_KEY,
      refusal,
      justification: 'Quarter-end audit needs this model this week',
    });
  }
}

También en el SDK

  • createClientVault: conserva el contenido de un sistema en modo bóveda cifrado con tu clave, en tu almacenamiento; Azoth solo sella los hashes.
  • groundingSources(passages): los pasajes en los que debe basarse una respuesta, para la comprobación de anclaje.
  • runReferenceSet: ejecuta un conjunto de referencia guardado en tu bóveda y envía su recibo, para el control de cambios de modelo.

Notificar llamadas hechas fuera de la pasarela

wrapOpenAI, wrapAnthropic, wrapBedrock, wrapMistral y wrapGemini envuelven tu cliente existente: cada llamada se notifica a Azoth — coste, latencia, tokens — en segundo plano, con spans OpenTelemetry gen_ai.* opcionales. Estas llamadas se observan, no se gobiernan: ninguna regla puede detenerlas.

wrapOpenAI

import OpenAI from 'openai';
import { AzothClient, wrapOpenAI } from '@azothos/sdk';

const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const openai = wrapOpenAI(new OpenAI(), azoth, {
  provider: 'openai',
  model: 'gpt-4o-mini',
  agentId: 'support-bot',        // the spend line it is attributed to
  workflowId: 'ticket-triage',
});

wrapAnthropic

import Anthropic from '@anthropic-ai/sdk';
import { AzothClient, wrapAnthropic } from '@azothos/sdk';

const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const anthropic = wrapAnthropic(new Anthropic(), azoth);

Opciones del cliente

apiKey
obligatorio: la clave API del espacio de trabajo
baseUrl
por defecto https://www.azothos.ai; tu propio host si es autoalojado
workspaceId
obligatorio para client.io.* y las simulaciones
enableTracing · tracer
emitir spans de OpenTelemetry
timeoutMs
por intento, 30 000 por defecto
maxRetries
intentos totales ante un 429 o un 5xx, 3 por defecto; un 429 respeta Retry-After

API REST v1

La mayoría de las rutas /api/v1 requieren una clave API: Authorization: Bearer <key> o X-Azoth-API-Key: <key>. Una clave con ámbitos solo alcanza las rutas que corresponden a sus ámbitos. Las lecturas propias del panel — /api/v1/me y las lecturas de GreenOps — requieren en cambio una sesión iniciada, nunca una clave. Cada ruta, cómo se autentica, sus campos y sus respuestas están en la referencia de la API, publicada también como archivo OpenAPI.

POST /api/v1/chat/completions
La pasarela gobernada, compatible con OpenAI
POST /api/v1/chat
La pasarela gobernada con un provider explícito, alternativas de respaldo y streaming
POST /api/v1/infer/resume
Ejecutar una llamada retenida una vez aprobada
GET /api/v1/journal
Las decisiones selladas
GET /api/v1/journal/export?format=dossier
El expediente de auditoría, como ZIP
POST /api/v1/decisions/export
Un expediente de decisión, por referencia de decisión
POST /api/v1/exceptions
Pedir una dispensa a partir de un rechazo
POST /api/v1/insights/{tool}
Las herramientas de lectura del asistente, con el ámbito insights:read
POST /api/v1/mcp
La pasarela MCP gobernada, con una clave vinculada a un agente
GET /api/v1/usage · /api/v1/report · /api/v1/budgets
El uso, el informe de gasto, los presupuestos
POST /api/ingest
Notificar llamadas hechas fuera de la pasarela
GET /api/proof/keys/{workspaceId}
Las claves públicas del espacio de trabajo (JWKS), sin clave API
POST /api/v1/chat
Authorization: Bearer <key>

{
  "provider": "anthropic",             // openai | anthropic | mistral | gemini | azure_openai
  "model": "claude-haiku-4-5",         // | openrouter | ollama | deepseek | huggingface | internal
  "messages": [{ "role": "user", "content": "Summarise this document." }],
  "maxTokens": 1024,
  "stream": false,
  "fallbackProviders": [{ "provider": "mistral", "model": "mistral-small-latest" }]
}

Respuestas que cabe esperar

400 validation_failed
El cuerpo no superó la validación: field nombra el campo y error dice por qué.
401
La clave API falta, no es válida o está revocada.
402 budget_exceeded
Un presupuesto rechazó la llamada antes del modelo.
202 human_review_required
Retenida para una persona; reanúdala con su approval_request_id.
403
Una regla la rechazó: policy_blocked, usecase_unresolved, usecase_not_approved, usecase_prohibited, usecase_archived, mandate_suspended, mandate_expired, kill_switch_active, jurisdiction_blocked, sovereignty_blocked, egress_blocked…
428 exhaustion_challenge_required
Un sistema público pide al visitante que supere una verificación.
429
Un límite de frecuencia, exhaustion_slow o exhaustion_blocked: retryAfterMs en el cuerpo, Retry-After en las cabeceras.
503 governance_error
La gobernanza no pudo ejecutarse y el despliegue falla en modo cerrado: inténtalo de nuevo.

Un rechazo de gobernanza se sella y lleva su recibo. Los rechazos por agotamiento de costes, en cambio, se cuentan y se sellan en cada cambio de nivel. Cada code se explica en Códigos de error, adonde lleva el doc_url de una respuesta.