Embeddable

Widgets API reference

Every /v1/widgets endpoint: create, list, get, edit, publish, embed code, previews, source files, versions and delete, with parameters and responses.

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

These endpoints create and manage widgets and landing pages 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, limits and error codes, see API authentication, limits and errors.

Summary

Method and pathWhat it doesUsage tab tokens
POST /widgetsCreate a widget and build it from a prompt1
GET /widgetsList widgets0
GET /widgets/:widgetIdGet one widget0
POST /widgets/:widgetId/editOne AI edit, saved as a draft1
POST /widgets/:widgetId/publishPublish the draft0
GET /widgets/:widgetId/embed-codeGet the embed code0
GET /widgets/:widgetId/previewLive preview link and screenshot0
GET /widgets/:widgetId/preview/draftScreenshot of the draft0
GET /widgets/:widgetId/filesList the widget's source files0
GET /widgets/:widgetId/files/contentRead one source file0
GET /widgets/:widgetId/versionsList saved versions0
POST /widgets/:widgetId/versions/:versionId/restoreRestore a version as the draft0
DELETE /widgets/:widgetIdDelete a widget0

A widget that doesn't exist, or belongs to another workspace, returns 404 not_found on every endpoint.

How a widget moves through the API

  1. POST /widgets creates the widget and starts a build. You get a jobId back right away.
  2. Poll GET /jobs/:jobId until status is completed or failed. A first build is published automatically before the job completes, so the embed code works as soon as the job is done.
  3. POST /widgets/:widgetId/edit makes a change. Edits are drafts: your live widget doesn't change.
  4. POST /widgets/:widgetId/publish puts the draft live.

Create a widget

POST /widgets

Creates a widget and starts an AI build from your prompt. The builder doesn't stop to ask questions on this path. It makes reasonable assumptions instead.

FieldTypeRequiredDescription
promptstringyesWhat to build, in plain language.
namestringnoDisplay name, up to 120 characters. Defaults to API Widget.
typestringnolanding-page to build a landing page. Anything else builds a widget.
idempotencyKeystringnoSee Idempotency below. Can also be sent as an Idempotency-Key header.
curl -X POST https://api.embeddable.co/v1/widgets \
  -H "Authorization: Bearer emb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing card",
    "prompt": "A 3-tier pricing card with a monthly/yearly toggle",
    "idempotencyKey": "pricing-card-2026-11-22"
  }'

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-workspace/editor/Wbk5MPTfzx",
  "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx"
}
FieldDescription
widgetIdThe new widget's ID. Use it in every other widget endpoint.
jobIdThe build job. Poll it with GET /jobs/:jobId.
editorUrlOpens the widget in the editor, for anyone signed in to the workspace.
previewUrlThe public preview page. It shows the widget once it's published.

The widget record is created before the build runs, so it appears in GET /widgets even if the build later fails. Create calls aren't checked against your message allowance up front: if the workspace is out of messages, you still get 202, and the job then fails with limit_reached or daily_limit_reached.

Idempotency

Send an idempotencyKey (8 to 100 characters: letters, digits and _ . : -) when you might retry a call, for example after a network timeout. If the same key is sent again within 10 minutes, the API doesn't start a second build. It returns the first job with status 200 and "deduplicated": true, and the repeat isn't counted in the Usage tab.

A retry with the same key does start a new build if the first job failed before it used a message (limit_reached, daily_limit_reached, widget_busy or ai_failed).

Without a key, every create call starts a new build, even with the same prompt.

List widgets

GET /widgets

Query parameterDefaultDescription
page1Page number, starting at 1.
limit20Widgets per page, from 1 to 100.
searchOnly widgets whose name contains this text (not case-sensitive). Only the first 100 characters are used.

Widgets come back newest-updated first.

{
  "widgets": [
    {
      "widgetId": "Wbk5MPTfzx",
      "name": "Pricing card",
      "type": "widget",
      "isPublished": true,
      "hasUnpublishedChanges": false,
      "status": "ACTIVE",
      "createdAt": "2026-11-22T10:12:03.000Z",
      "updatedAt": "2026-11-22T10:14:41.000Z",
      "editorUrl": "https://embeddable.co/app/your-workspace/editor/Wbk5MPTfzx",
      "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 3,
  "limit": 20
}

Each widget also includes its stored fields, such as id, organizationId, userId (the author), templateName, previewImage and meta. type is widget or landing-page, and can be null on older widgets. status is ACTIVE, ARCHIVED or SUSPENDED.

Get a widget

GET /widgets/:widgetId

Returns the same widget fields as the list inside a widget object, plus:

FieldDescription
embedCodeThe code to paste into a website.
activeJobIdSet while an AI edit or restore is running on the widget.

Edit a widget

POST /widgets/:widgetId/edit

Runs one AI builder turn on the widget, as if you'd typed the instruction in the editor chat. The result is a draft. Nothing goes live until you publish.

FieldTypeRequiredDescription
instructionstringyesThe change you want, up to 8,000 characters. prompt is accepted as another name for it.
imageUrlsstring[]noUp to 10 https links to images or files the builder should look at.
idempotencyKeystringnoSame rules as on create, scoped to this widget.
curl -X POST https://api.embeddable.co/v1/widgets/Wbk5MPTfzx/edit \
  -H "Authorization: Bearer emb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Make the yearly toggle the default and add a 20% badge"}'

Response: 202 Accepted with widgetId, jobId, status: "pending", editorUrl and previewUrl. Poll the job for the result.

Before it starts, the edit is refused with:

StatuserrorWhy
402limit_reached / daily_limit_reachedThe workspace is out of messages.
403key_owner_not_memberThe key's creator has left the workspace.
409widget_busyAnother edit or restore is running on this widget.
429too_many_jobsThe workspace already has its maximum number of AI jobs running (1 free, 3 paid).

The edit is added to the widget's latest chat in the editor, so you can continue it there.

Publish a widget

POST /widgets/:widgetId/publish

Puts the current draft live. The embed code doesn't change, so sites that already have it show the new version.

{
  "success": true,
  "message": "Published successfully",
  "fileCount": 9,
  "publishedAt": "2026-11-22T10:20:00.000Z",
  "embedCode": "<script src=\"https://widgets.embeddable.co/sdk/latest/embeddable.js\" defer></script>\n<div class=\"embeddable-Wbk5MPTfzx\"></div>",
  "editorUrl": "https://embeddable.co/app/your-workspace/editor/Wbk5MPTfzx",
  "previewUrl": "https://embeddable.live/embed/Wbk5MPTfzx"
}

After this, the widget's isPublished is true and hasUnpublishedChanges is false.

Returns 409 widget_busy while an AI edit is running. Publish after its job finishes. If the widget has never compiled, the call fails with 500 server_error.

Get the embed code

GET /widgets/:widgetId/embed-code

{
  "widgetId": "Wbk5MPTfzx",
  "isPublished": true,
  "hasUnpublishedChanges": false,
  "snippet": "<script src=\"https://widgets.embeddable.co/sdk/latest/embeddable.js\" defer></script>\n<div class=\"embeddable-Wbk5MPTfzx\"></div>"
}

The snippet shows the published version, so publish first. For where to paste it, see Embed a widget on your website.

Get the live preview

GET /widgets/:widgetId/preview

Returns widgetId, isPublished, hasUnpublishedChanges, previewUrl, editorUrl, updatedAt and, once the widget is published, screenshotUrl: an image of the published version.

Take a screenshot of the draft

GET /widgets/:widgetId/preview/draft

Renders the current draft, including unpublished edits, and returns it as images. It can take up to a minute.

Query parameterDefaultDescription
viewportdesktopdesktop (1280 px wide), mobile (390 px) or both.
fullPagefalsetrue captures up to 3 screen-heights instead of 1.
{
  "widgetId": "Wbk5MPTfzx",
  "source": "draft",
  "isPublished": true,
  "hasUnpublishedChanges": true,
  "images": [
    { "viewport": "desktop", "width": 1280, "height": 800, "y": 0, "mediaType": "image/png", "data": "iVBORw0KGgo..." }
  ],
  "truncated": false,
  "empty": false,
  "findings": "...",
  "editorUrl": "https://embeddable.co/app/your-workspace/editor/Wbk5MPTfzx",
  "livePreviewUrl": "https://embeddable.live/embed/Wbk5MPTfzx",
  "capturedAt": "2026-11-22T10:21:00.000Z",
  "durationMs": 14210
}

data is base64, and mediaType is image/png or image/jpeg. empty: true means the widget rendered nothing visible. findings is a short text description of what rendered.

Limits: 6 per widget per 10 minutes and 40 per workspace per hour (429 rate_limited). Other errors: 409 widget_busy while an edit runs, 404 no_source if the widget has no code yet, 422 build_failed if the draft doesn't compile (with up to 5 errors), 422 preview_unsupported for some older widgets, and 503 preview_unavailable.

Read the source files

GET /widgets/:widgetId/files lists the widget's own source files in the draft, with path, size (bytes) and lines for each, plus totalFiles and totalLines. Template code is left out.

GET /widgets/:widgetId/files/content reads one file.

Query parameterDefaultDescription
pathrequiredThe file path from the list, such as /App.tsx.
startLine1First line to return.
endLinelast lineLast line to return.
lineNumberstruefalse returns the lines without number prefixes.

The response has content, totalLines, startLine, endLine and truncated. One response holds up to 90 KB. When truncated is true, note tells you which startLine to ask for next.

Errors: 400 invalid_request for a bad path or line range, 403 protected_path for template code, 404 file_not_found, and 422 file_unreadable for binary files or files over 512 KB.

List and restore versions

Every AI edit that changes code saves a version, as in the editor.

GET /widgets/:widgetId/versions?limit=10 lists the newest versions first. limit is 1 to 25 and defaults to 10. Each version has versionId, createdAt, kind (ai_turn, manual_edit, restore_backup or unknown), an optional label (the instruction that made it), fileCount, matchesDraft and restorable.

POST /widgets/:widgetId/versions/:versionId/restore puts that version back as the draft. It doesn't publish. Before it restores, it saves the current draft as a new version and returns its ID as backupVersionId, so you can undo the restore. The response also lists filesWritten and filesDeleted. If the version already matches the draft, nothing changes and the response has "unchanged": true.

Limits: 10 restores per widget and 30 per workspace per hour (429 rate_limited). Other errors: 404 version_not_found, 409 widget_busy, 409 draft_changed (someone saved in the editor during the restore), 422 version_incomplete (that version isn't a full copy of the widget), and 503 restore_failed.

Delete a widget

DELETE /widgets/:widgetId

Deletes the widget and its files. This can't be undone.

{ "success": true }

Questions? Email us through the contact page.

Did this answer your question?

Your feedback helps us improve.