Embeddable

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.

4 min readPublished by Daniel Sternlicht on Nov 22, 2026, 10:57 AM UTCUpdated Nov 22, 2026

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 pathWhat it doesUsage tab tokens
POST /agentsCreate an agent, and build it if you send a prompt1
GET /agentsList agents0
GET /agents/:agentIdGet one agent0
POST /agents/:agentId/runRun an agent once and wait for the result1
DELETE /agents/:agentIdDelete an agent0

An agent that doesn't exist, or belongs to another workspace, returns 404 not_found.

Create an agent

POST /agents

FieldTypeRequiredDescription
namestringyesDisplay name, up to 255 characters.
descriptionstringnoA short note on what the agent does.
promptstringnoWhat 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 editorUrl to 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 parameterDefaultDescription
page1Page number, starting at 1.
limit20Agents 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.)

FieldDescription
statuscompleted or failed.
summaryWhat the run did, in plain words.
logsStep-by-step log lines with timestamps.
tokensUsedAI model tokens the run used. This is not the Usage tab count.
durationMsHow long the run took.
errorSet 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.