Core API
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.
Start here if you are wiring an AI agent, workflow, or tool into Contro1. This guide explains the runtime API as a developer story: create a key, preview control, create approval requests, log autonomous actions, trace runs, read state, and export signed evidence.
Key takeaways
- Use /api/centcom/v1 for agent runtime traffic from your agents, workflows, tools, and connectors.
- POST /requests is the main call when an agent must pause and ask a human to approve, reject, decide, or review something.
- POST /audit-records is for actions that already happened or do not need a pause, but still need traceability.
- Use trace_id, actor.agent_id, tool_calls, and retrieved_context when you want agent inventory, reconstruction, and evidence to be useful later.
- Evidence exports return signed packets with agent identity, trace context, decisions, timestamps, and integrity metadata.
The mental model
Contro1 sits at the boundary where an agent is about to do something that needs accountability. The agent can ask for approval before the action, record an autonomous action after it happens, or fetch the state and evidence attached to a previous decision.
The runtime API is intentionally small. You use one bearer API key, one v1 base URL, and a handful of endpoints that cover control, approvals, audit, traceability, and proof.
| Need | Call | Why |
|---|---|---|
| Check whether a request can be routed | POST /requests/control-map | Preview reviewers, role mappings, on-shift coverage, and policy satisfiability before creating the request. |
| Pause for a human decision | POST /requests | Create the approval, review, yes/no, free-text, or decision request. |
| Read request state | GET /requests/:id | Poll or inspect the current state if you are not only relying on webhook callbacks. |
| Cancel a pending request | DELETE /requests/:id | Stop a request before an operator completes it. |
| Log an action without pausing | POST /audit-records | Record autonomous activity, tool calls, workflow steps, or policy events. |
| Rebuild one conversation or case | GET /threads/:thread_id | Read requests and audit records that share the same thread. |
| Rebuild one agent run | GET /traces/:trace_id | Read the execution span across requests, tool calls, and sub-agents. |
| Inspect agent identity and scope | GET /agents/:agent_id | See the runtime view of one agent: verification, status, scopes, and activity. |
| Export proof | GET /requests/:id/evidence or /agents/:id/evidence | Return signed evidence packets for one decision or one agent. |
Step 1: authenticate once
Every runtime call uses the same base URL and bearer key. For a pilot, one API key is enough: it creates a verified base agent and lets Contro1 discover caller-declared agents as claimed children. For production, use separate keys by agent, tool, department, or environment when you want cleaner ownership and isolation.
Step 2: decide if the agent should pause
Use a request when the agent must wait before continuing. This is the normal path for refunds, discounts, data exports, production changes, customer messages, access changes, and other actions where a human decision should exist before the agent acts.
The request should explain the action, who or what is asking, what the risk is, and how the agent should continue after the decision. If your workflow can resume from a webhook, include callback_url and verify the signed callback before continuing.
Step 3: preview routing when risk is high
Use control-map before creating a request when the agent needs to know whether a policy can actually be satisfied. This is useful for role-based approvals, separation of duties, manager fallback, on-shift coverage, or workflows where a missing reviewer should stop the agent before it creates noise.
If the response says the path is satisfiable, create the request. If not, the agent can stop, ask for setup, or take a safer branch.
Step 4: log actions that do not pause
Not every event needs human approval. Use audit records when the agent did something that should be searchable later: a tool call, a policy warning, a low-risk automated action, a model-generated recommendation, or a retrieval step that explains why a later approval was requested.
Audit records are also how you make trace views richer. They can share trace_id, thread_id, correlation_id, actor, tool_calls, and metadata with approval requests.
Step 5: make identity and trace useful
The smallest request can work without trace fields, but the operating value comes from sending enough context to reconstruct what happened. actor.agent_id tells Contro1 which agent claims the action. trace_id links all events from one run. parent_trace_id links sub-agent runs to parent runs. tool_calls and retrieved_context explain what the agent used.
A caller-declared actor.agent_id is treated as claimed until the organization verifies it. That keeps onboarding easy without trusting a runtime string as a verified identity.
| Field | Send when | What it unlocks |
|---|---|---|
| actor.agent_id | Every agent request or audit record | Agent Inventory, per-agent history, claimed vs verified identity. |
| actor.agent_name | When available | Readable inventory names instead of raw ids. |
| trace_id | Every step in one run | Trace reconstruction across requests, records, tools, and callbacks. |
| parent_trace_id | Sub-agent or delegated run | Tree view of parent and child agent work. |
| thread_id | Conversation or case timeline | Combined timeline of related requests and audit records. |
| correlation_id | Business object id exists | Search by order, customer, incident, ticket, or workflow id. |
| tool_calls[] | A tool was called | Reviewer context and later evidence about what the agent actually did. |
| retrieved_context[] | RAG/search/DB context was used | Proof of the data behind the agent decision. |
Step 6: read state and continue
Most production integrations continue from a signed webhook callback. Polling is still useful for development, retries, dashboards, and systems that cannot receive callbacks.
GET /requests/:id returns the request state, operator response, protocol response, routing details, timestamps, and decision context. Your agent should continue only after the request reaches a completed decision state that your workflow accepts.
Step 7: reconstruct what happened
Use thread timelines when you want the story of a case or conversation. Use trace timelines when you want the story of one agent execution. Use agent trail when you want the history of one specific agent.
| Question | Call |
|---|---|
| What happened in this customer case? | GET /threads/:thread_id |
| What happened in this agent run? | GET /traces/:trace_id |
| What did this agent do over time? | GET /agents/:agent_id/trail |
| What agents has this key/org discovered? | GET /agents |
| What is this agent allowed to do? | GET /agents/:agent_id |
Step 8: export signed evidence
Evidence endpoints return signed packets that include agent identity, trace context, tool calls, retrieved context, decisions, timestamps, and an integrity signature.
Use request evidence when you need proof for one decision. Use agent evidence when you need proof of the activity attached to one agent. Add ?format=csv to the agent evidence endpoint when you need a spreadsheet-friendly export.
Which endpoint should I call?
A useful rule: if the agent has not acted yet and needs permission, create a request. If the agent already acted or the event is informational, create an audit record. If you need to understand or prove what happened, read request state, trace, trail, or evidence.
| Situation | Call |
|---|---|
| Agent wants to send an offer, discount, refund, export, deploy, or message | POST /requests |
| Agent wants to know whether the right reviewers exist before asking | POST /requests/control-map |
| Agent performed a low-risk step and you want a record | POST /audit-records |
| Agent called a tool and you want it visible in the run history | POST /audit-records with action=tool.call |
| Workflow needs the decision result without waiting for a webhook | GET /requests/:id |
| Workflow should stop a pending approval | DELETE /requests/:id |
| Developer wants the entire run tree | GET /traces/:trace_id |
| Developer wants everything tied to a case or conversation | GET /threads/:thread_id |
| Security wants to inspect agent inventory through the runtime API | GET /agents |
| Compliance wants proof for one decision or agent | GET /requests/:id/evidence or GET /agents/:id/evidence |
Frequently asked questions
Which base URL should my agent use?
Use https://api.contro1.com/api/centcom/v1 for runtime calls from agents, workflows, tools, and connectors.
Should my agent call control-map every time?
No. Use it for higher-risk or policy-sensitive actions where the agent should know whether approval routing is satisfiable before creating the request.
Do I need both requests and audit records?
Usually yes. Requests pause the workflow for a human decision. Audit records capture context, autonomous steps, tool calls, and events that make the final decision easier to understand later.
Can I start with one API key?
Yes. One key is fine for quick-start discovery. As you move to production, split keys by agent, tool, department, or environment for clearer ownership, scopes, and evidence.