Embeddable

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.

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

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.

CallUsage 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 version0

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:

WhatLimitError
AI jobs running at once in a workspace, checked when you start an edit1 on the free plan, 3 on paid plans429 too_many_jobs
AI edits or restores on one widget at a time1409 widget_busy
Draft screenshots6 per widget per 10 minutes, 40 per workspace per hour429 rate_limited
Version restores10 per widget per hour, 30 per workspace per hour429 rate_limited
prompt on createNo length limit
instruction on edit8,000 characters400 invalid_request
Widget name120 characters400 invalid_request
List page size (limit)100 (widgets and agents), 25 (versions)
One file read90 KB of content per responseResponse 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.

HTTPerrorWhen
400invalid_requestA required field is missing or a value is the wrong type, length or format. message names the field.
401unauthorizedThe Authorization header is missing or doesn't start with Bearer .
401invalid_keyThe key doesn't start with emb_live_, isn't recognised, or was revoked.
402limit_reachedThe workspace has used its monthly messages. Returned by the edit endpoint.
402daily_limit_reachedA free workspace has used today's messages. Returned by the edit endpoint.
403key_owner_not_memberThe person who created the key is no longer in the workspace.
403protected_pathYou asked to read template code that isn't part of the widget's own files.
404not_foundThe widget, agent or job doesn't exist, or belongs to another workspace.
404file_not_found, version_not_found, no_sourceThe file or version doesn't exist, or the widget has no code yet.
409widget_busyAn AI job is already running on this widget. activeJobId names it.
409draft_changedThe draft changed while a restore was running. Nothing was restored.
422file_unreadableThe file is binary or larger than 512 KB.
422build_failed, preview_unsupported, version_incompleteSee the Widgets API reference.
429too_many_jobs, rate_limitedSee Limits above.
500server_errorSomething went wrong on our side. message has the detail.
503preview_unavailable, restore_failedA 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 returns invalid_key was most likely revoked.
  • On 409 widget_busy, poll the job in activeJobId until it finishes, then retry.
  • On 429, wait retryAfterSeconds.
  • On 500 after 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 check GET /v1/widgets first.

Questions? Email us through the contact page.

Did this answer your question?

Your feedback helps us improve.