A Complete Guide to the API

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.

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.

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.

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.

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.

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. 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.

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.

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.

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.

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.

# 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.

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, split keys by agent, tool, department, or environment for clearer ownership, scopes, and evidence.

Related resources