ZUGER API

One API.
A whole back office.

Brief an agent in plain words, read the Run it made, and subscribe to what happens. Approvals and the audit trail come with it.

import os, requests

base = "https://beta.zuger.ai/v1"
auth = {"Authorization": "Bearer " + os.environ["ZUGER_KEY"]}

# brief an agent in plain words: the words become one Run
requests.post(base + "/briefs", headers=auth, json={
    "agent": "LEDGER",
    "text": "Where does cash stand this week?",
}).raise_for_status()

# then read the Runs, newest first
for run in requests.get(base + "/runs", headers=auth).json()["runs"]:
    print(run["agent"], run["status"], run["title"])

# LEDGER RUNNING Where does cash stand this week?
const base = "https://beta.zuger.ai/v1";
const headers = {
  Authorization: `Bearer ${process.env.ZUGER_KEY}`,
  "Content-Type": "application/json",
};

// brief an agent in plain words: the words become one Run
await fetch(`${base}/briefs`, {
  method: "POST", headers,
  body: JSON.stringify({ agent: "LEDGER", text: "Where does cash stand this week?" }),
});

// then read the Runs, newest first
const { runs } = await (await fetch(`${base}/runs`, { headers })).json();
for (const r of runs) console.log(r.agent, r.status, r.title);
# live today: brief an agent, then read the Run it made
curl https://beta.zuger.ai/v1/briefs \
  -H "Authorization: Bearer $ZUGER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "LEDGER",
    "text": "Where does cash stand this week?"
  }'

curl https://beta.zuger.ai/v1/runs \
  -H "Authorization: Bearer $ZUGER_KEY"

Quickstart

Brief, read, subscribe. The agent reads the tools your company connected, each scoped, for reading and revocable, and every consequential action lands in your approvals rather than in production.

pip install zuger COMING
npm i @zuger/sdk COMING

TypeScript and Python clients are written, and not yet published. Until they are, call the API directly: every tab above is a call you can make now.

CORE OBJECTS

Five nouns,
and that is the whole model.

ObjectWhat it is
CompanyYour tenant. Holds entities, connected tools, memory and the audit log.
AgentOne of the ten, on shift or not, with the standing mandate a person gave it in the Console.
RunOne execution of a brief. Has steps, an answer and any document, and a status such as DONE, BLOCKED, AWAITING_APPROVAL, AWAITING_INPUT, STOPPED_BY_BERNINA or HELD_BY_BERNINA.
ApprovalA stop. Carries the proposed action, the reasoning and the evidence. Only a human resolves it.
RoutineA brief on a schedule.

THE RUN OBJECT

What comes back
when you fetch a run.

Bernina's three decisions ride on every run. They are read-only via the API; they cannot be overridden programmatically.

{
  "runId": "run_01j9x",
  "agentKind": "LEDGER",
  "title": "Where does cash stand this week?",
  "status": "AWAITING_APPROVAL",   // DONE | BLOCKED | AWAITING_APPROVAL | AWAITING_INPUT | STOPPED_BY_BERNINA | HELD_BY_BERNINA | …
  "bernina": {
    "pre": { "decision": "pass" },
    "inRun": { "decision": "pass" },
    "post": { "decision": "redact" }
  }
}

A FINDING, WITH ITS CITATIONS

Every finding cites
what it rests on.

Audit-ready findings, as GET /v1/findings returns them. A finding cites at least two artefacts, never an earlier finding, and says what contradicts what. One that does not is never written.

Example response

// GET /v1/findings
{
  "state": { "state": "READY" },
  "findings": [{
    "id": "fnd_01jb2k",
    "agentKind": "LEDGER",
    "check": "vendor_anomaly",
    "severity": "urgent",
    "claim": "Invoice 2026-118 names a different bank account from the one Northwind GmbH was paid to in August.",
    "evidence": [
      { "kind": "INVOICE", "id": "inv_2026_118" },
      { "kind": "BANK_TRANSACTION", "id": "txn_08_4471" }
    ],
    "proposedAction": "Confirm the new account with Northwind on a number you already have.",
    "createdAt": "2026-10-03T08:12:00Z",
    "verdict": null,
    "runId": "run_01j9x",
    "entityId": null,
    // planned shape, not in the API yet
    "graphPath": [
      { "from": "vendor:northwind", "edge": "PAID_TO", "to": "account:ch93-…-4471", "cites": "txn_08_4471" },
      { "from": "vendor:northwind", "edge": "BILLED", "to": "invoice:2026-118", "cites": "inv_2026_118" },
      { "from": "invoice:2026-118", "edge": "NAMES", "to": "account:de89-…-0130", "cites": "inv_2026_118" }
    ]
  }]
}

The graph path is the planned shape, not in the API yet.Coming soon

Coming soon: what Säntis found. The scheduled check isn’t connected to your data yet, so this is usually empty.

HOW ZUGER RUNSComing soon

The runtime
behind the super-agent.

What the platform is building, part by part. Each part says when it is not live yet.

Coordinator

One coordinator decides where each piece of work goes, and each piece runs as its own Run. There is no sharding yet.

Coming soon

Threads

One conversation across every channel, passing through to each Worker what it needs.

Coming soon

Two-stage event filtering

Rules first, then a model only for what is left, so noise starts no Run.

Coming soon

Inline & Spill, Chain of Recall

Context is loaded in steps: what fits goes inline, the rest is spilled to a store the Worker recalls from.

Coming soon

Full-duplex Runs

A Run takes new instructions while it runs, “only the third quarter” or “stop”, without starting over.

Coming soon

Watchdog

Work that stalls is noticed and picked up again on its own.

Coming soon

Stateless runtime

Any Worker can take any step. Nothing lives only in one process.

Coming soon

Graph engineering

Every Run is a governed execution graph. The rules are enforced by the graph, not by prompts.

Coming soon

Company knowledge graph

Vendors, contracts, invoices, payments and filings, with the source of every edge.

Coming soon

Graph tools

Tools for agents to reason over the graph: neighbors · timeline · path · anomalies · cite

Coming soon

Evals in CI

An eval suite for every agent, run on every change, with accuracy and calibration tracked.

Coming soon

ZAP and KYA

Verified work between agents of different companies, through the Zuger Agent Protocol.

Coming soon

Zuger Score standard

An open, versioned way to compute the score, which anyone can check.

Coming soon

The Zuger Agent Protocol · The open Zuger Score standard

ENDPOINTS

The ones you will
actually call.

MethodPathDoes
POST/v1/briefsBrief an agent in plain words; the words become one Run
GET/v1/runsList Runs, newest first
GET/v1/runs/:idFetch a Run: its steps, its answer and any document
GET/v1/agentsList agents and whether each is on shift
GET/v1/approvalsEverything waiting on a human. Read only: no key can decide
POST/v1/routinesSchedule a brief to run every day, week or month
GET/v1/memoryRead company memory
GET/v1/audit/exportThe hash-chained audit log, oldest first. Zuger Max and Zuger Ultra
POST/v1/webhooksAdd an address of your own for Zuger to call

Every route, and the ones no key can call, are in the API reference: who may call each one, what it reads and a curl example, generated from the OpenAPI document.

Full reference

ERRORS

Every refusal has a code,
so your app can say it its way.

An error is one object, error, the same on every route. Its type is the kind of failure and its message the whole sentence, in English. A refusal a customer can meet also carries a stable code, and the values its sentence holds in params.

# POST /v1/routines with "schedule": { "every": "day", "hour": 25 }
{
  "error": {
    "type": "bad_request",
    "message": "The hour must be a whole number from 0 to 23.",
    "code": "schedule_part_whole_number",
    "params": { "part": "hour", "min": "0", "max": "23" },
    "field": "schedule"
  }
}
const WORDS = {
  schedule_part_whole_number: "{part}: from {min} to {max}.",
  agent_not_shift_put_shift: "Put that agent on shift first.",
};
const PARTS = { hour: "Hour", minute: "Minute" };

function say(e) {
  const words = WORDS[e.code];
  if (!words) return e.message; // unknown code: the English
  const p = { ...e.params };
  if (p.part) p.part = PARTS[p.part] ?? p.part;
  return words.replace(/\{(\w+)\}/g, (_, k) => p[k] ?? "");
}

Match the code, never the words

A code never changes meaning. When the English is reworded, the code stays; a new sentence gets a new code. So match on code, never on message.

Say it in your own words

Keep your own wording for the codes your app meets, and fill in params by name. A value chosen from a short list (an approval’s state, a category, a part of a schedule) arrives as a code of its own, several joined by commas.

The message stays English

The API speaks English. message is the full sentence with its values in it: show it when your app meets a code it does not know yet.

Not every error has a code

A code comes with the refusals a customer can meet. Where there is none, type and message are all there is. A 429 also sends Retry-After.

The Console does it this way

The Console says every code in eight languages exactly like this: the code, its params, the reader’s dictionary, and the English when a code is new.

Every code, in one list

The API reference lists every code with its English, the params it carries and the values those can take. See the error codes.

OPPORTUNITIES · COMING ONLINE

Dom’s Opportunities,
over the API.

Built, and switched on one company at a time. Where a company does not have it yet, the first route below answers that it is not available, and the other four refuse with 403.

MethodPathDoesScope
GET/v1/opportunitiesThe latest brief: what changed, the signals with links to their records, three to five ideas, and the ones you saved or are testingruns:read
POST/v1/opportunities/briefsAsk Dom for a brief now, with an optional focus. 3 Runs, 5 with web research (6 on Max and Ultra); the first one is free (on the Free plan it starts once your email address is confirmed)runs:write
POST/v1/opportunities/cards/:id/decisionSave an idea, or say it is not for you, with an optional noteruns:write
POST/v1/opportunities/cards/:id/preparePrepare an idea’s first test: one brief to each agent that prepares something for it, 1 Run eachruns:write
PATCH/v1/opportunities/settingsHow often, which levels, and whether it researches the web. An owner or admin, signed inNo API key

An idea is words. What a test needs is proposed by the agents and approved by a person, as every proposal is: nothing here sends, posts or pays. What the brief is.

WEBHOOKS

Subscribe to the moments
that matter.

EventFires when
run.finishedAn agent finished a Run, or stopped to wait for a decision
run.failedA Run could not finish
approval.createdSomething consequential is waiting on a human
approval.decidedA human approved or rejected it
approval.doneA human marked what they approved as carried out

Calls carry ids and states only, and are signed: X-Zuger-Signature: t=…,v1=…, where v1 is HMAC-SHA256 of t + "." + body with the secret shown once when you add the address. A failed call is retried five times; an address that keeps failing is switched off.

MCP

The same store,
as a tool server.

Zuger speaks the Model Context Protocol at beta.zuger.ai/mcp: Streamable HTTP, one JSON-RPC message per request, no session. With a key it is a bearer; without one, OAuth 2.1 with dynamic client registration and PKCE, which is how Claude and ChatGPT connect a person. The metadata is at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp.

ToolDoesScope
brief_agentHand an agent work in plain words; the words become one Runruns:write
list_runs · get_runRuns, and one Run in full: steps, answer, documents, Bernina’s verdicts, approvalsruns:read
whats_waiting · list_approvals · get_approvalWhat is waiting on a person. Read only, with the Console link to decideapprovals:read
list_routines · create_routine · pause_routineStanding instructions on a scheduleroutines:*
list_memory · rememberCompany memory, read and added tomemory:*
list_agents · list_findings · export_auditWho is on shift; what Säntis found (coming soon); the hash-chained logagents:read · findings:read · audit:read

There is no tool that approves, signs, files, pays, hires, connects a tool or changes billing, and the server’s instructions say so to the model before it does anything. A person connecting from Claude sees the same list, in plain words, on the Zuger in Claude page; the full technical page is Zuger MCP.

claude mcp add --transport http zuger https://beta.zuger.ai/mcp \
  --header "Authorization: Bearer $ZUGER_KEY"

THE RULES

What the API
will not let you do.

0KEYS THAT CAN APPROVE, SIGN, FILE OR PAY

You cannot approve via the API as an agent

Approval endpoints require a human session token. A machine token can read the queue but never resolve it.

You cannot change a mandate from inside a run

Mandates are edited by people, in the Console. An agent asking to change its own mandate is itself an escalation.

There is no sandbox, on purpose

Every key is live, and the gate is what keeps it from anything binding: no key can approve, sign, file or pay. To try things, make a second company on the Free plan and load a month of example data from Settings → Connectors; the agents are told it is example data.

Rate limits are per company

New Runs: from 10 a minute on Free to 300 on Ultra. Every 429 tells you when to retry.

Errors say what to do

Every error carries a type and an English message; every refusal you can meet adds a stable code and its params. Something unexpected is a 500 with the code something_went_wrong, and nothing about our insides.

Retries are safe

Send an Idempotency-Key header with a brief. The same key from the same person within a day answers with the first Run (replayed: true) instead of starting another.

ADDRESSES

Where the API
answers.

WhatAddress
REST APIhttps://beta.zuger.ai/v1
MCPhttps://beta.zuger.ai/mcp
OpenAPI documenthttps://beta.zuger.ai/v1/openapi.json

Bernina reads it again.

Before a Run starts, while it works, and before you see what it made. On every plan.

Your passkey, at every gate.

Anything binding waits for you, every time. An agent cannot read or change what stops it.

Free plan · No card

Build on the back office.

The API is open. Make a key in the Console, under Developers, and send your first brief.