Send a request envelope, get back an output envelope — with a proof ID, a status and the route that executed. Blocked outputs are expected safety behavior, not errors.
The endpoint
Four things to know before your first call:
Bearer token in the Authorization header. Get a sandbox key on the keys page.
Required on every request. No tenant, no memory — recall and tools only exist inside your tenant scope.
Recommended header. Replays return the original result instead of re-executing the task.
Returned on every output — including blocked ones. Use it to audit, trace and verify any claim.
{
"tenant_id": "tenant_demo_001",
"actor": {
"actor_id": "user_123",
"role": "admin"
},
"channel": "api",
"message": "Create a safe proof report for this architecture decision.",
"metadata": {
"workspace_id": "workspace_demo"
}
}
{
"status": "reported-pending-proof",
"proof_id": "PRF-demo-001",
"output": "...",
"blocker": null,
"route": {
"runtime": "gaia-orchestra-v2",
"mode": "dry-run"
}
}
| Field | Meaning |
|---|---|
| status | verified · reported-pending-proof · blocked · error. Only verified supports a production claim. |
| proof_id | Audit handle for this output. Every response has one — refusals included. |
| blocker | Set when status is blocked: which gate refused and why. This is expected safety behavior — handle it, don't retry blindly. |
| route | What actually executed: runtime and mode. dry-run results are never marked verified. |
Code examples
# Sandbox base URL — production route pending verification curl -X POST https://api.orijins.connect/v1/orchestra/handle \ -H "Authorization: Bearer $GAIA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "tenant_id": "tenant_demo_001", "actor": {"actor_id": "user_123", "role": "admin"}, "channel": "api", "message": "Create a safe proof report for this architecture decision.", "metadata": {"workspace_id": "workspace_demo"} }'
import os, uuid, json import urllib.request # Sandbox base URL — production route pending verification BASE = "https://api.orijins.connect" req = urllib.request.Request( f"{BASE}/v1/orchestra/handle", data=json.dumps({ "tenant_id": "tenant_demo_001", "actor": {"actor_id": "user_123", "role": "admin"}, "channel": "api", "message": "Create a safe proof report for this architecture decision.", "metadata": {"workspace_id": "workspace_demo"}, }).encode(), headers={ "Authorization": f"Bearer {os.environ['GAIA_API_KEY']}", "Content-Type": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, ) out = json.load(urllib.request.urlopen(req)) # Blocked outputs are expected safety behavior — handle them. if out["status"] == "blocked": print("Gate refused:", out["blocker"], "proof:", out["proof_id"]) else: print(out["status"], out["proof_id"]) print(out["output"])
// Sandbox base URL — production route pending verification const BASE = "https://api.orijins.connect"; interface OrchestraOutput { status: "verified" | "reported-pending-proof" | "blocked" | "error"; proof_id: string; output: string | null; blocker: string | null; route: { runtime: string; mode: string }; } const res = await fetch(`${BASE}/v1/orchestra/handle`, { method: "POST", headers: { Authorization: `Bearer ${process.env.GAIA_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ tenant_id: "tenant_demo_001", actor: { actor_id: "user_123", role: "admin" }, channel: "api", message: "Create a safe proof report for this architecture decision.", metadata: { workspace_id: "workspace_demo" }, }), }); const out = (await res.json()) as OrchestraOutput; // Blocked outputs are expected safety behavior — handle them. if (out.status === "blocked") { console.warn("Gate refused:", out.blocker, "proof:", out.proof_id); } else { console.log(out.status, out.proof_id, out.output); }
Sandbox keys are free, scoped and clearly labeled. Production keys require an approved tenant.