Skip to content
Agentic Control Plane

Agent HTTP triggers

Send one POST request and an agent in your workspace runs. Use it from n8n, Zapier, Make, or anything else that can send HTTP. Each run is tied to the API key that started it, checked against your policy, and logged.

Endpoint

POST https://api.agenticcontrolplane.com/<your-workspace>/agents/<profileId>/run

Replace <your-workspace> with your workspace slug and <profileId> with the agent profile ID from your dashboard.

Authentication

Put your API key in the Authorization header:

Authorization: Bearer $ACP_KEY

Create API keys under Settings > API Keys in your dashboard. A key can have an expiry date.

API keys (gsk_*), Firebase tokens, and external JWTs from your configured identity provider all work here.

Request

{
  "input": "Find all cold leads from last week and draft follow-up emails",
  "context": {
    "region": "EMEA",
    "quarter": "Q1",
    "maxLeads": "20"
  },
  "stream": false
}
Field Type Required Description
input string Yes The goal or instruction for the agent
context object No Key-value pairs added to the agent’s system prompt
stream boolean No true returns SSE events. Default: false

Context injection

Use context to pass runtime details without editing the agent’s profile. The values are added to the system prompt like this:

Context provided by the caller:
- region: EMEA
- quarter: Q1
- maxLeads: 20

This helps when one agent handles many cases. Pass the customer ID, ticket number, or region from your automation.

Response (non-streaming)

{
  "id": "run_abc123",
  "status": "completed",
  "output": "I found 12 cold leads from last week. Here are the drafted follow-up emails...",
  "conversationId": "conv_xyz",
  "usage": {
    "promptTokens": 1500,
    "completionTokens": 800,
    "toolCallCount": 3,
    "estimatedCostCents": 2.45,
    "model": "gpt-4o",
    "durationMs": 4200
  },
  "stopReason": "goal_complete"
}
Field Description
id Unique run identifier (prefixed with run_)
status Always completed for non-streaming responses
output The agent’s final text response
conversationId Conversation ID, for viewing the full thread in the dashboard
usage.promptTokens Total input tokens consumed
usage.completionTokens Total output tokens generated
usage.toolCallCount Number of tool calls the agent made
usage.estimatedCostCents Estimated LLM cost in cents
usage.model Model used (from the agent profile)
usage.durationMs Total execution time in milliseconds
stopReason A label set when the run ends: goal_complete, max_tool_calls, or max_rounds

stopReason describes the run after it finished. It does not mean that cap stopped the run. The Agents reference lists which caps actually stop an API-triggered run.

Response (streaming)

Set "stream": true to receive Server-Sent Events while the agent works. It is the same SSE format the dashboard chat uses.

data: {"type":"text","text":"Searching for cold leads..."}

data: {"type":"tool_calls","toolCalls":[{"id":"tc_1","name":"salesforce.search","arguments":"{...}"}]}

data: {"type":"governance","tool":"salesforce.search","decision":"allowed","layers":{"identity":"verified","policy":"allowed","rate_limit":"under_limit"}}

data: {"type":"tool_result","toolCallId":"tc_1","name":"salesforce.search","result":"{...}"}

data: {"type":"text","text":"Found 12 cold leads. Drafting follow-up emails..."}

data: {"type":"done","conversationId":"conv_xyz","usage":{"promptTokens":1500,"completionTokens":800}}

Event types:

Event Description
text Streamed text from the agent
tool_calls Agent is calling one or more tools
governance The policy decision for a tool call (allowed, denied, or transformed)
tool_result Result returned from a tool
error An error occurred
done Run complete, with usage metadata

What gets checked

Agent triggers use the same in-process checks as dashboard chat. They do not go through the harness hook that Claude Code and other coding agents use.

  • Identity. The API key identifies the caller. ABAC policies and rate limits apply per caller, not per agent.
  • Tool calls. Each tool call inside the run is checked against your policy.
  • Audit log. The trigger and every tool call are logged with the caller’s identity. Find them under Activity in your dashboard.
  • Billing. Calls are unlimited on every plan. The triggered profile counts as one initiating agent for the month’s band. LLM token costs are tracked per user per day.

Only deny is enforced on these runs. Nobody is there to answer a hold, and the trigger prompt tells the agent not to ask for confirmation. A tool your policy would ask about runs without a hold. For anything you do not want running unattended, set deny for the api tier.

Error responses

Status Body Cause
400 {"error": "Missing required field: input"} No input in request body
400 {"error": "context must be a key-value object"} context is not an object
400 {"error": "Model \"...\" from profile is not enabled in chat config"} Agent’s model isn’t configured
400 {"error": "No API key for provider \"...\""} No LLM API key for the model’s provider
401 {"error": "Unauthorized"} Missing or invalid API key
404 {"error": "Agent profile not found"} Invalid profileId
429 {"error": "Daily AI usage limit reached..."} Per-user daily LLM cost cap hit

Examples

curl

export ACP_KEY="your-api-key-here"

curl -X POST https://api.agenticcontrolplane.com/acme/agents/PROFILE_ID/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACP_KEY" \
  -d '{
    "input": "Summarize open support tickets from this week",
    "context": { "team": "engineering" }
  }'

n8n (HTTP Request node)

  1. Add an HTTP Request node
  2. Set method to POST
  3. Set URL to https://api.agenticcontrolplane.com/<workspace>/agents/<profileId>/run
  4. Under Authentication, select Header Auth with name Authorization and value Bearer YOUR_API_KEY
  5. Set body to JSON:
{
  "input": "{{ $json.trigger_text }}",
  "context": {
    "customerId": "{{ $json.customer_id }}",
    "priority": "{{ $json.priority }}"
  }
}

The agent’s answer is in the output field. Send it to Slack, email, a database, or the next step in your workflow.

Zapier (Webhooks by Zapier)

  1. Add a Webhooks by Zapier action step
  2. Choose POST as the action event
  3. Set URL to https://api.agenticcontrolplane.com/<workspace>/agents/<profileId>/run
  4. Under Headers, add Authorization: Bearer YOUR_API_KEY and Content-Type: application/json
  5. Set Data to:
input: Find all deals closing this month and flag any at risk
context__region: EMEA
context__quarter: Q1
  1. Map the output field from the response to your next Zapier step.

Python

import requests

response = requests.post(
    "https://api.agenticcontrolplane.com/acme/agents/PROFILE_ID/run",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "input": "Check inventory levels and alert if any item is below threshold",
        "context": {"warehouse": "east-coast"},
    },
)

result = response.json()
print(result["output"])
print(f"Cost: {result['usage']['estimatedCostCents']}c in {result['usage']['durationMs']}ms")

What happens during a run

  1. Your request is authenticated via the API key
  2. The agent profile is loaded (system prompt, model, allowed tools, limits)
  3. context values are added to the system prompt
  4. A conversation and run record are created in Firestore
  5. The agent runs through runCompletionLoop, calling tools and streaming results
  6. Each tool call is checked for identity, policy, and rate limits
  7. The run record is updated with final status, token counts, and cost
  8. Usage is recorded for billing and the audit log entry is written
  9. The response is returned, or the SSE stream ends with a done event
Get started free →

Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Getting started