Quickstart

# Requires curl and jq. TAVONEL_API_KEY holds a key scoped documents:intake + collections:compile + collections:read.
capability=$(curl -fsS https://tavonel.com/api/v1/uploads/capability \
  -H "Authorization: Bearer $TAVONEL_API_KEY" -H "content-type: application/json" \
  -d '{"originalFilename":"manual.pdf","declaredMimeType":"application/pdf","requestedBytes":184320}')
document_id=$(printf '%s' "$capability" | jq -r .documentId)

# 2. The bytes go straight to storage. Content-Type must match declaredMimeType.
curl -fsS -X PUT "$(printf '%s' "$capability" | jq -r .uploadUrl)" \
  -H "content-type: application/pdf" --data-binary @manual.pdf

# 3. 202 Accepted, with a job id. The compile continues if this shell exits.
job_id=$(curl -fsS https://tavonel.com/api/compile-jobs \
  -H "Authorization: Bearer $TAVONEL_API_KEY" -H "content-type: application/json" \
  -d "{\"documentIds\":[\"$document_id\"]}" | jq -r .jobId)

# 4. Poll until it settles. Nothing here is a World yet.
while :; do
  job=$(curl -fsS "https://tavonel.com/api/compile-jobs/$job_id" -H "Authorization: Bearer $TAVONEL_API_KEY")
  state=$(printf '%s' "$job" | jq -r .job.state)
  echo "state=$state"
  case "$state" in ready|review_required|failed|cancelled) break ;; esac
  sleep 5
done
collection_id=$(printf '%s' "$job" | jq -r .job.collectionId)
echo "candidate: $collection_id — a person activates it in the workspace before step 6"

import json, os, time, urllib.request

BASE = "https://tavonel.com"
KEY = os.environ["TAVONEL_API_KEY"]

def call(method, path, body=None, headers=None):
    data = json.dumps(body).encode() if body is not None else None
    request = urllib.request.Request(BASE + path, data=data, method=method)
    request.add_header("authorization", f"Bearer {KEY}")
    if data is not None:
        request.add_header("content-type", "application/json")
    for name, value in (headers or {}).items():
        request.add_header(name, value)
    with urllib.request.urlopen(request) as response:
        return json.loads(response.read() or b"{}")

capability = call("POST", "/api/v1/uploads/capability", {
    "originalFilename": "manual.pdf",
    "declaredMimeType": "application/pdf",
    "requestedBytes": os.path.getsize("manual.pdf"),
})

# The PUT is unauthenticated: the capability URL is the credential, and it is short-lived.
with open("manual.pdf", "rb") as handle:
    put = urllib.request.Request(capability["uploadUrl"], data=handle.read(), method="PUT")
    put.add_header("content-type", "application/pdf")
    urllib.request.urlopen(put).read()

accepted = call("POST", "/api/compile-jobs", {"documentIds": [capability["documentId"]]})

while True:
    job = call("GET", f"/api/compile-jobs/{accepted['jobId']}")["job"]
    print("state=", job["state"])
    if job["state"] in {"ready", "review_required", "failed", "cancelled"}:
        break
    time.sleep(5)

print("candidate:", job["collectionId"], "— a person activates it before step 6")

import { readFile, stat } from "node:fs/promises";

const BASE = "https://tavonel.com";
const KEY = process.env.TAVONEL_API_KEY!;

async function call<T>(method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(BASE + path, {
    method,
    headers: { authorization: `Bearer ${KEY}`, ...(body ? { "content-type": "application/json" } : {}) },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!response.ok) throw new Error(`${method} ${path} -> ${response.status} ${await response.text()}`);
  return response.json() as Promise<T>;
}

const capability = await call<{ documentId: string; uploadUrl: string }>(
  "POST", "/api/v1/uploads/capability",
  { originalFilename: "manual.pdf", declaredMimeType: "application/pdf", requestedBytes: (await stat("manual.pdf")).size },
);

await fetch(capability.uploadUrl, {
  method: "PUT",
  headers: { "content-type": "application/pdf" },
  body: await readFile("manual.pdf"),
});

const accepted = await call<{ jobId: string }>("POST", "/api/compile-jobs", { documentIds: [capability.documentId] });

const settled = new Set(["ready", "review_required", "failed", "cancelled"]);
let job: { state: string; collectionId: string | null };
do {
  ({ job } = await call<{ job: typeof job }>("GET", `/api/compile-jobs/${accepted.jobId}`));
  console.log("state=", job.state);
  if (!settled.has(job.state)) await new Promise((done) => setTimeout(done, 5_000));
} while (!settled.has(job.state));

console.log("candidate:", job.collectionId, "— a person activates it before step 6");

# 6. Ask the active World. `retrievalPath` names which runtime answered:
#    compiled-retrieval-v1, or excerpt-concatenation-fallback when the active World
#    has no compiled retrieval run. /search has no fallback and answers 409 in that case.
#    The fallback path returns citations; the compiled path returns a contextPacket.
curl -fsS "https://tavonel.com/api/v1/collections/$collection_id/ask" \
  -H "Authorization: Bearer $TAVONEL_API_KEY" -H "content-type: application/json" \
  -d '{"question":"What is the documented retention period?"}' \
  | jq '{code, retrievalPath, retrievalNotice, citations, contextPacket}'

# 7. Export, then verify without us. The fingerprint comes from the trust endpoint,
#    not from the archive -- an archive cannot vouch for its own key.
curl -fsS "https://tavonel.com/api/v1/collections/$collection_id/download" \
  -H "Authorization: Bearer $TAVONEL_API_KEY" -o world.zip
#    The trust record is v2: the active key's fingerprint is under keys[], not at the top.
fingerprint=$(curl -fsS https://tavonel.com/api/export/trust | jq -r '.activeKeyId as $id | .keys[] | select(.keyId == $id) | .publicKeySpkiSha256')
node tavonel-verify-export.mjs --archive world.zip --trusted-fingerprint "$fingerprint"
node tavonel-verify-package.mjs --package world.zip --require-signature

answer = call("POST", f"/api/v1/collections/{job['collectionId']}/ask",
              {"question": "What is the documented retention period?"})
print(answer["code"], answer["retrievalPath"])
for citation in answer.get("citations", []):
    print(citation["sourceVersionId"], citation["pageNumber1"], citation["bbox1000"])

# The download is bytes, not JSON, so it does not go through call().
download = urllib.request.Request(f"{BASE}/api/v1/collections/{job['collectionId']}/download")
download.add_header("authorization", f"Bearer {KEY}")
with urllib.request.urlopen(download) as response, open("world.zip", "wb") as out:
    out.write(response.read())

# Verification is the two published Node verifiers; there is no Python port of them.
# See the CLI page for the download-and-pin commands.

import { writeFile } from "node:fs/promises";

const answer = await call<{ code: string; retrievalPath: string; retrievalNotice?: string }>(
  "POST", `/api/v1/collections/${job.collectionId}/ask`,
  { question: "What is the documented retention period?" },
);
console.log(answer.code, answer.retrievalPath, answer.retrievalNotice ?? "");

const archive = await fetch(`${BASE}/api/v1/collections/${job.collectionId}/download`, {
  headers: { authorization: `Bearer ${KEY}` },
});
await writeFile("world.zip", Buffer.from(await archive.arrayBuffer()));

// Then run the two published verifiers; see the CLI page.