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	Optionally preview reviewers, role mappings, on-shift coverage, and policy satisfiability for complex routing.
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 credential is enough. For production, give each agent its own Agent Credential, and let the named parts of a multi-agent system identify themselves with the Contro1-Sub-Agent header: Contro1 registers each part under its agent the first time it is seen.

Runtime base URL

export CONTRO1_API_KEY="cc_live_..."
export CONTRO1_BASE_URL="https://api.contro1.com/api/centcom/v1"

curl "$CONTRO1_BASE_URL/requests" \
  -H "Authorization: Bearer $CONTRO1_API_KEY"

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.

Build the context at the gate, not in the prompt. Copy the exact tool input your code intercepted (machine-observed fact), attach the message or event that triggered the run, and carry the agent's justification by making reason a required parameter of the risky tool. Keep agent-written text labeled as agent-reported: it informs the reviewer but must never change routing or risk_level, because a prompt-injected agent writes very persuasive reasons.

Create an approval request

curl -X POST "$CONTRO1_BASE_URL/requests" \
  -H "Authorization: Bearer $CONTRO1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "approval",
    "title": "Approve 18% discount for Acme renewal",
    "source": { "integration": "sales-agent" },
    "actor": {
      "agent_id": "sales-renewal-agent",
      "agent_name": "Sales Renewal Agent"
    },
    "risk_level": "medium",
    "trace_id": "trc_acme_renewal_2026_06_08",
    "continuation": { "mode": "decision" },
    "callback_url": "https://example.com/webhooks/contro1"
  }'

Reviewer context and trust rules

Step 3: preview routing when risk is high

Use control-map when the agent or operator needs a routing preview for role-based approvals, separation of duties, manual routing targets, on-shift coverage, or quorum.

The approval request is still the source of truth. If routing is not ready, treat the preview as context, not a denial; create or keep the approval request when the action still needs review and wait for the final signed decision.

Preview the control path

curl -X POST "$CONTRO1_BASE_URL/requests/control-map" \
  -H "Authorization: Bearer $CONTRO1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "approval",
    "title": "Export customer segment for campaign",
    "required_role": "marketing_manager",
    "risk_level": "high",
    "source": { "integration": "campaign-agent" },
    "actor": { "agent_id": "campaign-agent" }
  }'

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.

Record an autonomous action

curl -X POST "$CONTRO1_BASE_URL/audit-records" \
  -H "Authorization: Bearer $CONTRO1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "tool.call",
    "summary": "Read CRM opportunity and generated proposal draft",
    "source": { "integration": "sales-agent" },
    "actor": { "agent_id": "sales-renewal-agent" },
    "trace_id": "trc_acme_renewal_2026_06_08",
    "outcome": "success",
    "severity": "info",
    "tool_calls": [
      { "name": "crm.read_opportunity", "outcome": "success", "output_summary": "Loaded renewal terms and account owner" }
    ]
  }'

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. The credential says which agent acted, and the Contro1-Sub-Agent header says which part of it. 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.

Identity is never taken from the body. An actor.agent_id that differs from the credential is refused with agent_identity_mismatch, so one agent cannot write into another agent's record by naming it.

The same claimed-versus-verified thinking applies inside each request: tool_calls, retrieved_context, and the triggering event are machine-observed when your gate recorded them; a justification or summary the model wrote is agent-reported. Both belong in the record, but label them so reviewers and auditors know which is fact and which is the agent's claim.

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.

Read request state

curl "$CONTRO1_BASE_URL/requests/req_123" \
  -H "Authorization: Bearer $CONTRO1_API_KEY"

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.

Export evidence

# One decision
curl "$CONTRO1_BASE_URL/requests/req_123/evidence" \
  -H "Authorization: Bearer $CONTRO1_API_KEY"

# One agent
curl "$CONTRO1_BASE_URL/agents/agt_123/evidence" \
  -H "Authorization: Bearer $CONTRO1_API_KEY"

# One agent as CSV
curl "$CONTRO1_BASE_URL/agents/agt_123/evidence?format=csv" \
  -H "Authorization: Bearer $CONTRO1_API_KEY"

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
A named part of the agent did the work	Any call with the Contro1-Sub-Agent header
The agent is already instrumented with OpenTelemetry	POST /otel/v1/traces from its OTLP exporter
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

Make the approval the gate, not a suggestion

The signed webhook is cryptographic proof of a human decision. Verify it inside the system that executes the action - not inside the agent. Any tool that must never run without human sign-off (payments, deploys, data deletion) should refuse to act without a verified approval; that way no agent, including shadow agents nobody registered, can trigger it by skipping Contro1.

Verify the signature and reject timestamps older than 5 minutes (replay protection; the timestamp marks callback delivery, not request creation, so long SLAs are unaffected).
Bind the approval to the exact action parameters via metadata / correlation_id - never treat "an approval arrived" as permission for a different action.
Execute each request_id exactly once (idempotency on your side).
When in doubt, confirm state directly with GET /v1/requests/:id using a read-only API key.

Full guardrail pattern with code: Webhooks

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 a routing preview is useful. The approval request itself remains the workflow gate.

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, give each agent its own credential, and let the parts of a multi-agent system identify themselves with the Contro1-Sub-Agent header rather than with extra keys.