Create widgets and agents with the API
A short walkthrough of the Developer API: get a key, create a widget from a prompt, poll the build, edit, publish and manage it.
The Developer API lets you create, edit, publish and delete widgets and AI agents in your workspace from your own code. This article walks through the widget flow. For every endpoint, parameter and response, use the reference articles.
Where the API reference lives
- API authentication, limits and errors: base URL, keys, costs, limits and every error code.
- Widgets API reference: create, list, get, edit, publish, embed code, previews, source files, versions and delete.
- Agents API reference: create, list, run and delete agents.
- Jobs API reference: following background builds.
To reach this article from your workspace, open Settings, go to the For developers tab, and click API Documentation.

Before you make any calls, you need an API key:
- Open Settings and select the For developers tab.
- Click New API Key and give the key a name.
- Copy the full key right away. You won't see it again.
Keys start with emb_live_ and belong to one workspace. Send the key on every request:
Authorization: Bearer emb_live_...
The base URL is https://api.embeddable.co/v1.
Create and build
To create a widget, send a POST to /v1/widgets with a natural-language prompt. The name field is optional and defaults to "API Widget".
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","idempotencyKey":"pricing-card-001"}'
The response is 202 Accepted and includes a widgetId, a jobId, a status of pending, an editorUrl that opens the widget in your workspace editor, and a previewUrl.
The idempotencyKey is optional. If your call times out and you send it again with the same key within 10 minutes, you get the first job back instead of a second build.
Builds run in the background
Creating a widget starts a background AI build and returns immediately. To find out when the build is done, poll the job. Add ?wait=50 to hold the request open for up to 50 seconds until the job finishes:
curl "https://api.embeddable.co/v1/jobs/job_...?wait=50" \
-H "Authorization: Bearer emb_live_..."
When the build finishes, the response shows status: "completed". A new widget is published automatically before its job completes, so its embed code works straight away. The result contains the buildId, widgetId, publishedFiles, published: true and assistantReply (the builder's reply). If the job fails, errorCode says why.
Edit and publish
Edit. Send one change as an instruction, the way you'd type it in the editor chat:
curl -X POST https://api.embeddable.co/v1/widgets/WIDGET_ID/edit \
-H "Authorization: Bearer emb_live_..." \
-H "Content-Type: application/json" \
-d '{"instruction":"Make the yearly toggle the default"}'
This also returns a jobId to poll. Edits are saved as a draft and don't change your live widget.
Publish. When the edit job reports completed, publish the draft:
curl -X POST https://api.embeddable.co/v1/widgets/WIDGET_ID/publish \
-H "Authorization: Bearer emb_live_..."
A successful response has success: true, message, fileCount, publishedAt, embedCode, editorUrl and previewUrl. After publishing, isPublished becomes true and hasUnpublishedChanges becomes false. The previewUrl only shows the widget once it has been published.
Manage widgets
List. GET /v1/widgets returns the widgets in your workspace. It accepts page (default 1), limit (default 20, max 100), and search to filter by name.
Fetch one. GET /v1/widgets/WIDGET_ID returns a single widget, including hasUnpublishedChanges and its embedCode. It returns a 404 not_found error if the widget doesn't exist or belongs to another workspace.
Delete. DELETE /v1/widgets/WIDGET_ID permanently removes the widget and its files. This can't be undone.
You can also get the embed code, take a screenshot of the draft, read the widget's source files, and restore earlier versions. See the Widgets API reference.
Agents
POST /v1/agents creates an AI agent. Unlike widgets, name is required and prompt is optional. With a prompt, it starts a build and returns a jobId to poll. Without one, it only creates the agent. POST /v1/agents/AGENT_ID/run runs an agent once. See the Agents API reference.
What it costs
These calls each count as 1 token in the Usage tab on the API Keys page:
- Creating a widget (
POST /v1/widgets) - Editing a widget (
POST /v1/widgets/:id/edit) - Creating an agent (
POST /v1/agents) - Running an agent (
POST /v1/agents/:id/run)
Reading, listing, polling, publishing and deleting are free. Widget builds and edits also use one message from your workspace's plan, the same as a message in the editor. API keys never spend message packs you bought separately. See Track API token usage.
Errors
Errors come back as JSON with an error code and a message. The common codes are:
| HTTP | error |
|---|---|
| 400 | invalid_request |
| 401 | unauthorized, invalid_key |
| 402 | limit_reached, daily_limit_reached (out of messages) |
| 403 | key_owner_not_member (the key's creator left the workspace) |
| 404 | not_found |
| 409 | widget_busy (another AI edit is running on the widget) |
| 422 | build_failed, preview_unsupported, version_incomplete, file_unreadable |
| 429 | too_many_jobs, rate_limited (wait retryAfterSeconds) |
| 500 | server_error |
| 503 | preview_unavailable, restore_failed |
For what each one means, see API authentication, limits and errors.
Did this answer your question?
Your feedback helps us improve.
