Reference
HTTP API reference
All 239 routes the gateway serves, generated from its OpenAPI document by scripts/gen/docs_reference.py. A running gateway serves the same document at /openapi.json and an explorer at /docs.
Two audiences
Agent traffic (/v1/*) is what your application calls on every request: the OpenAI- and Anthropic-compatible proxies, and the guard endpoints that check content and tool calls without proxying. It authenticates as an agent. The operator API (/api/*) is what the web app, the CLI and your scripts use to manage agents, policies, findings and evidence. It takes a bearer token from agentfox admin auth issue.
curl -s http://localhost:8080/v1/guard/tool_call \
-H "Content-Type: application/json" \
-H "X-AgentFox-Agent: support-triage" \
-d '{"agent": "support-triage", "tool": "tickets.close",
"arguments": {"ticket_id": "T-1042"},
"provenance": {"ticket_id": "user"},
"intent": "close tickets the customer asked to close"}'HTTP/1.1 200 OK
{"verdict":"block", "mode":"enforce",
"rules_fired":[{"rule_id":"capability.denied", ...},
{"rule_id":"tool.not_declared", "effect":"escalate", ...}],
"reason":"no resolved identity for the caller, so it holds no grants (default deny).
To have grants proposed from the calls this agent has made, run
`agentfox policy proposals from-traffic` and approve them; ...",
"explanation":{..., "dispute":{"endpoint":"POST /api/guardrails/feedback", ...}}}A verdict is a 200 with a body, not an error status: your code reads verdict and decides. Nothing is granted on a fresh install, so the first call is refused by default-deny, and the reason says how to fix it.
Worked examples for each endpoint are in the guides: Any language: the gateway covers the proxies and guard calls; Approvals covers polling an escalation.
Agent traffic
/api/health · Agent traffic (agent credential)
GET /health
The same payload as `/api/health`, at the path probes default to.
/api/metrics · Agent traffic (agent credential)
GET /metrics
Prometheus exposition.
/v1/chat · Agent traffic (agent credential)
POST /v1/chat/completions
OpenAI-compatible inline proxy
/v1/guard · Agent traffic (agent credential)
POST /v1/guard/agent_message
Authorise an inter-agent message
| Body field | Type |
|---|---|
sender required | string |
content required | string |
recipient | string |
nonce | string |
timestamp | number |
signature | string |
session_id | string |
POST /v1/guard/input
Enforce on content without proxying.
| Body field | Type |
|---|---|
agent required | string |
content required | string |
surface | string |
taint_source | string |
intent | string |
session_id | string |
trace_id | string |
environment | string |
context | array |
completion | object |
POST /v1/guard/memory_write
Authorise a memory write
| Body field | Type |
|---|---|
agent required | string |
content required | string |
subject | string |
taint_source | string |
provenance | object |
verified_by | string |
ttl_seconds | integer |
session_id | string |
POST /v1/guard/output
Enforce on content without proxying.
| Body field | Type |
|---|---|
agent required | string |
content required | string |
surface | string |
taint_source | string |
intent | string |
session_id | string |
trace_id | string |
environment | string |
context | array |
completion | object |
POST /v1/guard/tool_call
Authorise a tool call
| Body field | Type |
|---|---|
agent required | string |
tool required | string |
arguments | object |
provenance | object |
intent | string |
prior_tools | array |
prior_steps | array |
session_id | string |
environment | string |
approval_id | string |
/v1/mcp · Agent traffic (agent credential)
POST /v1/mcp/call
Govern one MCP call for callers that are not in-process Python.
| Body field | Type |
|---|---|
server required | string |
tool required | string |
arguments | object |
provenance | object |
result | any |
/v1/messages · Agent traffic (agent credential)
POST /v1/messages
Anthropic-compatible inline proxy
/v1/traces · Agent traffic (agent credential)
POST /v1/traces
OTLP/HTTP trace ingest
Operator API
/api/agent-controls · Operator API (bearer token)
GET /api/agent-controls
Kill-switch/quarantine state per agent.
/api/agent-messages · Operator API (bearer token)
GET /api/agent-messages
List Messages
Parameters: sender (query), limit (query)
/api/agents · Operator API (bearer token)
GET /api/agents
List Agents
Parameters: registered (query), environment (query)
POST /api/agents
Create Agent
| Body field | Type |
|---|---|
slug required | string |
name | string |
purpose | string |
owner_email | string |
owner_team | string |
environment | string |
risk_tier | string |
declared_models | array |
declared_tools | array |
data_classes | array |
framework | string |
POST /api/agents/{agent_id}/approve
Approve Agent
Parameters: agent_id (path, required)
POST /api/agents/{agent_id}/reject
Reject Agent
Parameters: agent_id (path, required)
GET /api/agents/{slug}
Get Agent
Parameters: slug (path, required)
PATCH /api/agents/{slug}
Update Agent
Parameters: slug (path, required)
| Body field | Type |
|---|---|
owner_email | string |
owner_team | string |
risk_tier | string |
purpose | string |
GET /api/agents/{slug}/access
Get Access
Parameters: slug (path, required), days (query)
POST /api/agents/{slug}/access
Grant a tool, or change the existing grant for it (one grant per tool key).
Parameters: slug (path, required)
| Body field | Type |
|---|---|
tool_key required | string |
requires_approval | boolean |
max_taint | string |
constraints | object |
actions | array |
DELETE /api/agents/{slug}/access/{capability_id}
Remove Access
Parameters: slug (path, required), capability_id (path, required)
POST /api/agents/{slug}/kill
Stop an agent now. Requires the stronger role — this is an incident action.
Parameters: slug (path, required)
| Body field | Type |
|---|---|
reason | string |
GET /api/agents/{slug}/lineage
Agent Lineage
Parameters: slug (path, required), depth (query)
GET /api/agents/{slug}/posture
Agent Posture
Parameters: slug (path, required)
GET /api/agents/{slug}/protection
Get Protection
Parameters: slug (path, required)
POST /api/agents/{slug}/protection
Save Protection
Parameters: slug (path, required)
| Body field | Type |
|---|---|
protections | object |
message | string |
words | array |
avoid | string |
allowed | string |
POST /api/agents/{slug}/protection/preview
Replay this agent's last week against the protections, as if enforcing.
Parameters: slug (path, required)
| Body field | Type |
|---|---|
protections | object |
message | string |
words | array |
avoid | string |
allowed | string |
POST /api/agents/{slug}/quarantine
Stop an agent while you investigate. Reversible and audited.
Parameters: slug (path, required)
| Body field | Type |
|---|---|
reason | string |
POST /api/agents/{slug}/resume
Restart a stopped agent. Deliberately the same role as `kill` — restarting something that was stopped for cause is not a lesser decision than stopping it.
Parameters: slug (path, required)
| Body field | Type |
|---|---|
reason | string |
GET /api/agents/{slug}/signing-key
Key Status
Parameters: slug (path, required)
POST /api/agents/{slug}/signing-key
Mint (or rotate) an agent's HMAC signing key. Shown once — like an API token, nothing after this call can retrieve the raw value again.
Parameters: slug (path, required)
/api/alerts · Operator API (bearer token)
DELETE /api/alerts/slack
Stop sending this tenant's alerts to its own Slack channel.
GET /api/alerts/slack
Whether this tenant has its own Slack channel, and whether alerts can leave at all.
PUT /api/alerts/slack
Send this tenant's monitor alerts to its own Slack incoming webhook.
| Body field | Type |
|---|---|
url required | string |
min_severity | string |
POST /api/alerts/slack/test
Send a test message to every channel this tenant's alerts go to, now.
/api/answerability · Operator API (bearer token)
GET /api/answerability/boundaries
Every declared knowledge boundary, or one agent's with `?agent=<slug>`.
Parameters: agent (query)
PUT /api/answerability/boundary
Write Boundary
| Body field | Type |
|---|---|
agent required | string |
systems_of_record | array |
coverage_months | integer |
coverage_start | string |
entity_types | array |
answerable_types | array |
out_of_scope_topics | array |
freshness_hours | integer |
mode | string |
POST /api/answerability/check
Would this question be refused, and what would we say instead?
| Body field | Type |
|---|---|
agent required | string |
question required | string |
known_entities | array |
GET /api/answerability/report
Abstention and over-refusal side by side.
Parameters: days (query)
/api/approvals · Operator API (bearer token)
GET /api/approvals
List Approvals
Parameters: status (query)
GET /api/approvals/{approval_id}
One approval. An operator may read any; an agent key only its own agent's.
Parameters: approval_id (path, required)
POST /api/approvals/{approval_id}/approve
Approve
Parameters: approval_id (path, required)
| Body field | Type |
|---|---|
rationale | string |
POST /api/approvals/{approval_id}/deny
Deny
Parameters: approval_id (path, required)
| Body field | Type |
|---|---|
rationale | string |
/api/attention · Operator API (bearer token)
GET /api/attention
What needs a human, ranked. The home page is built from this.
Parameters: hours (query)
/api/audit · Operator API (bearer token)
POST /api/audit/checkpoint
Checkpoint
GET /api/audit/entries
Audit Entries
Parameters: limit (query), action (query)
POST /api/audit/verify
Verify Chain
Parameters: start_seq (query), end_seq (query)
/api/auth · Operator API (bearer token)
POST /api/auth/github/provision
Find-or-create the user behind a GitHub identity, and mint them a token.
| Body field | Type |
|---|---|
github_user_id required | string |
github_login required | string |
email required | string |
name | string |
POST /api/auth/logout
Revoke the bearer token this request presents — the dashboard's Sign Out.
/api/board · Operator API (bearer token)
GET /api/board
Board
/api/business · Operator API (bearer token)
POST /api/business/compile
Compile written policy into rules and questions. Nothing is saved.
| Body field | Type |
|---|---|
text required | string |
GET /api/business/rules
List Business Rules
POST /api/business/rules
Save Business Rule
| Body field | Type |
|---|---|
definition required | object |
agent | string |
POST /api/business/rules/{key}/mode
Business Rule Mode
Parameters: key (path, required)
| Body field | Type |
|---|---|
mode required | string |
/api/compliance · Operator API (bearer token)
GET /api/compliance/status
Compliance Status
Parameters: framework (query)
/api/controls · Operator API (bearer token)
GET /api/controls
List Controls
POST /api/controls/compute
Compute Controls
Parameters: window_days (query)
POST /api/controls/sync
Load the static control catalog and obligation calendar from YAML into this tenant's control-plane DB. `agentfox admin catalog sync` does the same thing from the CLI against whatever DB it's pointed at — this is the same idempotent upsert, reachable without shell access to the deployment, so a freshly provisioned org isn't stuck at "0 controls, mapped to seven frameworks" with no way to fix it from the product itself.
/api/coverage · Operator API (bearer token)
GET /api/coverage/threats
Every published threat, and what this deployment actually does about it.
Parameters: window_days (query)
/api/credentials · Operator API (bearer token)
POST /api/credentials/{credential_id}/revoke
Revoke
Parameters: credential_id (path, required)
/api/custom-rules · Operator API (bearer token)
GET /api/custom-rules
Get Custom Rules
POST /api/custom-rules
Post Custom Rule
| Body field | Type |
|---|---|
key required | string |
name required | string |
kind | string |
polarity | string |
entries | array |
examples | array |
description | string |
surfaces | array |
agents | array |
case_sensitive | boolean |
sequence | SequenceSpec |
enabled | boolean |
effect | string |
message | string |
on_block | string |
severity | string |
POST /api/custom-rules/try
Match one text against a rule that has not been saved. Records nothing.
| Body field | Type |
|---|---|
rule required | object |
text required | string |
surface | string |
DELETE /api/custom-rules/{key}
Remove Custom Rule
Parameters: key (path, required)
/api/detectors · Operator API (bearer token)
GET /api/detectors
Which detectors exist, which are live, and how fast they are.
POST /api/detectors/{key}
Switch a detector on or off for this workspace. Turning one on that is not installed is refused: it would look enabled and check nothing.
Parameters: key (path, required)
| Body field | Type |
|---|---|
enabled required | boolean |
reason | string |
/api/discovery · Operator API (bearer token)
POST /api/discovery/scan
Sweep: lineage, unowned agents, registry drift, identity posture, delegation shape.
GET /api/discovery/shadow
Shadow Agents
Parameters: window_days (query)
POST /api/discovery/submit
Submit a redacted local scan for review
| Body field | Type |
|---|---|
source required | string |
label | string |
files_scanned | integer |
frameworks | array |
coverage | number |
counts | object |
sites | array |
/api/entitlement · Operator API (bearer token)
POST /api/entitlement/filter
Return only what this human may see, and record what was withheld.
| Body field | Type |
|---|---|
subject required | string |
agent | string |
chunks | array |
purpose | string |
trace_id | string |
record | boolean — Persist what was withheld. |
GET /api/entitlement/grants
List Grants
POST /api/entitlement/grants
Add Grant
| Body field | Type |
|---|---|
resource required | string — Matches a chunk's source; globs allowed. |
principal required | string |
principal_kind | string |
classes | array |
purposes | array |
residency | string |
GET /api/entitlement/over-permission
How much more the agent can reach than its callers are entitled to.
Parameters: days (query)
GET /api/entitlement/principals
List Principals
PUT /api/entitlement/principals
Put Principal
| Body field | Type |
|---|---|
subject required | string — Stable IdP identifier — an OIDC `sub`, employee id. |
agent | string |
display | string |
groups | array |
clearances | array |
purposes | array |
residency | string |
/api/escalation · Operator API (bearer token)
GET /api/escalation/conversations/{session_id}
The transcript plus why the policy did or didn't fire on it.
Parameters: session_id (path, required)
GET /api/escalation/handoffs
List Handoffs
Parameters: status (query), agent (query)
POST /api/escalation/handoffs/{handoff_id}/acknowledge
Acknowledge
Parameters: handoff_id (path, required)
GET /api/escalation/missed
**The 31% control.** Conversations that qualified for a hand-off and got none.
Parameters: since_hours (query), agent (query)
GET /api/escalation/policy
Read Policy
Parameters: agent (query)
PUT /api/escalation/policy
Write Policy
| Body field | Type |
|---|---|
agent | string |
conditions | object |
owner_role | string |
sla_minutes | integer |
mode | string |
GET /api/escalation/report
Report
Parameters: since_hours (query), agent (query)
POST /api/escalation/scan
Run detection and act on it: findings, retroactive hand-offs, SLA breaches.
Parameters: since_hours (query), agent (query)
POST /api/escalation/turns
Record one turn with its signals.
| Body field | Type |
|---|---|
session_id required | string |
agent | string |
trace_id | string |
user_text | string |
agent_text | string |
escalated | boolean |
failed | boolean |
confidence | number |
/api/eval · Operator API (bearer token)
GET /api/eval/annotations/queue
Eval results a human should look at: score within `band` of the scorer's own pass/fail threshold, or scorers disagreeing on the same case — both are exactly the shape a human should review rather than trust blindly, not a finding-in-itself the way a failed scorer already is.
Parameters: run_id (query), band (query), limit (query)
GET /api/eval/drift
Read-only. Viewing drift persists nothing, so the number of drift findings measures how often the agent drifted, not how often someone looked. Recording is the scheduled `drift.check` job (or `agentfox report drift` locally).
Parameters: agent (query, required), scorer (query)
POST /api/eval/gate
The CI entry point. Non-zero exit maps from ``passed: false``.
| Body field | Type |
|---|---|
suite required | string |
target | object |
scorers | array |
baseline_run_id | string |
thresholds | object |
min_pass_rate | number |
POST /api/eval/online
Run Online
| Body field | Type |
|---|---|
agent required | string |
scorers | array |
since_days | integer |
rate | number |
POST /api/eval/results/{result_id}/annotate
Record a human's judgment on a borderline eval result. Requires a note — same reasoning as Finding's own suppress/resolve discipline (registry.py's patch_finding): a one-click verdict with nothing recorded is how a real disagreement about scorer correctness disappears without anyone having actually looked.
Parameters: result_id (path, required)
| Body field | Type |
|---|---|
verdict | string |
note required | string |
GET /api/eval/runs
List Runs
Parameters: suite (query), limit (query)
POST /api/eval/runs
Create Run
| Body field | Type |
|---|---|
suite required | string |
target | object |
scorers | array |
baseline_run_id | string |
runner | string |
GET /api/eval/runs/{run_id}
Get Run
Parameters: run_id (path, required)
GET /api/eval/scorers
Scorers
GET /api/eval/slos
Slos
Parameters: agent (query)
POST /api/eval/slos
Declare a reliability target for one agent+scorer pair.
| Body field | Type |
|---|---|
agent required | string |
scorer required | string |
objective | string |
window | string |
target | number |
GET /api/eval/suites
List Suites
POST /api/eval/suites
Create Suite
| Body field | Type |
|---|---|
key required | string |
name | string |
description | string |
tags | array |
GET /api/eval/suites/{key}
Get Suite
Parameters: key (path, required)
POST /api/eval/suites/{key}/cases
Add Case
Parameters: key (path, required)
| Body field | Type |
|---|---|
input | object |
expected | object |
context | object |
labels | array |
split | string |
POST /api/eval/suites/{key}/cases/from-trace
Promote a production failure into a regression test.
Parameters: key (path, required), trace_id (query, required)
/api/evidence · Operator API (bearer token)
GET /api/evidence
List Evidence
POST /api/evidence
Enqueues through jobs_db rather than calling evidence.build() directly, and processes it within this same request — see jobs_db's own module docstring for why same-request processing, not a deferred worker, is the honest fit here. A transient failure gets one automatic retry later, with backoff, and this returns 202 queued_for_retry meanwhile; a permanent one is a real `Job` row with status="dead" a human can find via GET /jobs, not a bare 500.
| Body field | Type |
|---|---|
agents | array |
controls | array |
period_from | string |
period_to | string |
GET /api/evidence/{package_id}/download
Download Evidence
Parameters: package_id (path, required)
/api/export · Operator API (bearer token)
GET /api/export/siem
Export Siem
Parameters: format (query), since_days (query), limit (query)
/api/findings · Operator API (bearer token)
GET /api/findings
List Findings
Parameters: status (query), severity (query), type (query), agent (query), limit (query)
GET /api/findings/types
Every finding type: its title, default severity, what it means and who raises it.
GET /api/findings/{finding_id}
Get Finding
Parameters: finding_id (path, required)
PATCH /api/findings/{finding_id}
Patch Finding
Parameters: finding_id (path, required)
| Body field | Type |
|---|---|
status required | string |
suppression_reason | string |
note | string |
/api/frameworks · Operator API (bearer token)
GET /api/frameworks
Frameworks
POST /api/frameworks/review
Step 3 of the mapping review gate.
| Body field | Type |
|---|---|
control_key required | string |
framework required | string |
reference | string |
GET /api/frameworks/{key}
Framework
Parameters: key (path, required)
/api/guardrails · Operator API (bearer token)
GET /api/guardrails/feedback
List Feedback
Parameters: label (query), status (query), limit (query)
POST /api/guardrails/feedback
"This was wrong", attached to the decision it is about.
| Body field | Type |
|---|---|
decision_id required | string |
label required | string — false_positive | true_positive | false_negative |
detector_key | string |
entity_type | string |
note | string |
GET /api/guardrails/latency
Per-detector and per-agent p50/p95/max, plus how often the budget degraded.
Parameters: agent (query), days (query)
GET /api/guardrails/precision
Per-detector precision with the label count beside it.
Parameters: agent (query), days (query)
GET /api/guardrails/recommendations
Threshold suggestions, including the honest refusal to make one.
Parameters: days (query)
GET /api/guardrails/suppressions
List Suppressions
Parameters: agent (query)
POST /api/guardrails/suppressions
Accept a false positive as a scoped, expiring exception.
| Body field | Type |
|---|---|
feedback_id required | string |
scope | string — agent | global |
ttl_days | integer |
exact | boolean — suppress only this exact matched text |
reason | string |
DELETE /api/guardrails/suppressions/{suppression_id}
Delete Suppression
Parameters: suppression_id (path, required)
/api/health · Operator API (bearer token)
GET /api/health
Liveness, plus what is currently not being checked.
/api/identities · Operator API (bearer token)
GET /api/identities
List Identities
POST /api/identities/{identity_id}/capabilities
Add Capability
Parameters: identity_id (path, required)
| Body field | Type |
|---|---|
tool_key required | string |
actions | array |
constraints | object |
requires_approval | boolean |
max_taint | string |
POST /api/identities/{identity_id}/check
Check
Parameters: identity_id (path, required)
| Body field | Type |
|---|---|
tool_key required | string |
action | string |
arguments | object |
argument_taint | object |
POST /api/identities/{identity_id}/credentials
Issue
Parameters: identity_id (path, required), ttl_days (query)
POST /api/identities/{identity_id}/rotate
Rotate
Parameters: identity_id (path, required), overlap_hours (query)
/api/import · Operator API (bearer token)
POST /api/import/{tool}
Apply Import
Parameters: tool (path, required)
| Body field | Type |
|---|---|
source required | string |
skip | array |
POST /api/import/{tool}/plan
Plan Import
Parameters: tool (path, required)
| Body field | Type |
|---|---|
source required | string |
skip | array |
/api/integrations · Operator API (bearer token)
POST /api/integrations/github/connect
Connect
| Body field | Type |
|---|---|
access_token required | string |
GET /api/integrations/github/repos
List Repos
POST /api/integrations/github/scan
Trigger Scan
| Body field | Type |
|---|---|
repo_full_name required | string |
ref | string |
GET /api/integrations/github/scans/{scan_id}
Get Scan
Parameters: scan_id (path, required)
POST /api/integrations/github/webhook
GitHub push webhook: a signed push to a monitored repository queues a rescan.
POST /api/integrations/github/webhook-secret
Create or replace the GitHub connection's push-webhook secret (shown once).
POST /api/integrations/hosted-api/scan
Scan Hosted Api
| Body field | Type |
|---|---|
endpoint_url required | string |
docs_url | string |
openapi_spec_url | string |
purpose | string |
/api/jobs · Operator API (bearer token)
GET /api/jobs
Includes dead-lettered jobs by default — that's the point (jobs.py's own docstring: the dead letter is public state, not a log line an operator has to know to go look for).
Parameters: kind (query), status (query), limit (query)
GET /api/jobs/{job_id}
Get Job
Parameters: job_id (path, required)
POST /api/jobs/{job_id}/retry
Retry Job
Parameters: job_id (path, required)
/api/judgment · Operator API (bearer token)
GET /api/judgment/posture
What is in force, what may be changed, and what the deployment forbids.
PUT /api/judgment/posture
Replace the posture, refusing anything the deployment does not permit.
| Body field | Type |
|---|---|
tiers | array — Tier names to enable. 'deterministic' is implicit and always on. |
pii_egress | string — block | redact | allow |
fail_closed | boolean |
backend | string — local | remote | auto |
reason | string — Why this change is being made. Required — it is the field an investigation actually reads. |
confirm_egress | boolean — Required when the change starts sending payloads off this machine, or loosens how personal data is handled on the way. |
/api/legal-holds · Operator API (bearer token)
POST /api/legal-holds
Place Hold
| Body field | Type |
|---|---|
scope | object |
reason required | string |
/api/library · Operator API (bearer token)
GET /api/library/packs
List Packs
POST /api/library/packs/{pack_id}/install
Install Pack
Parameters: pack_id (path, required)
/api/mcp-servers · Operator API (bearer token)
GET /api/mcp-servers
List Mcp
POST /api/mcp-servers
Register an MCP server, and start monitoring it for tool drift.
| Body field | Type |
|---|---|
name required | string |
url | string |
transport | string |
trust_level | string |
pinned_version | string |
POST /api/mcp-servers/{name}/scan
Scan Mcp
Parameters: name (path, required)
| Body field | Type |
|---|---|
tools | array |
POST /api/mcp-servers/{name}/tools
Snapshot a listing *and* register each tool in the registry.
Parameters: name (path, required)
| Body field | Type |
|---|---|
tools | array |
accept_changes | boolean |
note | string |
/api/me · Operator API (bearer token)
GET /api/me
The signed-in identity, for the account menu.
/api/memory · Operator API (bearer token)
GET /api/memory
List Entries
Parameters: agent (query), active_only (query), limit (query)
POST /api/memory/{entry_id}/revoke
Pull an entry immediately — the concrete fix for 'no way to find and remove a bad memory'.
Parameters: entry_id (path, required)
POST /api/memory/{entry_id}/verify
A human vouches for an entry — it stops decaying on the unverified TTL.
Parameters: entry_id (path, required)
/api/metrics · Operator API (bearer token)
GET /api/metrics/breakdown
Breakdown
Parameters: dim (query), range (query), agent (query), environment (query)
GET /api/metrics/errors
Steps that failed — a tool that threw, a model call that errored — grouped.
Parameters: range (query), agent (query), environment (query)
GET /api/metrics/rules
How each rule behaved: fired, stopped something, or only watched.
Parameters: range (query), agent (query), environment (query)
GET /api/metrics/summary
Summary
Parameters: range (query), agent (query), environment (query)
/api/monitors · Operator API (bearer token)
GET /api/monitors
Every monitor in the tenant, with its last result and when it next runs.
Parameters: kind (query), enabled (query)
POST /api/monitors
Watch a source by hand. The first run stores a baseline; later runs report changes.
| Body field | Type |
|---|---|
kind required | string |
target required | string |
name | string |
interval_seconds | integer |
config | object |
enabled | boolean |
DELETE /api/monitors/{monitor_id}
Stop watching a source. Its findings are kept.
Parameters: monitor_id (path, required)
GET /api/monitors/{monitor_id}
One monitor, with the findings it raised that are still open.
Parameters: monitor_id (path, required)
PATCH /api/monitors/{monitor_id}
Rename, retune the interval, change config, or pause/resume (``enabled``).
Parameters: monitor_id (path, required)
| Body field | Type |
|---|---|
name | string |
interval_seconds | integer |
enabled | boolean |
config | object |
POST /api/monitors/{monitor_id}/pause
Stop scheduled runs. Open findings stay open; nothing is closed while paused.
Parameters: monitor_id (path, required)
POST /api/monitors/{monitor_id}/resume
Resume scheduled runs from the monitor's next due time.
Parameters: monitor_id (path, required)
POST /api/monitors/{monitor_id}/run
Run one monitor now, through the job queue, and return its result.
Parameters: monitor_id (path, required)
/api/obligations · Operator API (bearer token)
GET /api/obligations
Obligations
/api/onboarding · Operator API (bearer token)
GET /api/onboarding
Install state as a checklist, computed live.
/api/platform · Operator API (bearer token)
GET /
Name the service and say where to go next. Unauthenticated.
/api/policies · Operator API (bearer token)
GET /api/policies
List Policies
Parameters: agent (query)
POST /api/policies
Upsert Policy
| Body field | Type |
|---|---|
body required | string |
notes | string |
mode | string |
level | string |
scope_id | string |
compose | string |
GET /api/policies/effective
The policy actually in force for a subject, with per-rule provenance.
Parameters: agent (query), team (query), user (query), environment (query)
GET /api/policies/lint
Policy lint. `passed` is false when critical/high findings exist.
POST /api/policies/simulate
Replay recorded traffic against a candidate policy.
| Body field | Type |
|---|---|
body required | string |
agent | string |
since_days | integer |
limit | integer |
persist | boolean |
POST /api/policies/validate
Validate Policy
| Body field | Type |
|---|---|
body required | string |
notes | string |
mode | string |
level | string |
scope_id | string |
compose | string |
GET /api/policies/{key}
Get Policy
Parameters: key (path, required)
GET /api/policies/{key}/canary
Get Policy Canary
Parameters: key (path, required)
POST /api/policies/{key}/canary/advance
Check the candidate cohort's health and advance, hold, or auto-roll-back.
Parameters: key (path, required)
POST /api/policies/{key}/canary/rollback
Rollback Policy Canary
Parameters: key (path, required)
POST /api/policies/{key}/canary/start
Start Policy Canary
Parameters: key (path, required)
| Body field | Type |
|---|---|
candidate_version | integer |
steps | array |
max_block_rate_delta | number |
max_block_rate_drop | number |
min_dwell_seconds | integer |
min_sample | integer |
POST /api/policies/{key}/mode
Promote or demote a policy, optionally making a saved version live.
Parameters: key (path, required)
| Body field | Type |
|---|---|
mode required | string |
version | integer |
level | string |
scope_id | string |
compose | string |
GET /api/policies/{key}/rego
Get Rego
Parameters: key (path, required)
POST /api/policies/{key}/rules/{rule_id}
Change one rule's action or switch it off, as a new saved version.
Parameters: key (path, required), rule_id (path, required)
| Body field | Type |
|---|---|
effect | string |
enabled | boolean |
message | string |
on_block | string |
min_score | number |
notes | string |
POST /api/policies/{policy_id}/approve
Approve Policy
Parameters: policy_id (path, required)
POST /api/policies/{policy_id}/reject
Reject Policy
Parameters: policy_id (path, required)
/api/probes · Operator API (bearer token)
GET /api/probes/targets
List Targets
POST /api/probes/targets
Register a target. It is created disabled; nothing is sent until opt-in.
| Body field | Type |
|---|---|
agent required | string |
adapter | string |
url | string |
name | string |
model | string |
auth_header | string |
forbidden_tools | array |
leak_markers | array |
probes | array |
interval_seconds | integer |
max_probes_per_run | integer |
rate_limit_per_minute | integer |
timeout_seconds | number |
GET /api/probes/targets/{target_id}
Get Target
Parameters: target_id (path, required)
PATCH /api/probes/targets/{target_id}
Update Target
Parameters: target_id (path, required)
| Body field | Type |
|---|---|
url | string |
forbidden_tools | array |
leak_markers | array |
probes | array |
interval_seconds | integer |
max_probes_per_run | integer |
rate_limit_per_minute | integer |
timeout_seconds | number |
GET /api/probes/targets/{target_id}/campaigns
Campaigns
Parameters: target_id (path, required), limit (query)
POST /api/probes/targets/{target_id}/opt-in
Opt In
Parameters: target_id (path, required)
| Body field | Type |
|---|---|
acknowledgement required | string |
POST /api/probes/targets/{target_id}/opt-out
Opt Out
Parameters: target_id (path, required)
POST /api/probes/targets/{target_id}/run
Probe the target now. Same consent and caps as a scheduled run, and refused within `MIN_MANUAL_GAP_SECONDS` of the previous run.
Parameters: target_id (path, required)
GET /api/probes/warning
What a person must read before enabling probes, plus the probe library, the hard caps and the adapter contract a target endpoint has to speak.
/api/proposals · Operator API (bearer token)
GET /api/proposals
List change proposals, filtered by status, kind and scope.
Parameters: status (query), kind (query), scope_level (query), scope_id (query), limit (query)
GET /api/proposals/{proposal_id}
One proposal with its diff, evidence, proof and decisions.
Parameters: proposal_id (path, required)
POST /api/proposals/{proposal_id}/apply
Apply an approved proposal, or settle one whose canary has finished.
Parameters: proposal_id (path, required)
POST /api/proposals/{proposal_id}/decide
Approve or reject; an org-level loosening needs two different approvers.
Parameters: proposal_id (path, required)
| Body field | Type |
|---|---|
approve required | boolean |
note required | string |
POST /api/proposals/{proposal_id}/rollback
Undo an applied or canaried proposal through its applier.
Parameters: proposal_id (path, required)
| Body field | Type |
|---|---|
reason required | string |
POST /api/proposals/{proposal_id}/verify
Record whether an applied change worked; ``verified: false`` rolls it back.
Parameters: proposal_id (path, required)
| Body field | Type |
|---|---|
verified required | boolean |
note required | string |
/api/providers · Operator API (bearer token)
GET /api/providers
The neutrality surface, made inspectable.
/api/redteam · Operator API (bearer token)
GET /api/redteam/campaigns
List Campaigns
POST /api/redteam/campaigns
Enqueues through jobs_db and processes within this same request — see jobs_db's own module docstring and governance.py's build_evidence for the same reasoning applied to the other named candidate operation.
| Body field | Type |
|---|---|
agent required | string |
name | string |
probes | array |
runner | string |
adaptive | boolean |
budget | integer |
seed | integer |
include_deployment_probes | boolean |
GET /api/redteam/probes
List Probes
/api/reliability · Operator API (bearer token)
GET /api/reliability
Circuit-breaker state and live budget consumption.
/api/retention · Operator API (bearer token)
GET /api/retention
Retention
/api/risk · Operator API (bearer token)
POST /api/risk/assessments/{slug}
Create Assessment
Parameters: slug (path, required)
| Body field | Type |
|---|---|
eu_ai_act_class | string |
inherent_risk | string |
residual_risk | string |
answers | object |
review_months | integer |
sign_off | boolean |
signed_off_by | string |
GET /api/risk/classify/{slug}
Classify Agent
Parameters: slug (path, required)
GET /api/risk/register
Get Register
/api/rules · Operator API (bearer token)
GET /api/rules/{rule_id}/examples
Get Examples
Parameters: rule_id (path, required)
POST /api/rules/{rule_id}/examples
Post Example
Parameters: rule_id (path, required)
| Body field | Type |
|---|---|
decision_id required | string |
fires required | boolean |
sample | string |
POST /api/rules/{rule_id}/examples/check
Check Examples
Parameters: rule_id (path, required)
| Body field | Type |
|---|---|
policy required | string |
body | string |
DELETE /api/rules/{rule_id}/examples/{example_id}
Remove Example
Parameters: rule_id (path, required), example_id (path, required)
/api/sources · Operator API (bearer token)
GET /api/sources
List Sources
Parameters: tier (query), domain (query)
PUT /api/sources
Register or re-tier a source.
| Body field | Type |
|---|---|
key required | string — The identifier the retriever emits — URI, doc id, table. |
title | string |
tier | string — system_of_record | approved | unverified | external |
owner | string |
domain | string — Corpus this belongs to, e.g. 'finance'. |
updated_at_source | string |
freshness_sla_hours | integer |
deprecated | boolean |
metadata | object |
POST /api/sources/assess
Would this answer, from these sources, pass?
| Body field | Type |
|---|---|
answer required | string |
chunks | array |
agent_domain | string |
POST /api/sources/connections
Attach a real connector to a registered source — a database or an authenticated enterprise API — so `validate` can check it for real instead of assuming every source is a plain fetchable URL.
| Body field | Type |
|---|---|
key required | string — Must match an already-registered source's key. |
kind required | string — database | api |
config | object — database: dialect, host, port, database, username, check_table (optional). api: base_url, auth_header (default 'Authorization'), auth_prefix (default 'Bearer '). |
credential | string — The raw password or token — encrypted immediately, never stored in the clear. |
POST /api/sources/context-check
Would this document or chunk set be fit to enter the corpus?
| Body field | Type |
|---|---|
text | string |
chunks | array |
source_key | string |
GET /api/sources/health
Which registered sources are stale, deprecated, or unowned.
DELETE /api/sources/{key}
Retire a source. Deprecates by default rather than deleting.
Parameters: key (path, required), hard (query)
POST /api/sources/{key}/validate
Actually fetch the source and check its content, rather than trust the tier.
Parameters: key (path, required)
/api/tokens · Operator API (bearer token)
GET /api/tokens
List Tokens
POST /api/tokens
Mint a token for the caller's own use. The raw value is returned once — same guarantee as every other credential this platform issues.
| Body field | Type |
|---|---|
name | string |
ttl_days | integer |
POST /api/tokens/{token_id}/revoke
Revoke Token
Parameters: token_id (path, required)
/api/tools · Operator API (bearer token)
GET /api/tools
List Tools
POST /api/tools
Create Tool
| Body field | Type |
|---|---|
key required | string |
name | string |
kind | string |
impact | string |
description | string |
json_schema | object |
output_trust | string |
/api/traces · Operator API (bearer token)
GET /api/traces
List Traces
Parameters: agent (query), verdict (query), environment (query), entity_type (query), tool (query), rule (query), errors (query), since_days (query), start (query), end (query), limit (query)
GET /api/traces/resolve
Their run id → our governance decision.
Parameters: system (query, required), external_id (query, required)
GET /api/traces/{trace_id}
Get Trace
Parameters: trace_id (path, required)
/api/version · Operator API (bearer token)
GET /api/version
Every version that participates in a decision, so a verdict can be reproduced.
/api/workspace · Operator API (bearer token)
POST /api/workspace/apply
Apply Workspace
| Body field | Type |
|---|---|
source required | string |
GET /api/workspace/export
Export Workspace
POST /api/workspace/plan
Plan Workspace
| Body field | Type |
|---|---|
source required | string |
Public, unauthenticated
The playground, the waitlist and the live showcase feed. Sandboxed or read-only, rate-limited, and separate from your data.
/api/playground · Public, unauthenticated
POST /api/playground/sessions
Create a playground sandbox.
POST /api/playground/sessions/{session_id}/chat
Chat
Parameters: session_id (path, required)
| Body field | Type |
|---|---|
agent | string |
message required | string |
document | string |
POST /api/playground/sessions/{session_id}/enforce
Flip the baseline policy observe -> enforce (or back) for this sandbox only.
Parameters: session_id (path, required)
| Body field | Type |
|---|---|
mode required | string |
GET /api/playground/sessions/{session_id}/state
Everything the live sidebar needs: recent traces (decisions + detector runs + findings), the tamper-evident audit chain's own self-check, and compliance posture — all real, already-existing functions, just called and serialized.
Parameters: session_id (path, required)
POST /api/playground/sessions/{session_id}/tool-call
Try a tool call directly, with no model in the loop.
Parameters: session_id (path, required)
| Body field | Type |
|---|---|
agent required | string |
tool required | string |
arguments | object |
provenance | object |
intent | string |
/api/public · Public, unauthenticated
GET /api/public/showcase
AgentFox probing its own demo agent: recent runs, attacks attempted, contained and escaped, findings opened and closed. Unauthenticated and read-only; returns ``{"enabled": false}`` on a deployment that does not run the showcase.
/api/waitlist · Public, unauthenticated
POST /api/waitlist
Record an address. Unauthenticated, idempotent, and it sends nothing anywhere.
| Body field | Type |
|---|---|
email required | string |
source | string |
company | string |
note | string |