Build Agents with the REST API

ACP’s public API lets you create, manage, and invoke agents programmatically. Every agent you create through the API gets the same governance as agents created through the dashboard — identity verification, scope enforcement, content scanning, and audit logging.

Authentication

All API requests use gsk_ API keys. Create one in the ACP dashboard under Settings → API Keys.

curl -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  https://api.makeagents.run/myworkspace/api/v1/agents

The key format is gsk_{slug}_{random}. ACP extracts the workspace slug from the key to route requests to the correct tenant.

Create an agent

curl -X POST \
  -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  https://api.makeagents.run/myworkspace/api/v1/agents \
  -d '{
    "name": "Sales Assistant",
    "model": "gpt-4o",
    "systemPrompt": "You are a helpful sales assistant with access to Salesforce.",
    "tools": ["salesforce.query", "salesforce.getRecord", "salesforce.search"],
    "temperature": 0.3
  }'

Response:

{
  "id": "agent_7f8a9b0c1d2e",
  "name": "Sales Assistant",
  "model": "gpt-4o",
  "tools": ["salesforce.query", "salesforce.getRecord", "salesforce.search"],
  "createdAt": "2026-03-15T10:30:00Z",
  "status": "active"
}

List agents

curl -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  https://api.makeagents.run/myworkspace/api/v1/agents

Returns all agents in your workspace.

Get an agent

curl -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  https://api.makeagents.run/myworkspace/api/v1/agents/agent_7f8a9b0c1d2e

Update an agent

curl -X PUT \
  -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  https://api.makeagents.run/myworkspace/api/v1/agents/agent_7f8a9b0c1d2e \
  -d '{
    "name": "Sales Assistant v2",
    "tools": ["salesforce.query", "salesforce.getRecord", "salesforce.search", "salesforce.createRecord"],
    "temperature": 0.2
  }'

Delete an agent

curl -X DELETE \
  -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  https://api.makeagents.run/myworkspace/api/v1/agents/agent_7f8a9b0c1d2e

Run an agent

Invoke an agent with a user message. The agent runs with the full governance pipeline — identity, scopes, content scanning, rate limits.

curl -X POST \
  -H "Authorization: Bearer gsk_myworkspace_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  https://api.makeagents.run/myworkspace/api/v1/agents/agent_7f8a9b0c1d2e/run \
  -d '{
    "message": "What opportunities are closing this month?",
    "userToken": "eyJhbGciOiJSUzI1NiIs..."
  }'

The userToken is the end-user’s JWT from your identity provider. ACP verifies it and enforces the user’s scopes on every tool call the agent makes. This means the agent can only access what the user is allowed to access.

Response:

{
  "runId": "run_3e4f5a6b7c8d",
  "status": "completed",
  "output": "Based on your Salesforce data, there are 12 opportunities closing this month totaling $847,000...",
  "toolCalls": [
    {
      "tool": "salesforce.query",
      "input": { "query": "SELECT Name, Amount, CloseDate FROM Opportunity WHERE CloseDate = THIS_MONTH" },
      "result": "success",
      "latencyMs": 230
    }
  ],
  "usage": {
    "promptTokens": 450,
    "completionTokens": 180,
    "costCents": 1.26
  }
}

Governance for API-created agents

API-created agents go through the same governance pipeline as dashboard-created agents:

1. Identity — The userToken JWT is verified against your IdP’s JWKS endpoint
2. Scopes — Each tool call checks the user’s scopes against the tool’s requirements
3. Immutable rules — SSN, credit card, and SSRF patterns are blocked (cannot be disabled)
4. Content scanning — PII detection on inputs and outputs
5. Rate limits — Per-user rate limits enforced
6. Plan limits — Subscription tier limits on agent runs, tool calls, and spending
7. Audit logging — Every action attributed to the specific user, not the API key

The API key identifies the workspace. The userToken identifies the human. Both are required for agent runs.

Audit attribution

In the audit log, API-created agent runs show:

{
  "sub": "auth0|8f3a2b1c9d4e5f6a",
  "source": "api",
  "agentId": "agent_7f8a9b0c1d2e",
  "agentName": "Sales Assistant",
  "tool": "salesforce.query",
  "ok": true
}

The source: "api" field distinguishes API-triggered runs from dashboard or MCP client runs. The user’s identity is still the verified JWT — not the API key.

Rate limits and plan tiers

Use cases

CI/CD integration — Create agents that run as part of your deployment pipeline. The pipeline’s service identity is verified, and every tool call is audited.

Custom chat apps — Build a customer-facing chat application. Each end-user authenticates via your IdP, and the agent runs with their permissions.

Batch processing — Programmatically run agents against a list of inputs. Each run carries the initiating user’s identity.

Testing — Create test agents with specific tool configurations. Run them with test user tokens to verify governance rules.

Back to guides · Connect MCP servers → · SOC 2 audit trails →