Core API
API endpoint index
A compact map of the public Contro1 runtime API: request creation, Control Map preview, audit records, and thread timelines.
Use this page when you want the simple list of public runtime API calls that agents and framework connectors should call directly.
Key takeaways
- Agent runtime traffic uses /api/centcom/v1 with a bearer API key.
- POST /requests/control-map previews routing before creating a request.
- Request endpoints accept general policy evidence fields such as policy_context and approval_comment_required.
- GET /requests/:id/evidence exports a JSON packet for one reviewed action.
- Dashboard administration APIs are intentionally not part of the public runtime contract.
- External role mappings let admins route roles such as CFO to one or more reviewers and fallbacks.
Runtime API for agents
These are the calls production agents and framework connectors normally use. Base URL: https://api.contro1.com/api/centcom/v1.
| Method | Endpoint | Use it for |
|---|---|---|
| POST | /requests/control-map | Preview role mappings, fallback reviewers, on-shift capacity, and approval-policy satisfiability before creating a request. |
| POST | /requests | Create a human approval, yes/no, free-text, review, or decision request. |
| GET | /requests?thread_id=... | List requests in one thread for connector and case reconstruction workflows. |
| GET | /requests/:id | Fetch request state, response, operator details, policy context, and protocol response. |
| GET | /requests/:id/evidence | Export one JSON evidence packet with request metadata, policy context, reviewer decision, webhook status, timestamps, and final protocol response. |
| DELETE | /requests/:id | Cancel a pending request before an operator has completed it. |
| POST | /audit-records | Record an autonomous action that should be audited without pausing for human approval. |
| GET | /audit-records | Search audit records by actor, source, workflow, outcome, severity, correlation_id, external_request_id, thread_id, tags, text, or date range. |
| GET | /audit-records/:id | Fetch one audit record. |
| GET | /threads/:thread_id | Fetch the combined timeline for a thread across requests and audit records. |
| GET | /agents | List the agents that have called Contro1, with verification status and least-agency scopes. |
| GET | /agents/:agent_id | Fetch one agent: identity, verification, scopes, and status. |
| GET | /agents/:agent_id/trail | Full decision trail for one agent (add ?trace_id= to scope to one run). |
| GET | /agents/:agent_id/evidence | Signed evidence bundle for one agent (add ?format=csv for a spreadsheet). |
| GET | /traces/:trace_id | Full execution trace for one run: span tree, sub-agents, and tool calls. |
Use an SDK when you can
If your agent runtime is Python, Node, or TypeScript, use the official SDKs instead of hand-writing every HTTP call. They wrap request creation, audit records, evidence reads, and webhook verification while keeping the same public runtime API underneath.
Dashboard operator API
Operator console calls are dashboard APIs, not public agent runtime APIs. They are session-authenticated, role-gated, audited, and intentionally not documented path-by-path on the public site.
Use the dashboard for claiming, viewing, responding to, reassigning, and escalating requests. If you need embedded operator workflows for an enterprise deployment, use a scoped integration path rather than the internal dashboard contract.
Admin setup API
Admin, organization-management, Slack, and webhook-secret operations are dashboard APIs. They are for authenticated admins and managers, not for production agents.
The public docs describe the capabilities rather than listing internal paths: manage members and roles, map external approval roles, configure departments and shifts, create API keys, rotate webhook signing material, inspect activity, and connect Slack.
For enterprise management automation, use a scoped admin API engagement with explicit scopes, audit logging, rate limits, and separate credentials from runtime agent keys.
When you need management automation
If you want to automate organization administration, do not call dashboard session endpoints from an agent. Use a dedicated management integration with least-privilege scopes such as org read, operator write, routing write, shift write, or webhook-secret rotation.
Keep runtime approval keys and admin automation credentials separate. Runtime keys should create and inspect agent requests; management credentials should be narrow, audited, and issued only to trusted automation.
Contact us for enterprise automation · Authentication and API key handling
Frequently asked questions
Is this the exhaustive public runtime API?
Yes for agent runtime calls under /api/centcom/v1. Dashboard, admin, auth, and Slack routes are not part of the public runtime contract.
Which endpoints should an agent call first?
Most agents call POST /requests/control-map for high-risk policies, then POST /requests if routing is satisfiable, and then wait for the signed webhook callback.
Can one person satisfy several role mappings?
Yes. Operator roles are stored as an array, and external role mappings can point multiple external roles to the same reviewer. Separation-of-duties policies still require distinct people for distinct approvals.