Developer API Overview

The Embeddable Developer API lets you create, list, publish, and delete widgets and AI agents from your own code. It uses standard REST conventions over HTTPS, returns JSON, and authenticates with Bearer API keys.

Base URL

https://api.embeddable.co/v1

Authentication

Every request must include an Authorization: Bearer <api_key> header. API keys start with emb_live_.

curl https://api.embeddable.co/v1/widgets \
  -H "Authorization: Bearer emb_live_..."

Creating an API key

1. Sign in to your Embeddable workspace.
2. Open Settings → API Keys for your organization.
3. Click New API Key, give it a name, and copy the full key shown — you will not see it again.
4. Treat the key like a password. If it leaks, revoke it from the same page.

API keys are scoped to one organization. A key from organization A cannot read or modify resources in organization B.

Token usage

Some endpoints consume API tokens from your organization plan:

Usage is recorded per request and visible in the Usage tab on the API Keys page.

Async builds

Creating a widget or agent kicks off a background AI build. The endpoint returns immediately with a jobId you can poll:

POST /v1/widgets   →  { widgetId, jobId, status: "pending" }
GET  /v1/jobs/:id  →  { status: "completed", result: { buildId, widgetId } }

See Jobs for the full polling pattern.

Quickstart

# 1. Create a widget from a prompt
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 basic pricing card with title and CTA"}'
# → { "widgetId": "abc123", "jobId": "job_...", "status": "pending" }

# 2. Poll until the build finishes
curl https://api.embeddable.co/v1/jobs/job_... \
  -H "Authorization: Bearer emb_live_..."
# → { "status": "completed", "result": { "buildId": "...", "widgetId": "abc123" } }

# 3. Publish it
curl -X POST https://api.embeddable.co/v1/widgets/abc123/publish \
  -H "Authorization: Bearer emb_live_..."
# → { "success": true, "fileCount": 9 }

Errors

All errors return JSON in the form { "error": "<code>", "message": "<human readable>" }.