Trigger an Agent

Starts 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

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

Request body

application/json. Both fields are optional.

{
  "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"}'

See Errors for error responses.