Démarrer gratuitement →

SDK et CLI

@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)

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, 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, où mène le doc_url d’une réponse.