Ops API Reference
Protected ops APIs expose status and operator controls, while the public live APIs expose sanitized evidence only.
Endpoint summary
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /ops/api/live/status | Public sanitized | Public status objects for guardian, signal, and refund agents. |
| GET | /ops/api/live/feed | Public sanitized | Sanitized live events for public allow-listed agents. |
| GET | /ops/api/refunds/agent/status | Operator protected | Refund worker health and runtime state. |
| GET | /ops/api/refunds/ledger | Operator protected | Refund ledger rows for authorized operators. |
| POST | /ops/api/refunds/process-once | Operator protected | Process one ledger entry for verification. |
Example public live request
curl -s https://haltstate.ai/ops/api/live/status
curl -s 'https://haltstate.ai/ops/api/live/feed?limit=20'Example response shape:
{
"tenant": "public-demo",
"guardian": {"status": "active", "last_action": "comment.create"},
"signal": {"status": "active", "last_action": "comment.create"},
"refund": {"status": "active", "last_action": "refund.create", "last_decision": "DENY"}
}Example protected refund request
curl -i https://haltstate.ai/ops/api/refunds/agent/status
curl -i https://haltstate.ai/ops/api/refunds/ledgerUnauthenticated public requests are expected to return 401 or 403, or an intentionally sanitized response. Current public behavior is 401 with {"detail":"Invalid or missing credentials"}.
Example operator response shape
{
"agent_id": "retail-refund-agent",
"status": "active",
"last_action": "refund.create",
"last_decision": "DENY",
"redaction_status": "customer data hidden"
}Operator ledger responses may include protected ledger state for authorized users. Public unauthenticated responses must not include raw customer names, email, card data, raw order payloads, raw policy IDs, approval IDs, tenant secrets, API keys, or operator notes.
Error codes
| Status | Meaning |
|---|---|
| 200 | Public sanitized response or authorized operator response. |
| 400 | Invalid request parameters. |
| 401 | Missing or invalid credentials. |
| 403 | Credentials valid but not authorized for the resource. |
| 404 | Route not exposed or resource not found. A 404 on /ops/api/refunds/* means the protected refund route is not publicly exposed as claimed. |
| 429 | Rate limit or abuse control. |
| 500 | Server error; high-risk workers should fail closed. |
Access boundary
Raw ledger endpoints are operator tools. Public unauthenticated access must be denied or intentionally sanitized. The public proof of behavior is the live board and sanitized feed, not raw ledger data.
Public versus operator APIs
The public live endpoints are designed for a witness feed. They expose a curated, sanitized picture of governed runtime behavior. Refund ledger endpoints are operator APIs and should require authentication or return intentionally limited data. Do not use raw ledger access as the public proof surface; use the live board and sanitized feed.
Implementation notes
Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.
Operational evidence
For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.