Reference

SDK Reference

Full reference for @azoth/sdk — the Node.js instrumentation package and the v1 REST API.

Installation

npm install @azoth/sdk

Requires Node.js 18+ and an Azoth API key from Dashboard → Settings → Access Control (labelled "Contrôle d'accès" in French). Click Generate credential in the Access Credentials section to mint a key — it starts with az_live_ on paid plans or az_test_ on the free tier.

new AzothClient(config)

Construct the SDK once at boot. The client batches usage events and (optionally) starts an OpenTelemetry tracer for every wrapped provider call.

import { AzothClient } from '@azoth/sdk';

const azoth = new AzothClient({
  apiKey:         process.env.AZOTH_API_KEY,   // required — az_live_… or az_test_…
  baseUrl:        'https://www.azothos.ai',   // optional override (self-hosted)
  workspaceId:    process.env.AZOTH_WORKSPACE_ID, // required for client.io.* and simulate*; resolved from key for track()/flush()
  enableTracing:  true,                        // optional — auto-loads @opentelemetry/api
  // or pass an explicit tracer:
  // tracer:      trace.getTracer('my-service'),
  debug:          false,
  maxBatchSize:   100,
  flushIntervalMs: 5000,
});

wrapOpenAI(client, azoth, ctx?)

Wraps an existing OpenAI instance. Returns a Proxy that intercepts every chat.completions.create + completions.create call.

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

const azoth  = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const openai = wrapOpenAI(new OpenAI(), azoth, {
  provider: 'openai',
  model:    'gpt-4o',
  agentId:  'my-agent',     // optional — ties usage events to this agent
  workflowId: 'support-v2', // optional — multi-step workflow tag
});

wrapAnthropic(client, azoth, ctx?)

Same pattern as wrapOpenAI — wraps an Anthropic client and intercepts messages.create.

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

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

const msg = await anthro.messages.create({
  model: 'claude-opus-4-7',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

Same shape for wrapBedrock, wrapMistral, wrapGemini.

v1 REST API

All endpoints require a Bearer API key: Authorization: Bearer <key>

Base URL: https://www.azothos.ai

POST /api/v1/chat

Unified chat endpoint with automatic provider routing, semantic caching, and streaming support. Available on Pro+ plans.

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer <key>

{
  "provider": "anthropic",          // openai | anthropic | mistral | gemini | azure_openai
  "model": "claude-sonnet-4-6",     //   | openrouter | ollama | deepseek | huggingface
  "messages": [
    { "role": "user", "content": "Summarize this document." }
  ],
  "temperature": 0.7,               // optional, default 0.7
  "maxTokens": 1024,                // optional
  "stream": false,                  // optional — returns SSE stream if true
  "useCache": true,                 // optional — semantic cache lookup
  "fallbackProviders": [            // optional — automatic fallback chain
    { "provider": "openai", "model": "gpt-4o-mini" }
  ]
}

// Non-streaming response
{
  "content": "Here is a summary…",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "usage": {
    "inputTokens": 240,
    "outputTokens": 180,
    "costUsd": 0.00042,
    "latencyMs": 1240,
    "cacheHit": false
  }
}

GET /api/v1/usage

Returns usage traces for the workspace. Paginated, 100 rows max per request.

GET /api/v1/usage?limit=50&offset=0&provider=openai&from=2026-05-01

GET /api/v1/report

Aggregated cost and token report for the workspace.

GET /api/v1/report?period=30d

// Response
{
  "period": "30d",
  "totalCost": 142.80,
  "totalTokens": 12_400_000,
  "cacheHitRate": 0.28,
  "avgLatencyMs": 890,
  "topAgents": [ ... ],
  "byProvider": { "openai": { "cost": 98.20, "calls": 4200 }, ... }
}

GET /api/v1/agents

Lists agents with their accumulated cost and status.

GET /api/v1/export

GDPR Article 20 data portability — exports all workspace traces as JSON or NDJSON. Max 90-day window.

GET /api/v1/export?format=ndjson&from=2026-04-01&to=2026-05-01

Error codes