---
title: embed.create
product: BOLD Embed
method: POST
path: /v1/embed/embeds
scope: embed:write
price: 10 credits ($0.01) per embed
price_cents: 1
price_credits: 10
billing: per_call
unit: embed
---

# embed.create

Create or update an embed

`POST https://boldstudios.io/api/v1/embed/embeds`

Creates an embeddable card and returns its token, the widget URL, the share-image URL and a paste-ready snippet. Idempotent on (kind, ref): calling it again for the same subject updates that embed rather than minting a second token, which matters because the first token is already pasted into somebody's website.

## Auth and billing

- `Authorization: Bearer bold_live_<prefix>_<secret>`, with the `embed:write` scope.
- Paid from: API balance.
- Price: 10 credits ($0.01) per embed. Charged only when the work succeeds.
- Send `Idempotency-Key` and a retry is not charged twice.

## Example

```bash
curl -X POST 'https://boldstudios.io/api/v1/embed/embeds' \
  -H 'Authorization: Bearer bold_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"scorecard","ref":"jane-doe","mode":"fetch","source_path":"data/scorecard/jane-doe","width":480,"allowed_domains":["janedoe.example.com"]}'
```

```json
{
  "ok": true,
  "token": "e_0f3a9c7d21b4482e9a5c6d8e1f204b73",
  "kind": "scorecard",
  "ref": "jane-doe",
  "embed_url": "https://boldstudios.io/embed/v/e_0f3a9c7d21b4482e9a5c6d8e1f204b73",
  "image_url": "https://boldstudios.io/embed/i/e_0f3a9c7d21b4482e9a5c6d8e1f204b73.png",
  "snippet": "<div data-bold-embed=\"e_0f3a9c7d21b4482e9a5c6d8e1f204b73\"></div>"
}
```

## Failures

Every error is `{ statusCode, name, message }`. Switch on `name`.

| Status | name | What to do |
| --- | --- | --- |
| 401 | `invalid_key`, `key_revoked`, `key_expired` | Mint a new key. |
| 402 | `insufficient_credits` | Top up. The body carries `balance_cents` and `price_cents`. |
| 403 | `scope_denied` | The body names the missing scope in `required_scope`. |
| 422 | `validation_error` | Fix the request. Nothing was charged. |
| 429 | `rate_limited` | Wait `Retry-After` seconds. |

Those five are the common ones. All 20: https://boldstudios.io/api/v1/docs/errors.md .

Full catalog: https://boldstudios.io/api/v1 . Everything in one fetch: https://boldstudios.io/api/v1/llms-full.txt . Human docs: https://boldstudios.io/developers .