API authentication, limits and errors
Base URL, API key header, what each call costs, rate and concurrency limits, and every error code the Embeddable Developer API returns.
The Developer API lets your own code create, edit, publish and delete widgets and AI agents in one workspace. It is a REST API over HTTPS that takes and returns JSON. This page covers what every request has in common. For the endpoints, see the Widgets, Agents and Jobs references.
Base URL
https://api.embeddable.co/v1
Send request bodies as JSON with Content-Type: application/json.
Authentication
Every request needs an API key in the Authorization header, with the Bearer scheme:
curl https://api.embeddable.co/v1/widgets \
-H "Authorization: Bearer emb_live_..."
- Keys start with
emb_live_, followed by 43 random characters. - A key belongs to one workspace. It can't see or change anything in another workspace. Asking for another workspace's widget, agent or job returns
404 not_found. - A key has full access to its workspace: read, create, edit, publish and delete.
- A key acts as the person who created it. Widgets and agents it creates list that person as the author. If that person leaves the workspace, AI edits made with the key are refused with
403 key_owner_not_member. Create a new key.
To create, revoke or rotate keys, see Create and manage API keys. Keep keys on your server. Never put a key in browser or app code that visitors can read.
What each call costs
Calls that run the AI builder are counted as 1 token in the Usage tab on the API Keys page. Everything else is free.
| Call | Usage tab tokens |
|---|---|
POST /v1/widgets (create and build a widget) | 1 |
POST /v1/widgets/:widgetId/edit (one AI edit) | 1 |
POST /v1/agents (create an agent) | 1 |
POST /v1/agents/:agentId/run (run an agent) | 1 |
| Everything else: reads, lists, job polling, publish, delete, file reads, screenshots, restoring a version | 0 |
AI builds and edits also use one message from your workspace's plan, the same as a message typed in the editor. A free workspace also has a daily message limit. API keys never spend message packs you bought separately.
When a create call is repeated with the same idempotency key, the API returns the first job and doesn't count the call again. See Widgets API reference, under Idempotency.
Track your totals in the Usage tab. See Track API token usage.
Check usage from code
GET /v1/usage returns the workspace's message allowance. It is free.
{
"plan": "pro",
"unlimited": false,
"monthly": { "used": 41, "limit": 500, "remaining": 459, "period": "2026-11" },
"daily": null,
"purchasedCredits": 0,
"purchasedCreditsUsable": true,
"widgets": { "count": 12, "limit": null },
"costs": { "createWidget": 1, "editWidget": 1, "publish": 0, "read": 0 }
}
(Example values.) daily is only set on the free plan. monthly.limit and monthly.remaining are null when the workspace has no monthly cap, or when its limit can't be read at that moment. widgets.limit is 1 on the free plan and null on paid plans.
Limits
There is no general request rate limit. These limits apply:
| What | Limit | Error |
|---|---|---|
| AI jobs running at once in a workspace, checked when you start an edit | 1 on the free plan, 3 on paid plans | 429 too_many_jobs |
| AI edits or restores on one widget at a time | 1 | 409 widget_busy |
| Draft screenshots | 6 per widget per 10 minutes, 40 per workspace per hour | 429 rate_limited |
| Version restores | 10 per widget per hour, 30 per workspace per hour | 429 rate_limited |
prompt on create | No length limit | |
instruction on edit | 8,000 characters | 400 invalid_request |
Widget name | 120 characters | 400 invalid_request |
List page size (limit) | 100 (widgets and agents), 25 (versions) | |
| One file read | 90 KB of content per response | Response has truncated: true |
A 429 response includes retryAfterSeconds. Wait that long before trying again.
Errors
Errors return an HTTP status and a JSON body with a machine-readable error code and a message you can show or log:
{ "error": "invalid_request", "message": "\"prompt\" is required" }
Some errors add fields, such as activeJobId on 409 widget_busy or retryAfterSeconds on 429.
| HTTP | error | When |
|---|---|---|
| 400 | invalid_request | A required field is missing or a value is the wrong type, length or format. message names the field. |
| 401 | unauthorized | The Authorization header is missing or doesn't start with Bearer . |
| 401 | invalid_key | The key doesn't start with emb_live_, isn't recognised, or was revoked. |
| 402 | limit_reached | The workspace has used its monthly messages. Returned by the edit endpoint. |
| 402 | daily_limit_reached | A free workspace has used today's messages. Returned by the edit endpoint. |
| 403 | key_owner_not_member | The person who created the key is no longer in the workspace. |
| 403 | protected_path | You asked to read template code that isn't part of the widget's own files. |
| 404 | not_found | The widget, agent or job doesn't exist, or belongs to another workspace. |
| 404 | file_not_found, version_not_found, no_source | The file or version doesn't exist, or the widget has no code yet. |
| 409 | widget_busy | An AI job is already running on this widget. activeJobId names it. |
| 409 | draft_changed | The draft changed while a restore was running. Nothing was restored. |
| 422 | file_unreadable | The file is binary or larger than 512 KB. |
| 422 | build_failed, preview_unsupported, version_incomplete | See the Widgets API reference. |
| 429 | too_many_jobs, rate_limited | See Limits above. |
| 500 | server_error | Something went wrong on our side. message has the detail. |
| 503 | preview_unavailable, restore_failed | A dependent service is down. Try again in a minute. |
Agent runs that fail return error: "execution_failed". See the Agents API reference.
A create or edit call can succeed (202) and its job can still fail later. Job failures have their own codes. See the Jobs API reference.
Handling errors
- On
401, check the key. A key that worked before and now returnsinvalid_keywas most likely revoked. - On
409 widget_busy, poll the job inactiveJobIduntil it finishes, then retry. - On
429, waitretryAfterSeconds. - On
500after a create or edit, don't retry blindly. The build may already have started and used a message. Retry with the same idempotency key, or checkGET /v1/widgetsfirst.
Questions? Email us through the contact page.
Did this answer your question?
Your feedback helps us improve.
