API Reference

REST API

Reference for the early MVP decision API exposed by actantosd. The full ActantOS platform will expand these endpoints; contracts below reflect what ships today.

Intercept tool call

POST /v1/intercept/tool-call

Main interception point. Adapters and the MCP gateway normalize each tool call and submit agent, session, resource, and normalized facts for Cedar evaluation.

Response decisions

allow — issues a short-lived decision_token and sandbox constraints.
deny — fail-closed; includes reason_code (e.g. policy_forbid.credential_path, kill_switch_active).
approval_required — returns approval.approval_id for manual review.

JSON — minimal request

{
  "request_id": "demo_abc12345",
  "tenant_id": "t_demo",
  "agent": {
    "id": "pi_demo",
    "runtime_type": "pi",
    "environment": "dev",
    "risk_tier": "medium"
  },
  "subject": { "user_id": "u_demo", "role": "developer" },
  "session": { "id": "s_demo", "budget_remaining_cents": 10000 },
  "tool": { "name": "read", "kind": "file", "schema_hash": "sha256:..." },
  "action": { "operation": "read", "args": { "path": ".env" } },
  "resource": { "id": "file:.env", "kind": "file", "path": ".env" },
  "normalized": {
    "verb": "read",
    "mutation": false,
    "destructive": false,
    "network": false,
    "credential_access": true,
    "risk_class": "critical"
  }
}

Record tool result

POST /v1/tool-result

Called after sandbox execution. Requires the decision_token from an allow response. Records exit codes, output hashes, and links results back to the intercept request_id.

Approve or deny

POST /v1/approvals/{approval_id}/decide

Manual approval API for Week 1. Returns a one-use approval_token that the adapter re-submits in the authorization block on the next intercept call.

JSON

{ "decision": "approved", "approver_user_id": "admin" }

Session audit timeline

GET /v1/sessions/{session_id}/events

Returns the hash-chained audit timeline for a session: request_id, tool name, final_decision, risk_class, approval_id, and result_hash.

Kill switch

POST /v1/kill-switches

Immediately deny all tool calls for a scoped agent, tenant, or session. Active kill switches return reason_code=kill_switch_active.

GET /v1/kill-switches?tenant_id=...

List active kill switches for a tenant.