Agents API
Agents are AI-powered automations that execute playbooks against your contacts. The Agents API lets you create, configure, trigger, and monitor them.
List Agents
Section titled “List Agents”GET /v1/agentsRequired scope: agents:read
Query Parameters
Section titled “Query Parameters”| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | boolean | — | Filter by enabled/disabled status. |
playbook_template | string | — | Filter by playbook template. |
limit | number | 20 | Results per page (1–100). |
offset | number | 0 | Pagination offset. |
Response — 200 OK
Section titled “Response — 200 OK”{ "status": "success", "agents": [ /* agent objects */ ], "total": 5, "limit": 20, "offset": 0}Create an Agent
Section titled “Create an Agent”POST /v1/agentsRequired scope: agents:write
Request Body
Section titled “Request Body”| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Agent display name. |
description | string | no | Human-readable description. |
playbook_template | string | no | Predefined playbook template. |
capabilities | string[] | no | List of capabilities. |
identity_id | string | no | Identity used for outreach. |
playbook | object | no | Custom playbook configuration. |
monitoring | object | no | Monitoring configuration. |
llm_config | object | no | LLM provider/model configuration. |
enabled | boolean | no | Whether the agent is active. |
Response — 201 Created
Section titled “Response — 201 Created”{ "status": "success", "agent": { /* agent object */ }}Get an Agent
Section titled “Get an Agent”GET /v1/agents/:idRequired scope: agents:read
Update an Agent
Section titled “Update an Agent”PATCH /v1/agents/:idRequired scope: agents:write
Send only the fields you want to update.
Delete an Agent
Section titled “Delete an Agent”DELETE /v1/agents/:idRequired scope: agents:write
Deleting an agent also removes all of its associated runs.
List Agent Runs
Section titled “List Agent Runs”GET /v1/agents/:id/runsRequired scope: agents:read
Query Parameters
Section titled “Query Parameters”| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Results per page (1–100). |
offset | number | 0 | Pagination offset. |
status | string | — | Filter by run status. |
Get a Single Run
Section titled “Get a Single Run”GET /v1/agents/runs/:runIdRequired scope: agents:read
Returns the run enriched with contact details.
Trigger an Agent Run
Section titled “Trigger an Agent Run”POST /v1/agents/:id/triggerRequired scope: agents:trigger
Request Body
Section titled “Request Body”| Field | Type | Required | Description |
|---|---|---|---|
contact_ids | string[] | no | Specific contacts to target. If omitted, the agent uses its default targeting. |
Response — 200 OK
Section titled “Response — 200 OK”{ "status": "success", "job_id": "job_xyz789"}Approve a Pending Action
Section titled “Approve a Pending Action”POST /v1/agents/runs/:runId/contacts/:contactId/actions/:actionIndex/approveRequired scope: agents:approve
Reject a Pending Action
Section titled “Reject a Pending Action”POST /v1/agents/runs/:runId/contacts/:contactId/actions/:actionIndex/rejectRequired scope: agents:approve