Documentation

Agents API

Create, list, run, and delete AI agents via the Embeddable Developer API.

AI Agents are autonomous functions that run on schedules, on demand, or in response to webhooks. Use this API to provision agents from your code.

POST /v1/agents

Create a new agent. If you provide a prompt, an AI build is kicked off asynchronously to scaffold the agent's code. The build conversation is saved to chat history so a user can continue refining the agent in the UI.

Body

FieldTypeRequiredDescription
namestringyesDisplay name
descriptionstringnoShort description of what the agent does
promptstringnoIf set, kicks off an AI build with this prompt

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-org/agents/j81csCCat6"
}
FieldDescription
editorUrlDirect link to open and continue editing the agent in your Embeddable workspace

If you omit prompt, the agent is created in a draft state without a build job:

{
  "agentId": "...",
  "status": "created",
  "message": "Agent created.",
  "editorUrl": "https://embeddable.co/app/your-org/agents/..."
}

Token cost: 1

Agent builds may pause to ask clarifying questions (e.g. "Which email service?"). The conversation is persisted to chat history — open the agent in your Embeddable workspace UI to see the question and reply.

GET /v1/agents

List agents in your organization.

Query parameters

ParamTypeDefault
pagenumber1
limitnumber20

Response

{
  "agents": [
    {
      "agentId": "j81csCCat6",
      "name": "Daily Joke Emailer",
      "status": "DRAFT",
      "createdAt": "...",
      "editorUrl": "https://embeddable.co/app/your-org/agents/j81csCCat6"
    }
  ],
  "total": 17,
  "page": 1,
  "pages": 1,
  "limit": 20
}

GET /v1/agents/:agentId

Fetch a single agent.

{
  "agent": {
    "agentId": "j81csCCat6",
    "name": "Daily Joke Emailer",
    "description": null,
    "status": "DRAFT",
    "organizationId": "...",
    "editorUrl": "https://embeddable.co/app/your-org/agents/j81csCCat6"
  }
}

POST /v1/agents/:agentId/run

Trigger a one-off run of an agent.

Body

FieldTypeDescription
inputobjectOptional input payload passed to the agent function

Response

{
  "runId": "...",
  "status": "running"
}

The exact response shape depends on the agent — see your agent's functions/main.ts for the input/output contract.

Token cost: 1

DELETE /v1/agents/:agentId

Permanently delete an agent.

{ "success": true }

Token cost: 0.

On this page