Documentation

Widgets API

Create, list, publish, and delete widgets via the Embeddable Developer API.

POST /v1/widgets

Create a new widget and start an AI build from a prompt. Returns immediately with a jobId you can poll.

Body

FieldTypeRequiredDescription
promptstringyesNatural-language description of the widget to build
namestringnoDisplay name (defaults to "API Widget")

Response — 202 Accepted

{
  "widgetId": "Wbk5MPTfzx",
  "jobId": "job_1776081418601_b5049f7fd47c",
  "status": "pending",
  "message": "Widget created. Poll GET /v1/jobs/:jobId for build status.",
  "editorUrl": "https://embeddable.co/app/your-org/editor/Wbk5MPTfzx",
  "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx"
}
FieldDescription
editorUrlDirect link to open the widget in your Embeddable workspace editor
previewUrlPublic live embed URL (only loads content after the widget is published)

Token cost: 1

Example

curl -X POST https://api.embeddable.co/v1/widgets \
  -H "Authorization: Bearer emb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing Card",
    "prompt": "Create a 3-tier pricing card with monthly/yearly toggle"
  }'

GET /v1/widgets

List widgets in your organization with pagination.

Query parameters

ParamTypeDefaultDescription
pagenumber1Page number
limitnumber20Items per page (max 100)
searchstring–Filter by name

Response

{
  "widgets": [
    {
      "widgetId": "Wbk5MPTfzx",
      "name": "Pricing Card",
      "isPublished": true,
      "createdAt": "2026-04-13T12:34:56Z",
      "editorUrl": "https://embeddable.co/app/your-org/editor/Wbk5MPTfzx",
      "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 3,
  "limit": 20
}

Each widget includes editorUrl (workspace editor link) and previewUrl (live public embed URL).

GET /v1/widgets/:widgetId

Fetch a single widget.

Response

{
  "widget": {
    "widgetId": "Wbk5MPTfzx",
    "name": "Pricing Card",
    "isPublished": true,
    "hasUnpublishedChanges": false,
    "organizationId": "...",
    "createdAt": "...",
    "editorUrl": "https://embeddable.co/app/your-org/editor/Wbk5MPTfzx",
    "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx"
  }
}

Returns 404 not_found if the widget doesn't exist or doesn't belong to your organization.

POST /v1/widgets/:widgetId/publish

Publish the latest build to the widget's public URL. After publishing, isPublished becomes true and hasUnpublishedChanges becomes false.

Response

{
  "success": true,
  "message": "Published successfully",
  "fileCount": 9
}

Make sure the build job for the widget has completed (GET /v1/jobs/:jobId returns status: "completed") before publishing.

DELETE /v1/widgets/:widgetId

Permanently delete a widget. This removes the widget record AND its compiled assets from S3.

Response

{ "success": true }

This action is irreversible and consumes 0 tokens.

On this page