Trigger an Agent
Start an Agent execution on demand via the Squadbase API.
https://api.squadbase.dev/v0/agent/{agentId}/triggerStarts a new execution of an Agent. Returns 201 Created as soon as the execution record is created and the sandbox is started; the agent then runs in the background and delivers its result to the configured notification channels.
Request headers
Prop
Type
Required
The x-api-key header is required on every request — see Authentication. Since this endpoint takes a JSON body, also send Content-Type: application/json.
Use an Idempotency-Key to safely retry a trigger after a network error without risking a duplicate execution. Reuse the same key for retries of the same logical request, and a new key for a genuinely new run. Keys are scoped per API key.
Path parameters
Prop
Type
Required
Request body
application/json. Both fields are optional.
Prop
Type
Required
{
"message": "Analyze this week's signup trends",
"title": "Weekly signup analysis"
}Response — 201 Created
Returns an execution object. Save the executionId to poll for status and fetch the result.
{
"executionId": "uuid", // handle for status / result lookups
"agentId": "uuid",
"status": "RUNNING",
"title": "Weekly signup analysis",
"message": "Analyze this week's signup trends",
"startedAt": "ISO8601",
"completedAt": null,
"createdAt": "ISO8601"
}Example
curl -X POST 'https://api.squadbase.dev/v0/agent/<AGENT_ID>/trigger' \
-H 'x-api-key: <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <UNIQUE_KEY>' \
-d '{"message":"Analyze this week'\''s signup trends","title":"Weekly analysis"}'import requests
response = requests.post(
"https://api.squadbase.dev/v0/agent/<AGENT_ID>/trigger",
headers={
"x-api-key": "<YOUR_API_KEY>",
"Content-Type": "application/json",
"Idempotency-Key": "<UNIQUE_KEY>",
},
json={
"message": "Analyze this week's signup trends",
"title": "Weekly analysis",
},
)
execution = response.json()
print(execution["executionId"], execution["status"])const response = await fetch(
"https://api.squadbase.dev/v0/agent/<AGENT_ID>/trigger",
{
method: "POST",
headers: {
"x-api-key": "<YOUR_API_KEY>",
"Content-Type": "application/json",
"Idempotency-Key": "<UNIQUE_KEY>",
},
body: JSON.stringify({
message: "Analyze this week's signup trends",
title: "Weekly analysis",
}),
},
);
const execution = await response.json();
console.log(execution.executionId, execution.status);See Errors for error responses.