# Embed widgets

> The API operations about embed widgets, each with its input, its output and an example.

The operations about embed widgets. Each one is a `POST` with a JSON object as its body: [Making a request](/docs/api#start) has the rules they share.

## Embed widgets

`POST /api/v1/embeds.get` · Read

The embed widgets of one site: two small cards the site owner can show on their own pages, Chart (visitors in the last hour, a trend line, the top three countries) and Realtime (people on the site right now). Answers the HTML snippet to paste for each card, the embed token inside them, the colour and theme written into the snippets, and when the token expires. embed is null while widgets are switched off. They are switched on, changed, given a new token and switched off in the dashboard under Settings, Sharing; no operation here does that. Call sites.list first for the siteId. This works while the workspace is locked, but the widgets themselves show a dash until the lock lifts.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string | required | The site id, from sites.list. |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `embed` | object \| null | always | The widgets of the site, or null while they are switched off. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/embeds.get \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'
```

**CLI**

```bash
clearsaga embeds get --input '{"siteId":"site_abc123def456"}'
```

**MCP**

```text
Tool: embeds_get
Arguments: {"siteId":"site_abc123def456"}
```

Run `clearsaga help embeds get` for one flag per field.