Agency API quickstart

export ALLTERNIT_API_KEY="<your api key>"
export BASE="https://api.allternit.com"

const BASE = "https://api.allternit.com";
const KEY = process.env.ALLTERNIT_API_KEY!;

const headers = (extra: Record<string, string> = {}) => ({
  Authorization: `Bearer ${KEY}`,
  "Allternit-Version": "2026-09-29",
  ...extra,
});

import os, uuid, json
import requests

BASE = "https://api.allternit.com"
KEY = os.environ["ALLTERNIT_API_KEY"]

def headers(**extra):
    return {
        "Authorization": f"Bearer {KEY}",
        "Allternit-Version": "2026-09-29",
        **extra,
    }

curl -X POST "$BASE/v1/agency" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Allternit-Version: 2026-09-29" \
  -H "Content-Type: application/json" \
  -d '{"goal": "Fix the failing checkout tests and verify the repair"}'

import { randomUUID } from "node:crypto";

const createRes = await fetch(`${BASE}/v1/agency`, {
  method: "POST",
  headers: headers({
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  }),
  body: JSON.stringify({
    goal: "Fix the failing checkout tests and verify the repair",
  }),
});
if (createRes.status !== 202) {
  const { error } = await createRes.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const run = await createRes.json();
console.log(run.id, run.status, run.resolved.defaults_source);

res = requests.post(
    f"{BASE}/v1/agency",
    headers=headers(**{"Idempotency-Key": str(uuid.uuid4())}),
    json={"goal": "Fix the failing checkout tests and verify the repair"},
)
if res.status_code != 202:
    err = res.json()["error"]
    raise RuntimeError(f'{err["code"]}: {err["message"]}')
run = res.json()
print(run["id"], run["status"], run["resolved"]["defaults_source"])

curl -N "$BASE/v1/runs/run_01JB2K4Y7MQ8/events" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Accept: text/event-stream"

# Resume after a disconnect
curl -N "$BASE/v1/runs/run_01JB2K4Y7MQ8/events" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: evt_01JB2K50000007"

type RunEvent = { id: string; seq: number; type: string; data: any };

async function* streamEvents(runId: string, lastEventId?: string): AsyncGenerator<RunEvent> {
  const res = await fetch(`${BASE}/v1/runs/${runId}/events`, {
    headers: headers({
      Accept: "text/event-stream",
      ...(lastEventId ? { "Last-Event-ID": lastEventId } : {}),
    }),
  });
  if (!res.ok || !res.body) throw new Error(`stream failed: ${res.status}`);

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  while (true) {
    const { value, done } = await reader.read();
    if (done) return;
    buffer += decoder.decode(value, { stream: true });
    let end: number;
    while ((end = buffer.indexOf("\n\n")) !== -1) {
      const frame = buffer.slice(0, end);
      buffer = buffer.slice(end + 2);
      const data = frame
        .split("\n")
        .filter((line) => line.startsWith("data:"))
        .map((line) => line.slice(5).trimStart())
        .join("\n");
      if (data) yield JSON.parse(data) as RunEvent; // comment lines (": ping") carry no data
    }
  }
}

let lastId: string | undefined;
let openAttention: any = null;
for await (const event of streamEvents(run.id)) {
  lastId = event.id;
  switch (event.type) {
    case "run.progress":
      console.log("step:", event.data.step);
      break;
    case "attention.requested":
      openAttention = event.data;
      console.log("needs you:", event.data.topic);
      break;
    case "run.status_changed":
      console.log(event.data.from, "->", event.data.to);
      break;
    default:
      break; // ignore event types you do not know
  }
}

def stream_events(run_id, last_event_id=None):
    h = headers(Accept="text/event-stream")
    if last_event_id:
        h["Last-Event-ID"] = last_event_id
    with requests.get(f"{BASE}/v1/runs/{run_id}/events", headers=h, stream=True) as res:
        res.raise_for_status()
        data_lines = []
        for raw in res.iter_lines(decode_unicode=True):
            if raw is None:
                continue
            if raw == "":                      # blank line ends one message
                if data_lines:
                    yield json.loads("\n".join(data_lines))
                data_lines = []
            elif raw.startswith("data:"):
                data_lines.append(raw[5:].lstrip())
            # lines starting with ":" are heartbeats; ignore them

last_id = None
open_attention = None
for event in stream_events(run["id"]):
    last_id = event["id"]
    if event["type"] == "run.progress":
        print("step:", event["data"]["step"])
    elif event["type"] == "attention.requested":
        open_attention = event["data"]
        print("needs you:", event["data"]["topic"])
    elif event["type"] == "run.status_changed":
        print(event["data"]["from"], "->", event["data"]["to"])
    # ignore event types you do not know

curl -X POST "$BASE/v1/attention/att_01JB2K61QF/responses" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type": "approval", "comment": "Patch looks scoped to the failing test."}'

const answer = await fetch(`${BASE}/v1/attention/${openAttention.id}/responses`, {
  method: "POST",
  headers: headers({
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  }),
  body: JSON.stringify({ type: "approval", comment: "Patch looks scoped to the failing test." }),
});
if (answer.status === 409) {
  console.log("someone else already answered"); // ERR_ATTENTION_RESOLVED
}

answer = requests.post(
    f'{BASE}/v1/attention/{open_attention["id"]}/responses',
    headers=headers(**{"Idempotency-Key": str(uuid.uuid4())}),
    json={"type": "approval", "comment": "Patch looks scoped to the failing test."},
)
if answer.status_code == 409:
    print("someone else already answered")  # ERR_ATTENTION_RESOLVED

curl "$BASE/v1/runs/run_01JB2K4Y7MQ8" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

const final = await (await fetch(`${BASE}/v1/runs/${run.id}`, { headers: headers() })).json();
console.log(final.status, final.completion.status);
for (const c of final.completion.criteria) {
  console.log(c.criterion, c.result, c.receipt_ids);
}

final = requests.get(f'{BASE}/v1/runs/{run["id"]}', headers=headers()).json()
print(final["status"], final["completion"]["status"])
for c in final["completion"]["criteria"]:
    print(c["criterion"], c["result"], c.get("receipt_ids"))

curl "$BASE/v1/runs/run_01JB2K4Y7MQ8/artifacts" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

const artifacts = await (
  await fetch(`${BASE}/v1/runs/${run.id}/artifacts`, { headers: headers() })
).json();
for (const a of artifacts.data) {
  console.log(a.name, a.kind, a.hash, a.verification_status);
  if (a.content_url) {
    const bytes = await (await fetch(a.content_url)).arrayBuffer(); // short-lived URL
  }
}

import hashlib

artifacts = requests.get(f'{BASE}/v1/runs/{run["id"]}/artifacts', headers=headers()).json()
for a in artifacts["data"]:
    print(a["name"], a.get("kind"), a["hash"], a["verification_status"])
    if a.get("content_url"):
        body = requests.get(a["content_url"]).content  # short-lived URL
        assert "sha256:" + hashlib.sha256(body).hexdigest() == a["hash"]

curl "$BASE/v1/runs/run_01JB2K4Y7MQ8/receipts?limit=200" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

# Server-side check (a convenience, not the trust root)
curl "$BASE/v1/runs/run_01JB2K4Y7MQ8/receipts/verification" \
  -H "Authorization: Bearer $ALLTERNIT_API_KEY"

async function allReceipts(runId: string) {
  const out: any[] = [];
  let cursor: string | null = null;
  do {
    const url = new URL(`${BASE}/v1/runs/${runId}/receipts`);
    url.searchParams.set("limit", "200");
    if (cursor) url.searchParams.set("cursor", cursor);
    const page = await (await fetch(url, { headers: headers() })).json();
    out.push(...page.data);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);
  return out;
}

const receipts = await allReceipts(run.id);

// Link check: each prev_hash must equal the previous content_hash
receipts.forEach((r, i) => {
  const expected = i === 0 ? null : receipts[i - 1].content_hash;
  if (r.index !== i || r.prev_hash !== expected) throw new Error(`chain broken at ${i}`);
});

const check = await (
  await fetch(`${BASE}/v1/runs/${run.id}/receipts/verification`, { headers: headers() })
).json();
console.log(check.hash_chain_valid, check.signatures_valid, check.head_hash);

def all_receipts(run_id):
    out, cursor = [], None
    while True:
        params = {"limit": 200, **({"cursor": cursor} if cursor else {})}
        page = requests.get(f"{BASE}/v1/runs/{run_id}/receipts", headers=headers(), params=params).json()
        out.extend(page["data"])
        if not page["has_more"]:
            return out
        cursor = page["next_cursor"]

receipts = all_receipts(run["id"])

# Link check: each prev_hash must equal the previous content_hash
for i, r in enumerate(receipts):
    expected = None if i == 0 else receipts[i - 1]["content_hash"]
    assert r["index"] == i and r["prev_hash"] == expected, f"chain broken at {i}"

check = requests.get(f'{BASE}/v1/runs/{run["id"]}/receipts/verification', headers=headers()).json()
print(check["hash_chain_valid"], check["signatures_valid"], check["head_hash"])