Agents
Agents are artificial intelligence assistants that can interact with your customers across communication channels such as WhatsApp, Telegram, Instagram, and more.
Agent endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents | List every agent |
GET | /v1/agents/{agentId} | Get a specific agent |
POST | /v1/agents | Create a new agent |
PATCH | /v1/agents/{agentId} | Update an agent |
DELETE | /v1/agents/{agentId} | Delete an agent |
Prompt (automatic versioning)
Every prompt write creates a new entry in the history and updates the agent's activePromptId in sync with systemPrompt.
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents/{agentId}/prompt | Get the active prompt |
POST | /v1/agents/{agentId}/prompt | Write the full prompt (new version) |
PATCH | /v1/agents/{agentId}/prompt | Edit (oldText/newText, fuzzy or regex) |
GET | /v1/agents/{agentId}/prompt/versions | List versions |
GET | /v1/agents/{agentId}/prompt/versions/{versionId} | Get a single version |
Sub-agents
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents/{agentId}/subagents | List connected sub-agents |
GET | /v1/agents/{agentId}/subagents/available | List connectable agents |
POST | /v1/agents/{agentId}/subagents | Connect a sub-agent by ID |
POST | /v1/agents/{agentId}/subagents/create | Create + connect a new sub-agent |
PATCH | /v1/agents/{agentId}/subagents/{subagentId} | Update the connection configuration |
DELETE | /v1/agents/{agentId}/subagents/{subagentId} | Disconnect (without deleting the agent) |
To manage a sub-agent's prompt, use the regular Prompt endpoints with the sub-agent's agentId.
Guardrails
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents/{agentId}/guardrails | Get the guardrails configuration |
PATCH | /v1/agents/{agentId}/guardrails | Update the guardrails |
Assist rules
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents/{agentId}/assist-rules | Get the human-assist rules |
PATCH | /v1/agents/{agentId}/assist-rules | Update the rules |
Schedule
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents/{agentId}/schedule | Get the operating schedule |
PATCH | /v1/agents/{agentId}/schedule | Update the schedule (per-day merge) |
Knowledge base
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/agents/{agentId}/knowledge | List entries (?status=&limit=) |
GET | /v1/agents/{agentId}/knowledge/{knowledgeId} | Get a single entry |
POST | /v1/agents/{agentId}/knowledge | Create entries from public URLs or raw text (content) |
POST | /v1/agents/{agentId}/knowledge/upload | Upload files (multipart/form-data, ≤ 20 MB) |
POST | /v1/agents/{agentId}/knowledge/web | Ingest web URLs |
PATCH | /v1/agents/{agentId}/knowledge/{knowledgeId} | Update / reprocess / edit content |
DELETE | /v1/agents/{agentId}/knowledge/{knowledgeId} | Delete an entry |
POST | /v1/agents/{agentId}/knowledge/{knowledgeId}/reparse | Reprocess the original source |
Consejo
For API keys with access to multiple workspaces, you must include ?workspace={workspaceId} in any write operation against /v1/agents/....