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 optionally previews routing for complex approval paths.
  • 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.

MethodEndpointUse it for
POST/requests/control-mapOptionally preview role mappings, fallback reviewers, on-shift capacity, and approval-policy satisfiability for complex routing.
POST/requestsCreate 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/:idFetch request state, response, operator details, policy context, and protocol response.
GET/requests/:id/evidenceExport one JSON evidence packet with request metadata, policy context, reviewer decision, webhook status, timestamps, and final protocol response.
DELETE/requests/:idCancel a pending request before an operator has completed it.
POST/audit-recordsRecord an autonomous action that should be audited without pausing for human approval.
GET/audit-recordsSearch audit records by actor, source, workflow, outcome, severity, correlation_id, external_request_id, thread_id, tags, text, or date range.
GET/audit-records/:idFetch one audit record.
GET/threads/:thread_idFetch the combined timeline for a thread across requests and audit records.
GET/agentsList the agents that have called Contro1, with verification status and least-agency scopes.
GET/agents/:agent_idFetch one agent: identity, verification, scopes, and status.
GET/agents/:agent_id/trailFull decision trail for one agent (add ?trace_id= to scope to one run).
GET/agents/:agent_id/evidenceSigned evidence bundle for one agent (add ?format=csv for a spreadsheet).
GET/traces/:trace_idFull 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.

Contro1 Python SDK · Contro1 JavaScript and TypeScript SDK

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 create POST /requests for actions that need approval and wait for the signed webhook callback. Use POST /requests/control-map when complex routing needs a preview.

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.

Related resources

A Complete Guide to the API

A practical walkthrough of the Contro1 runtime API: which endpoint an agent calls, when to call it, what to send, and how approvals, audit records, traces, and evidence fit together.

Contro1 Python SDK

Install and use the framework-agnostic Contro1 Python SDK to request human approvals or input, verify signed webhooks, log autonomous actions, and fetch audit evidence.

Contro1 JavaScript and TypeScript SDK

Install and use @contro1/sdk in Node, TypeScript, Express, Fastify, or Next.js backends to create approval requests, verify webhooks, and write audit records.