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)
- Add an HTTP Request node
- Set method to POST
- Set URL to
https://api.agenticcontrolplane.com/<workspace>/agents/<profileId>/run - Under Authentication, select Header Auth with name
Authorizationand valueBearer YOUR_API_KEY - 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)
- Add a Webhooks by Zapier action step
- Choose POST as the action event
- Set URL to
https://api.agenticcontrolplane.com/<workspace>/agents/<profileId>/run - Under Headers, add
Authorization: Bearer YOUR_API_KEYandContent-Type: application/json - Set Data to:
input: Find all deals closing this month and flag any at risk
context__region: EMEA
context__quarter: Q1
- Map the
outputfield 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
- Your request is authenticated via the API key
- The agent profile is loaded (system prompt, model, allowed tools, limits)
contextvalues are added to the system prompt- A conversation and run record are created in Firestore
- The agent runs through
runCompletionLoop, calling tools and streaming results - Each tool call is checked for identity, policy, and rate limits
- The run record is updated with final status, token counts, and cost
- Usage is recorded for billing and the audit log entry is written
- The response is returned, or the SSE stream ends with a
doneevent
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:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex