# @azothos/sdk et l’API REST v1

Deux entrées. Envoyez les appels par la passerelle gouvernée avec n’importe quel client compatible OpenAI — le chemin où les règles s’appliquent et où les décisions sont scellées —, ou déclarez les appels faits ailleurs avec les wrappers du SDK.

## Installation

```
npm install @azothos/sdk
```

Node.js 18 ou plus récent, et une clé API de **Réglages › Accès** (`az_live_…` ou `az_test_…`). Le SDK vérifie la forme de la clé avant toute requête.

## Par la passerelle

Pointez un client OpenAI vers `https://www.azothos.ai/api/v1` — ou vers votre propre hôte, en auto-hébergé. `azothGatewayHeaders` construit les en-têtes Azoth et lève une erreur sur une valeur que la passerelle refuserait :

```
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` : le système (mandat) que sert l’appel
- `X-Azoth-Decision-Ref` — `decisionRef` : la décision métier, un identifiant opaque
- `X-Azoth-Subject-Zone` — `subjectZone` : où se trouvent les personnes concernées — `FR`, `US-CA`, `EU`…
- `X-Azoth-End-User` — `endUser` : le visiteur d’un système public, un identifiant opaque, jamais un e-mail
- `X-Azoth-Challenge-Passed` — `challengePassed` : le nonce d’un challenge que le visiteur a passé
- `X-Azoth-Locale` — la langue d’un refus : `en`, `fr`, `es`, `zh` ou `ar`
- `X-Azoth-On-Behalf-Of` — la personne pour qui l’appel est fait — son identifiant SCIM ou son e-mail —, avec une clé de service autorisée à nommer des personnes ; à poser vous-même ([attribution humaine](https://www.azothos.ai/fr/docs/admin#attribution))

## Reçus

`receiptOf(response | body | headers)` lit un reçu, `decodeReceipt(token)` ses champs, et `verifyReceipt(token, jwks)` vérifie sa signature avec WebCrypto. Depuis le SDK 1.2.0, il refuse aussi un reçu signé au moment ou après la compromission déclarée de sa clé (le `status` et le `compromised_at` de la clé) : les clés de l’espace de travail et leur état sont publiés à `/api/proof/keys/<workspaceId>`.

## Refus et dérogations

`parseRefusal(err)` lit le bloc de refus, `formatRefusal` donne un texte à afficher, `alternativeRequest(option)` les en-têtes et la modification du corps d’une option conforme, et `requestException(…)` demande au responsable de la règle une dérogation limitée dans le temps. Sur un 428, `exhaustionChallengeOf(err)` renvoie le challenge à passer.

```
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',
    });
  }
}
```

## Aussi dans le SDK

- `createClientVault` : gardez le contenu d’un système en mode coffre chiffré avec votre clé, dans votre stockage ; Azoth n’en scelle que les empreintes.
- `groundingSources(passages)` : les passages sur lesquels une réponse doit s’appuyer, pour la vérification d’ancrage.
- `runReferenceSet` : exécutez un jeu de cas de référence gardé dans votre coffre et envoyez son reçu, pour le contrôle des changements de modèle.

## Déclarer les appels faits hors de la passerelle

`wrapOpenAI`, `wrapAnthropic`, `wrapBedrock`, `wrapMistral` et `wrapGemini` enveloppent votre client existant : chaque appel est déclaré à Azoth — coût, latence, tokens — en arrière-plan, avec des spans OpenTelemetry `gen_ai.*` facultatifs. Ces appels sont observés, pas gouvernés : aucune règle ne peut les arrêter.

### 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);
```

### Options du client

- `apiKey` — obligatoire : la clé API de l’espace de travail
- `baseUrl` — par défaut `https://www.azothos.ai` ; votre propre hôte en auto-hébergé
- `workspaceId` — obligatoire pour `client.io.*` et les simulations
- `enableTracing · tracer` — émettre des spans OpenTelemetry
- `timeoutMs` — par tentative, 30 000 par défaut
- `maxRetries` — nombre total de tentatives sur un 429 ou un 5xx, 3 par défaut ; un 429 respecte `Retry-After`

## API REST v1

La plupart des routes `/api/v1` prennent une clé API : `Authorization: Bearer <key>` ou `X-Azoth-API-Key: <key>`. Une clé à portée limitée n’atteint que les routes que ses portées couvrent. Les lectures propres au tableau de bord — `/api/v1/me` et les lectures GreenOps — prennent une session connectée à la place, jamais une clé. Chaque route, son authentification, ses champs et ses réponses figurent dans la [référence de l’API](https://www.azothos.ai/fr/docs/api), aussi publiée sous forme de fichier OpenAPI.

- `POST /api/v1/chat/completions` — La passerelle gouvernée, compatible OpenAI
- `POST /api/v1/chat` — La passerelle gouvernée avec un `provider` explicite, des solutions de repli et le streaming
- `POST /api/v1/infer/resume` — Exécuter un appel mis en attente une fois qu’il est approuvé
- `GET /api/v1/journal` — Les décisions scellées
- `GET /api/v1/journal/export?format=dossier` — Le dossier d’audit, en ZIP
- `POST /api/v1/decisions/export` — Un dossier de décision, par référence de décision
- `POST /api/v1/exceptions` — Demander une dérogation à partir d’un refus
- `POST /api/v1/insights/{tool}` — Les outils de lecture de l’assistant, avec la portée `insights:read`
- `POST /api/v1/mcp` — La passerelle MCP gouvernée, avec une clé liée à un agent
- `GET /api/v1/usage · /api/v1/report · /api/v1/budgets` — L’usage, le rapport de dépenses, les budgets
- `POST /api/ingest` — Déclarer les appels faits hors de la passerelle
- `GET /api/proof/keys/{workspaceId}` — Les clés publiques de l’espace de travail (JWKS), sans clé 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" }]
}
```

## Réponses à prévoir

- `400 validation_failed` — Le corps n’a pas passé la validation : `field` nomme le champ, `error` dit pourquoi.
- `401` — La clé API est absente, invalide ou révoquée.
- `402 budget_exceeded` — Un budget a refusé l’appel avant le modèle.
- `202 human_review_required` — Mis en attente pour une personne ; reprenez-le avec son `approval_request_id`.
- `403` — Une règle l’a refusé : `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 système public demande au visiteur de passer un challenge.
- `429` — Une limite de débit, `exhaustion_slow` ou `exhaustion_blocked` : `retryAfterMs` dans le corps, `Retry-After` dans les en-têtes.
- `503 governance_error` — La gouvernance n’a pas pu s’exécuter et le déploiement refuse par défaut : réessayez.

> Un refus de gouvernance est scellé et porte son reçu. Les refus pour épuisement des coûts sont comptés à la place, et scellés à chaque changement de palier. Chaque `code` est expliqué dans [Codes d’erreur](https://www.azothos.ai/fr/docs/errors), où mène le `doc_url` d’une réponse.
