Developers

API Reference

Every endpoint embedio exposes: what authenticates it, what it accepts, and what it returns.

Authentication

Every dashboard-facing endpoint below (forms, bookings, webhooks, uploads, AI chat, and live chat management) is authenticated with your project's API key as a Bearer token. Find and regenerate your key on the API Keys page in your dashboard.

curl https://api.tryembedio.com/v1/forms \
  -H "Authorization: Bearer sk_live_..."

Endpoints reached through an opaque per-resource key in the URL — a form's submit key, a booking page's key, a chat widget's key, or a share-link token — are meant to be called directly from a visitor's browser and do not take an API key.

Rate Limits

Every public endpoint below (no API key — reached with a per-resource key or token) is rate-limited per IP address. A request over the limit gets a 429 response and standard RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset response headers. Bearer-authenticated dashboard endpoints (forms, submissions, webhooks, uploads, AI Chat and Live Chat management) aren't separately rate-limited — your plan's monthly submission and storage pool (see Forms & Submissions) is the real ceiling there.

Forms & Submissions

Submit a form (public, no API key)

The endpoint your embedded form or the SDK actually posts to. formKey is the opaque key shown on each form's implementation page.

curl -X POST https://api.tryembedio.com/v1/submit/frm_xxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "visitor@example.com", "message": "Hello!"}'

• _gotcha: honeypot field — leave it empty; a filled value is silently treated as spam and answered with a fake success
• _redirect: a URL on the same origin as the submitting page; external redirects are rejected for non-JSON submissions. Optional — what happens after a submission (a custom message, or a redirect of your choice) is normally set per-form on the dashboard's "After submission" panel, no field required. This overrides the dashboard setting for one embed only.
• file: a single file field, only accepted when the project has the Uploads module enabled

Manage forms (requires API key)

Share Links

A share link lets you hand a client or teammate read-only access to one form's submissions without giving them your API key.

Bookings

All three endpoints below are public — the booking page's key is the credential, and requests are rate-limited.

Webhooks

Webhook endpoints are managed with your API key (create, list, delete, view delivery logs, resend, and send a test event). embedio delivers submission.created to every enabled endpoint whenever a form on your project receives a real submission.

POST <your endpoint URL>
Content-Type: application/json
X-Embedio-Event: submission.created
X-Embedio-Delivery: 5f2b1c3a-...
X-Embedio-Signature: sha256=<hmac-sha256 of the raw body, hex-encoded>

{
  "event": "submission.created",
  "data": {
    "submissionId": "...",
    "formKey": "frm_xxxxxxxxxx",
    "formName": "Contact form",
    "formType": "form",
    "data": { "email": "visitor@example.com", "message": "Hello!" },
    "sourceUrl": "https://yoursite.com/contact",
    "flagged": false,
    "createdAt": "2026-01-01T12:00:00.000Z"
  },
  "deliveryId": "5f2b1c3a-...",
  "createdAt": "2026-01-01T12:00:00.000Z"
}

Verify a delivery by computing HMAC-SHA256 of the exact raw request body, keyed with the endpoint's secret (shown once on the Webhooks page, format whsec_...), and comparing it to the hex digest after sha256= in X-Embedio-Signature.

const crypto = require("crypto");

function isValidDelivery(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

Uploads

There's no separate upload endpoint — a file rides along with a normal form submission as a multipart file field (see Forms & Submissions above). Everything here is for managing files afterward, with your API key.

AI Chat Widget

Public endpoints scoped by your project's AI chat widget key (found on the AI Chat settings page), rate-limited. Messages are limited to 4,000 characters and each conversation stores at most 200 messages.

Live Chat Widget

Public endpoints scoped by your project's live chat widget key (found on the Live Chat settings page), rate-limited and polling-based. Messages are limited to 4,000 characters and each conversation stores at most 200 messages.