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.
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_….
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.00000330Change 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'));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"))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.
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:
- The key and the body are checked. A system exposed to the public gets its cost-exhaustion tier first (public systems).
- The call is bound to its mandate: the
X-Azoth-Usecaseheader, else the agent, the connector or the key it is bound to, else the workspace default. - The rules run: the emergency stop, the mandate’s state, budgets, sovereignty, policy rules, the applicable law, human approval.
- The model answers, on the provider the rules allow. Routing and the cache are enrichments, inside those rules.
- 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.