# API Quickstart — Create, Run, and Audit an Agent

Five minutes from API key to a governed agent run you can read back from the audit log. Pure curl.

# 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](https://cloud.agenticcontrolplane.com/login?from=%2Fonboarding)) 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:

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

```bash
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
  }'
```

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

Hold onto that `id`.

## 3. Run it

```bash
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](/docs/agent-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:

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

```json
{
  "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](/docs/api/policies).
- **Manage the fleet** → list, patch, and version agents in the [Agents reference](/docs/api/agents).
- **Wire it into automation** → trigger runs from n8n, Zapier, or cron in [Run triggers](/docs/agent-triggers).