> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Dashboard drafts

> Read Usertick dashboards through the REST API, and create and edit them as drafts from typed cards. A person reviews and publishes each draft in Usertick.

The dashboard endpoints read the boards in **Dashboards** and write their drafts. A board the API creates or edits stays a draft, and its viewers see nothing new until a person opens it in edit mode in Usertick and selects **Publish**. The API never publishes, discards, deletes, pins or shares a dashboard.

| Endpoint | Scopes | Does |
| - | - | - |
| [`GET /dashboards/capabilities`](https://docs.usertick.com/developers/api/reference/get-dashboard-capabilities) | `dashboards:draft` | Lists the card kinds, their fields and the plan's limits |
| [`GET /dashboards`](https://docs.usertick.com/developers/api/reference/list-dashboards) | `dashboards:read` | Lists the dashboards the credential may open |
| [`GET /dashboards/{dashboardId}`](https://docs.usertick.com/developers/api/reference/get-dashboard) | `dashboards:read` | Returns a dashboard as its viewers see it |
| [`GET /dashboards/{dashboardId}/draft`](https://docs.usertick.com/developers/api/reference/get-dashboard-draft) | `dashboards:read` | Returns a dashboard's draft |
| [`POST /dashboards`](https://docs.usertick.com/developers/api/reference/create-dashboard) | `dashboards:draft`, `dashboards:read` | Creates a dashboard as a draft |
| [`PATCH /dashboards/{dashboardId}/draft`](https://docs.usertick.com/developers/api/reference/edit-dashboard-draft) | `dashboards:draft`, `dashboards:read` | Changes a dashboard's draft |

An app or an AI assistant acts as the person who connected it, so, as in Usertick, reading requires the **View surveys and results** permission, and writing a draft requires **Manage dashboards and reports** and the right to edit that board. Every draft written through the API appears in the activity log as made through the credential and uses no AI credits.

## Who sees a new board

* A board an **API key** creates is shared with the organization and editable by everyone, so the key can read and change it later. Usertick names the key's creator as the board's creator.
* A board an **app or an AI assistant** creates is private to the person who connected it, as a new board in Usertick is. That person shares it from the dashboard.

An API key lists and reads the boards shared with the organization, and an app or an assistant also reads its person's private boards and the boards shared with them. A private board the credential can't open returns `404` with `PUB-015-001`.

## The typed card

The API reads and writes every card in one shape:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "w_k3v9q2ab",
  "kind": "big_number",
  "widgetType": "big-number",
  "title": "NPS",
  "surveyId": "11111111-1111-4111-8111-111111111111",
  "questionId": null,
  "metric": "nps",
  "dimension": null,
  "granularity": null,
  "derived": null,
  "target": null,
  "when": null,
  "text": null,
  "position": { "x": 0, "y": 0 },
  "size": { "w": 3, "h": 2 },
  "extraSettings": false,
  "aiGenerated": false,
  "surveyMissing": false
}
```

| Field | Meaning |
| - | - |
| `kind` | The card kind, such as `question`, `big_number`, `breakdown`, `responses_over_time`, `goal`, `threshold`, `themes` or `note`. `null` for a card only the dashboard makes, such as a countdown, which the API can remove but not change. |
| `title` | What the card is called, 1 to 120 characters. |
| `surveyId`, `questionId` | The survey the card reads and one of its questions, when the kind takes them. |
| `metric` | The measure of a number, goal, threshold or comparison card: `responses` (the default), `avg_score`, `nps`, `csat`, `ces`, `acceptance_rate` or `click_rate`. Every measure but `responses` needs a survey. |
| `dimension`, `granularity`, `derived`, `target`, `when`, `text` | The kind's own settings: what a breakdown splits by, a chart's time bucket, the rate a derived number shows, a goal's target or a threshold's line and side, and a note's text (up to 2,000 characters). |
| `position`, `size` | The card's place on the 12-column grid. Left out on a new card, the card goes below the lowest card, first fit, and takes its kind's default size. |
| `extraSettings` | `true` when the card holds settings the typed shape doesn't show, such as several questions on one chart or the card's own filters. An edit keeps them. |
| `surveyMissing` | `true` when the survey the card reads is gone. The card stays. |
| `aiGenerated` | `true` when Usertick AI drafted the card. The API never marks a card it writes. |

[`GET /dashboards/capabilities`](https://docs.usertick.com/developers/api/reference/get-dashboard-capabilities) lists every kind with the fields it takes, which are required, their values and defaults, what the kind needs of a survey, and its default and smallest size. A field the kind doesn't take returns `400` with `PUB-015-002`, and a kind the API doesn't build returns `PUB-015-006`. A survey or a question the credential can't read, or a question that isn't in the survey, returns `PUB-015-008`. Each error names its field, such as `cards[2].surveyId`.

## Create a dashboard

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://app.usertick.com/api/public/v1/dashboards \
  -H "Authorization: Bearer $USERTICK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f8c2c1e-onboarding-board" \
  -d '{
    "name": "Onboarding health",
    "cards": [
      { "kind": "big_number", "title": "NPS", "surveyId": "11111111-1111-4111-8111-111111111111", "metric": "nps" },
      { "kind": "responses_over_time", "title": "Responses", "surveyId": "11111111-1111-4111-8111-111111111111" }
    ]
  }'
```

The body takes `name` (1 to 255 characters), `description` (up to 1,000), the tile's `icon` and `color` keys (up to 40 each) and 0 to 500 `cards`. The call returns `201` with the draft, including its `draftVersion`, its cards and `editorUrl`, which opens the board in edit mode in Usertick. Give the person `editorUrl` so they can review and publish the board.

The plan's limits on dashboards (`403` with `PLN-001-005`) and cards per dashboard (`PLN-001-013`) apply as they do in the dashboard, and Usertick refuses a draft past the plan's cards rather than cutting it. A board's layout holds at most 128 KB, about 400 cards, and a request past that returns `400` with `DSH-002-004`.

## Edit a draft

`PATCH /dashboards/{dashboardId}/draft` applies 1 to 50 operations in order, saved together or not at all:

| Operation | Does |
| - | - |
| `add_card` `{ card }` | Adds a card |
| `update_card` `{ id, set }` | Changes the fields sent; every other setting of the card stays. `null` clears a field, and the kind can't change. |
| `remove_card` `{ id }` | Removes a card from the draft; viewers keep it until a person publishes |
| `set_board` `{ name, description, icon, color }` | Renames the board or changes its description or tile |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "expectedDraftVersion": 2,
  "operations": [
    { "op": "add_card", "card": { "kind": "themes", "title": "Top themes", "surveyId": "11111111-1111-4111-8111-111111111111" } },
    { "op": "update_card", "id": "w_k3v9q2ab", "set": { "title": "NPS this month" } },
    { "op": "set_board", "name": "Onboarding" }
  ]
}
```

* Send `expectedDraftVersion` from the last read. If the draft changed since then, the edit returns `409` with `PUB-015-004`, and you need to read the draft again and redo the edit.
* While the board is open in edit mode in Usertick, the edit returns `409` with `PUB-015-003`. Ask the person to leave edit mode, then send the edit again.
* A card ID that names no card returns `400` with `PUB-015-005`, and fewer than 1 or more than 50 operations return `PUB-015-007`.
* You can edit a published board too. Its viewers keep the published board, and the answer says `hasUnpublishedChanges: true` until a person publishes or discards the draft.
* A board shared with you as view only returns `403` with `DSH-006-003`, and a board a plan change made read-only returns `403` with `PLN-004-004`. A board already past the plan's cards per dashboard keeps saving as long as it doesn't grow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.