Quickstart

In five minutes you’ll create an agent, run it, and read back every tool call it made — entirely over the API. You’ll need a workspace (sign up free) and an API key.

1. Get a key

In the console, go to Settings → API Keys, create a key, and copy it. Export it so the snippets below just work:

export ACP_KEY="gsk_acme_…"
export ACP="https://api.agenticcontrolplane.com"

Your workspace slug is the middle of the key — acme here. You’ll need it for the governance calls in step 4.

2. Create an agent

An agent profile is the unit you govern: a model, a system prompt, the tools it may use, and hard caps on budget, tool calls, and runtime.

curl -sX POST "$ACP/api/v1/agents" \
  -H "Authorization: Bearer $ACP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release Notes Writer",
    "model": "claude-sonnet-4-6",
    "systemPrompt": "Summarize merged PRs into crisp release notes.",
    "enabledTools": ["github.list_pull_requests"],
    "maxBudgetCents": 50,
    "maxToolCalls": 20
  }'

{ "ok": true, "id": "a7Kf9_Qe2" }

Hold onto that id.

3. Run it

curl -sX POST "$ACP/api/v1/agents/a7Kf9_Qe2/run" \
  -H "Authorization: Bearer $ACP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Draft release notes for everything merged this week." }'

The agent runs under the caps you set. Every tool call it makes is checked against your workspace policy first — if a call isn’t allowed, it’s denied and logged, and the run keeps going. See Run triggers for streaming and the full response shape.

4. Read back what it did

Now query the audit log. Every tool call the agent made — allowed or denied — is there, with the decision and the identity behind it:

curl -s "$ACP/acme/admin/audit?limit=20" \
  -H "Authorization: Bearer $ACP_KEY"

{
  "entries": [
    {
      "tool": "github.list_pull_requests",
      "decision": "allow",
      "agentName": "Release Notes Writer",
      "sessionId": "run_a7Kf9_Qe2_01",
      "ts": "2026-06-25T17:04:11.218Z"
    }
  ],
  "count": 1,
  "since": "2026-06-25T16:49:11.000Z",
  "limit": 20
}

Reading the audit log needs a key with the admin.audit.read scope (or *). Replace acme with your own slug.

What you just did

You provisioned a governed agent, ran it, and pulled its full audit trail — the same three things the console does, now scriptable. From here:

• Tighten the rules → set the policy that governs this agent in Policies.
• Manage the fleet → list, patch, and version agents in the Agents reference.
• Wire it into automation → trigger runs from n8n, Zapier, or cron in Run triggers.