# Hexad Survey widget

> Marczewski Hexad player-type survey — 24 questions that derive a player's primary type.

Source: https://docs.hatched.live/docs/reference/widgets/hexad-survey

## Mount

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

<div data-hatched-mount="hexad-survey"></div>
```

Submitting (or deleting) a response is a write, so mount the survey with a
**session token**. The buddy never passes its own IDs — the widget context
resolves the buddy, customer and audience from the token.

## Script attributes

| Attribute            | Values                 | Default                           |
| -------------------- | ---------------------- | --------------------------------- |
| `data-session-token` | widget session token   | submit 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 question metadata and the buddy's own response.
- Submitting a response requires a **session token** granted the
  `survey:submit` scope — `POST .../responses` is rejected `403` without it.
- `DELETE .../me` requires no write scope; it is always permitted (see
  **Availability**), so `survey:submit` applies only to submit.

## Plan & capability

- No plan capability gate — availability is controlled per workspace by the
  survey configuration (Audience → Survey settings) and the buddy's role.
- Minimum plan: **Free**.

## Availability

The survey is gated per workspace: the reads (`GET .../questions`,
`GET .../me`) and the write (`POST .../responses`) all require the survey to be
both enabled and widget-visible. When it isn't, those endpoints return
`403 hexad_survey_disabled`.

`DELETE /widget/hexad-survey/me` is the one exception — it is **always
permitted**, even when the survey is disabled, so a user can withdraw consent
and erase their raw response at any time.

## Endpoints

| Method   | Path                          | Purpose                                          |
| -------- | ----------------------------- | ------------------------------------------------ |
| `GET`    | `/widget/hexad-survey/questions` | 24 question keys + axis assignment + consent version |
| `POST`   | `/widget/hexad-survey/responses` | Submit/replace the response (UPSERT by buddy)    |
| `GET`    | `/widget/hexad-survey/me`        | The buddy's current response (or `null`)         |
| `DELETE` | `/widget/hexad-survey/me`        | Delete the raw response (GDPR / consent withdrawal) |

Verbatim Marczewski question text ships in the widget's tenant-installable copy
bundle, not from the API. Responses carry a `consent_version` and a
`retention_expires_at`.