AISOS
10 · Volume 7
API Reference
Authentication
Every request carries an organisation API key as a bearer token. Owners, admins and developers issue keys on the Enterprise Dashboard; the key is shown once and stored only as a SHA-256 hash. Revocation is immediate. The organisation's bound policy bundle, budget and plan apply to every call made with its keys.
Authorization: Bearer aisos_live_<48 hex characters>
POST /api/public/v1/mediate
Run one question through the full kernel pipeline — identity, AI firewall, knowledge firewall, policy routing, live model, output firewall — and receive the answer with its verdicts. Metered to the key's organisation and refused before any model is called when the monthly budget would be exceeded.
Body parameters
| name | type | required | description |
|---|---|---|---|
| actor | string ≤120 | yes | The end user or service on whose behalf you call. Recorded in usage and the ledger. |
| prompt | string ≤8000 | yes | The question. Instruction-override content is blocked by the AI firewall. |
| scope | enum | yes | Knowledge scope: kb.support | kb.finance | kb.hr. |
| channel | enum | no | Where the answer goes: internal-ui (default) | customer-email | public-web | tool-arg. Caps confidentiality. |
| model | string | no | "auto" (default) routes to the cheapest live endpoint cleared for the context; or pin an id from /models. |
| tool | string | no | A tool the reasoning may propose, e.g. tool.search. Effectful tools need VERIFIED lineage. |
Example request
curl -X POST https://YOUR-APP/api/public/v1/mediate \
-H "Authorization: Bearer $AISOS_API_KEY" \
-H "content-type: application/json" \
-d '{"actor":"svc.helpdesk","prompt":"What is the refund window?","scope":"kb.support"}'Response
{
"id": "med_00001a",
"decision": "permit", // permit | transform | deny
"answer": "Refunds are issued within 14 days … [E1]",
"citations": ["so_kb_support_01 · kb://support/refund-policy"],
"groundedness": 0.86, // 0..1 evidence coverage
"model": "aisos/kernel-fast",
"live": true,
"routing": "auto → aisos/kernel-fast (cheapest live endpoint cleared for C1)",
"attempts": [{ "model": "aisos/kernel-fast", "status": 200, "ok": true, "note": "…" }],
"firewall": { "verdict": "allow", "risk": 0, "signals": [] },
"verdicts": [{ "rule": "R-01", "decision": "permit", "reason": "…" }],
"dna": "fc78ae3ee5691ec772d25045",
"costUsd": 0.00042,
"ledgerHead": "9b1c…",
"note": "live upstream …"
}Status codes
POST /api/public/v1/mediate/stream
Same body and checks as /mediate, delivered as Server-Sent Events. Prompt checks, routing and budget run before any model is contacted. Each model chunk is re-scanned with a 48-character hold-back, so a secret split across chunks is caught before any of it is sent; on the first violation the upstream generation is cancelled and an abort event is sent. Only the final event is authoritative.
Body parameters
| name | type | required | description |
|---|---|---|---|
| (body) | object | yes | Identical to /mediate. Send Accept: text/event-stream. |
Example request
for await (const e of aisos.mediateStream({ actor: "svc.chat", prompt, scope: "kb.support" })) {
if (e.event === "attempt") ui.clear();
if (e.event === "delta") ui.append(e.data.text);
if (e.event === "abort") ui.withdraw(e.data.reason);
if (e.event === "final") ui.settle(e.data); // decision, citations, verdicts, dna
}Response
event: attempt data: {"model":"aisos/kernel-fast"} // discard earlier deltas
event: delta data: {"text":"Refunds are issued within "}
event: delta data: {"text":"14 days [E1]."}
event: abort data: {"kind":"api-key","reason":"output contained api-key content"} // withdraw shown text
event: final data: { ...full /mediate response... }
event: error data: {"message":"client disconnected"}Status codes
POST /api/public/v1/agents/run
Give a goal; a live planner proposes up to four tool steps; each step passes the five-stage secure execution pipeline (validate, authorise, sandbox, execute, verify); the answer is grounded only on tool outputs.
Body parameters
| name | type | required | description |
|---|---|---|---|
| goal | string ≤2000 | yes | What the agent should achieve. |
| scope | enum | yes | kb.support | kb.finance | kb.hr. |
Example request
curl -X POST https://YOUR-APP/api/public/v1/agents/run \
-H "Authorization: Bearer $AISOS_API_KEY" -H "content-type: application/json" \
-d '{"goal":"Summarise our refund and escalation rules","scope":"kb.support"}'Response
{
"goal": "…",
"plan": [{ "tool": "tool.search", "args": { "query": "refund policy" } }],
"steps": [{ "index": 0, "tool": "tool.search", "stage": "execute", "decision": "permit", "detail": "1 result(s)" }],
"decision": "permit",
"answer": "• Refunds within 14 days …",
"planner": "aisos/kernel-fast",
"note": "live upstream …"
}Status codes
GET /api/public/v1/models
List live, attested endpoints the router may use, with their confidentiality ceilings. Simulation endpoints are never listed and never served by the API.
Example request
curl https://YOUR-APP/api/public/v1/models -H "Authorization: Bearer $AISOS_API_KEY"
Response
{ "models": [
{ "id": "aisos/kernel-fast", "region": "us-east", "max_confidentiality": 1, "cost_per_ktoken_usd": 0.0009, "typical_latency_ms": 700 },
{ "id": "aisos/kernel-enterprise", "region": "us-east", "max_confidentiality": 2, "cost_per_ktoken_usd": 0.015, "typical_latency_ms": 2600 }
] }Status codes
Errors
Transport errors return { error, message }. Kernel denials are not errors: they return the full mediation object with decision: "deny" and HTTP 403, naming the rule, the reason and the remediation. The API never substitutes a simulated answer: if live inference is unavailable the call is denied with live inference unavailable.
TypeScript SDK
import { createAisos } from "@aisos/sdk";
const aisos = createAisos({ baseUrl: "https://YOUR-APP", apiKey: process.env.AISOS_API_KEY! });
const r = await aisos.mediate({
actor: "svc.helpdesk",
prompt: "What is our refund window?",
scope: "kb.support",
});
if (r.decision === "deny") {
// Denials are values, not exceptions.
console.warn(r.verdicts.find((v) => v.decision === "deny")?.remediation);
} else {
console.log(r.answer, r.citations, r.dna);
}Limits
- Request body ≤ 16 KB; prompt ≤ 8,000 characters; agent goal ≤ 2,000.
- Agent plans ≤ 6 steps; tool arguments ≤ 400 characters.
- Calls are refused before any model runs once month-to-date spend plus the call estimate exceeds the organisation budget.
- Up to 3 routing attempts per call; failed endpoints fall through on 429/5xx only.