# @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](https://www.azothos.ai/es/docs/admin#attribution))

## 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](https://www.azothos.ai/es/docs/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](https://www.azothos.ai/es/docs/errors), adonde lleva el `doc_url` de una respuesta.
