Start free →

Getting started

Quick start

Send your first call through the Azoth gateway, keep its receipt and find its sealed decision — in about five minutes, without changing your prompts.

You need an Azoth workspace and a provider key saved in Settings › Providers and models. The SDK examples need Node.js 18 or later.

Create a free account →

Create an API key

In Settings › Access, create an API key and copy it into AZOTH_API_KEY: it is shown once. Free workspaces get az_test_… keys, paid plans az_live_….

Send a call through the gateway

The gateway speaks the OpenAI chat format at /api/v1/chat/completions. -D - prints the response headers, where the receipt rides.

curl -sS -D - https://www.azothos.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $AZOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Say hello in one word." }]
  }'

# HTTP/2 200
# x-azoth-receipt: eyJhbGciOiJFZERTQSIs…
# x-azoth-provider: openai
# x-azoth-model: gpt-4o-mini
# x-azoth-cost-usd: 0.00000330
Or point your OpenAI client at Azoth

Change the base URL and the key — nothing else in your code. azothGatewayHeaders from @azothos/sdk adds the optional Azoth headers and refuses a value the gateway would refuse. .withResponse() also gives you the response headers, where the receipt rides.

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: process.env.AZOTH_USECASE_ID }),
});

const { data, response } = await openai.chat.completions
  .create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Say hello in one word.' }],
  })
  .withResponse();

console.log(data.choices[0].message.content);
console.log(response.headers.get('x-azoth-receipt'));
Or from Python

The openai package works the same way: change base_url and the key. with_raw_response keeps the response headers, where the receipt rides.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.azothos.ai/api/v1",
    api_key=os.environ["AZOTH_API_KEY"],
)

raw = client.chat.completions.with_raw_response.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(raw.parse().choices[0].message.content)
print(raw.headers.get("x-azoth-receipt"))
Keep the receipt

Every answer that is not streamed, served or blocked, carries a signed receipt in X-Azoth-Receipt — and in azoth.receipt in a served JSON body. It names the decision without any content: keep it with your records. A streamed answer carries X-Azoth-Trace-Id instead: its decision is sealed when the stream ends.

Find the decision

In Proof › Decisions the call appears with its outcome, its rules and its law. Verify it yourself opens the offline verifier: paste the receipt, choose the dossier.

How it works

A call through the gateway goes through these steps, in this order:

  1. The key and the body are checked. A system exposed to the public gets its cost-exhaustion tier first (public systems).
  2. The call is bound to its mandate: the X-Azoth-Usecase header, else the agent, the connector or the key it is bound to, else the workspace default.
  3. The rules run: the emergency stop, the mandate’s state, budgets, sovereignty, policy rules, the applicable law, human approval.
  4. The model answers, on the provider the rules allow. Routing and the cache are enrichments, inside those rules.
  5. The decision is sealed in the workspace’s hash-chained journal — refusals included — and the answer leaves with its receipt.

Governance profiles

How strictly a call without an approved mandate is handled follows the governance mode: the stricter of the deployment’s (GOVERNANCE_PROFILE) and the one the workspace chose in Settings › Organization — a workspace can tighten it, never loosen it (governance mode). observe, the default, seals and serves; govern also alerts; enforce refuses. A stopped mandate, and a system classified as a prohibited practice, are refused in every mode.

Next