# Group Quest widget

> Cooperative team goal with a shared progress bar — join, contribute, and win together.

Source: https://docs.hatched.live/docs/reference/widgets/group-quest

## Mount

```html
<script src="https://cdn.hatched.live/widget.js" data-session-token="SESSION_TOKEN" defer></script>

<div data-hatched-mount="group-quest"></div>
```

Joining or leaving a quest is a write, so mount the Group Quest widget with a
**session token**. With an embed token the active quests render read-only and
the join button is disabled.

## Script attributes

| Attribute            | Values                 | Default                           |
| -------------------- | ---------------------- | --------------------------------- |
| `data-session-token` | widget session token   | join enabled                      |
| `data-embed-token`   | embed token            | read-only                         |
| `data-theme`         | `light` `dark`         | `light`                           |
| `data-api-base-url`  | API origin + `/api/v1` | `https://api.hatched.live/api/v1` |

## Required scopes

- `read` lists the active quests visible to the buddy.
- `quests:join` is required to join or leave — mount with a **session token**
  granted the `quests:join` scope. Embed tokens are read-only.

## Plan & capability

- Capability: `group_quest` (tenant toggle in Settings → Capabilities).
- Minimum plan: **Growth**.
- Two distinct 403s can come back:
  - `403 plan_feature_locked` — the plan does not entitle the capability.
    Details carry `required_plan` and an `upgrade_url`.
  - `403 capability_disabled` — the plan entitles it but an operator turned the
    Settings toggle off for this workspace.

## Endpoints

| Method | Path                            | Purpose                                            |
| ------ | ------------------------------- | -------------------------------------------------- |
| `GET`  | `/widget/group-quests/active`   | Active quests visible to the buddy (progress, deadline) |
| `POST` | `/widget/group-quests/:id/join` | Join a quest — idempotent (`already_joined` on re-join) |
| `POST` | `/widget/group-quests/:id/leave`| Leave a quest — prior contribution stays counted   |

> The public mount name is `group-quest`; the API routes are namespaced under
> `/widget/group-quests` (plural).