Widgets API reference
Every /v1/widgets endpoint: create, list, get, edit, publish, embed code, previews, source files, versions and delete, with parameters and responses.
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 path | What it does | Usage tab tokens |
|---|---|---|
POST /widgets | Create a widget and build it from a prompt | 1 |
GET /widgets | List widgets | 0 |
GET /widgets/:widgetId | Get one widget | 0 |
POST /widgets/:widgetId/edit | One AI edit, saved as a draft | 1 |
POST /widgets/:widgetId/publish | Publish the draft | 0 |
GET /widgets/:widgetId/embed-code | Get the embed code | 0 |
GET /widgets/:widgetId/preview | Live preview link and screenshot | 0 |
GET /widgets/:widgetId/preview/draft | Screenshot of the draft | 0 |
GET /widgets/:widgetId/files | List the widget's source files | 0 |
GET /widgets/:widgetId/files/content | Read one source file | 0 |
GET /widgets/:widgetId/versions | List saved versions | 0 |
POST /widgets/:widgetId/versions/:versionId/restore | Restore a version as the draft | 0 |
DELETE /widgets/:widgetId | Delete a widget | 0 |
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
POST /widgetscreates the widget and starts a build. You get ajobIdback right away.- Poll
GET /jobs/:jobIduntilstatusiscompletedorfailed. A first build is published automatically before the job completes, so the embed code works as soon as the job is done. POST /widgets/:widgetId/editmakes a change. Edits are drafts: your live widget doesn't change.POST /widgets/:widgetId/publishputs 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.
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | What to build, in plain language. |
name | string | no | Display name, up to 120 characters. Defaults to API Widget. |
type | string | no | landing-page to build a landing page. Anything else builds a widget. |
idempotencyKey | string | no | See 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"
}
| Field | Description |
|---|---|
widgetId | The new widget's ID. Use it in every other widget endpoint. |
jobId | The build job. Poll it with GET /jobs/:jobId. |
editorUrl | Opens the widget in the editor, for anyone signed in to the workspace. |
previewUrl | The 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 parameter | Default | Description |
|---|---|---|
page | 1 | Page number, starting at 1. |
limit | 20 | Widgets per page, from 1 to 100. |
search | Only 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:
| Field | Description |
|---|---|
embedCode | The code to paste into a website. |
activeJobId | Set 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.
| Field | Type | Required | Description |
|---|---|---|---|
instruction | string | yes | The change you want, up to 8,000 characters. prompt is accepted as another name for it. |
imageUrls | string[] | no | Up to 10 https links to images or files the builder should look at. |
idempotencyKey | string | no | Same 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:
| Status | error | Why |
|---|---|---|
| 402 | limit_reached / daily_limit_reached | The workspace is out of messages. |
| 403 | key_owner_not_member | The key's creator has left the workspace. |
| 409 | widget_busy | Another edit or restore is running on this widget. |
| 429 | too_many_jobs | The 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 parameter | Default | Description |
|---|---|---|
viewport | desktop | desktop (1280 px wide), mobile (390 px) or both. |
fullPage | false | true 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 parameter | Default | Description |
|---|---|---|
path | required | The file path from the list, such as /App.tsx. |
startLine | 1 | First line to return. |
endLine | last line | Last line to return. |
lineNumbers | true | false 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.
