Agents API reference
Every /v1/agents endpoint: create an AI agent (optionally built from a prompt), list, get, run and delete, with parameters and responses.
AI agents are automations that run on a schedule, on demand or when something happens. These endpoints create, run and delete agents in the workspace your API key belongs to. All paths are relative to https://api.embeddable.co/v1, and every request needs Authorization: Bearer emb_live_.... For keys, costs and error codes, see API authentication, limits and errors.
Summary
| Method and path | What it does | Usage tab tokens |
|---|---|---|
POST /agents | Create an agent, and build it if you send a prompt | 1 |
GET /agents | List agents | 0 |
GET /agents/:agentId | Get one agent | 0 |
POST /agents/:agentId/run | Run an agent once and wait for the result | 1 |
DELETE /agents/:agentId | Delete an agent | 0 |
An agent that doesn't exist, or belongs to another workspace, returns 404 not_found.
Create an agent
POST /agents
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name, up to 255 characters. |
description | string | no | A short note on what the agent does. |
prompt | string | no | What the agent should do. If set, the AI builder starts building it. |
curl -X POST https://api.embeddable.co/v1/agents \
-H "Authorization: Bearer emb_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Daily sales summary",
"prompt": "Every morning at 8, email me yesterday'\''s new orders"
}'
Response: 202 Accepted
{
"agentId": "j81csCCat6",
"jobId": "job_1776081422363_3eba6668084f",
"status": "pending",
"message": "Agent created. Poll GET /v1/jobs/:jobId for build status.",
"editorUrl": "https://embeddable.co/app/your-workspace/agents/j81csCCat6"
}
Without a prompt, no build starts. jobId is left out and status is created:
{
"agentId": "j81csCCat6",
"status": "created",
"message": "Agent created.",
"editorUrl": "https://embeddable.co/app/your-workspace/agents/j81csCCat6"
}
The call counts as 1 token in the Usage tab either way.
About agent builds
- Poll the build with
GET /jobs/:jobId. See the Jobs API reference. - Unlike widget builds, an agent build may stop to ask a question, such as which email service to use. The conversation is saved to the agent's chat. Open
editorUrlto read the question and reply there. - Agents don't use the workspace brand kit, and there is no API endpoint for editing an agent after it's built. Continue in the editor.
List agents
GET /agents
| Query parameter | Default | Description |
|---|---|---|
page | 1 | Page number, starting at 1. |
limit | 20 | Agents per page, up to 100. |
Agents come back newest-updated first.
{
"agents": [
{
"agentId": "j81csCCat6",
"name": "Daily sales summary",
"description": null,
"status": "DRAFT",
"lastRunAt": null,
"lastRunStatus": null,
"totalRuns": 0,
"createdAt": "2026-11-22T10:12:03.000Z",
"updatedAt": "2026-11-22T10:12:03.000Z",
"editorUrl": "https://embeddable.co/app/your-workspace/agents/j81csCCat6"
}
],
"total": 3,
"page": 1,
"pages": 1,
"limit": 20
}
Each agent also includes its stored fields, such as id, organizationId, userId (the author), model, maxIterations, lastRunError and totalTokensUsed.
status is DRAFT, ACTIVE, PAUSED or ERROR. New agents start as DRAFT.
Get an agent
GET /agents/:agentId
Returns the same fields as the list, inside an agent object.
Run an agent
POST /agents/:agentId/run
Runs the agent once, now. The request stays open until the run finishes, so allow a long timeout in your HTTP client.
The body accepts an input object, but the run doesn't use it yet. The agent runs the same way as a manual run.
Response: 200
{
"status": "completed",
"summary": "Sent the summary of 14 orders to [email protected]",
"logs": [
{ "timestamp": "2026-11-22T08:00:01.000Z", "message": "Starting agent execution for j81csCCat6" }
],
"tokensUsed": 5321,
"durationMs": 8410
}
(Example values.)
| Field | Description |
|---|---|
status | completed or failed. |
summary | What the run did, in plain words. |
logs | Step-by-step log lines with timestamps. |
tokensUsed | AI model tokens the run used. This is not the Usage tab count. |
durationMs | How long the run took. |
error | Set when the run failed. |
A run can return 200 with status: "failed". Check status, not only the HTTP code. If the run can't start or crashes, the API returns the error status with error: "execution_failed" or the error message, plus summary when there is one. A successful (200) run counts as 1 token in the Usage tab.
The run is saved in the agent's run history.
Delete an agent
DELETE /agents/:agentId
Deletes the agent with its code, saved secrets and triggers. This can't be undone.
{ "success": true }
Questions? Email us through the contact page.
Did this answer your question?
Your feedback helps us improve.
