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/sdkNode.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-UsecaseusecaseId : le système (mandat) que sert l’appelX-Azoth-Decision-RefdecisionRef : la décision métier, un identifiant opaqueX-Azoth-Subject-ZonesubjectZone : où se trouvent les personnes concernées — FR, US-CA, EU…X-Azoth-End-UserendUser : le visiteur d’un système public, un identifiant opaque, jamais un e-mailX-Azoth-Challenge-PassedchallengePassed : le nonce d’un challenge que le visiteur a passéX-Azoth-Localeen, fr, es, zh ou arX-Azoth-On-Behalf-OfReç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
apiKeybaseUrlhttps://www.azothos.ai ; votre propre hôte en auto-hébergéworkspaceIdclient.io.* et les simulationsenableTracing · tracertimeoutMsmaxRetriesRetry-AfterAPI 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/completionsPOST /api/v1/chatprovider explicite, des solutions de repli et le streamingPOST /api/v1/infer/resumeGET /api/v1/journalGET /api/v1/journal/export?format=dossierPOST /api/v1/decisions/exportPOST /api/v1/exceptionsPOST /api/v1/insights/{tool}insights:readPOST /api/v1/mcpGET /api/v1/usage · /api/v1/report · /api/v1/budgetsPOST /api/ingestGET /api/proof/keys/{workspaceId}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_failedfield nomme le champ, error dit pourquoi.401402 budget_exceeded202 human_review_requiredapproval_request_id.403policy_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_required429exhaustion_slow ou exhaustion_blocked : retryAfterMs dans le corps, Retry-After dans les en-têtes.503 governance_errorUn 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.