---
title: "Create (host) a group decision session"
method: POST
path: "/groups"
---

# Create (host) a group decision session

`POST /groups`

## Request

- Base URL: `https://localselections.com/api/v1`
- URL: `https://localselections.com/api/v1/groups`
- Auth: API key in header `X-API-Key`

Requires the `groups_host` scope, and requires the API key owner to have an active subscription — the identical gate the browser's group-hosting flow enforces (PROJECT_OVERVIEW.md section 3.2), re-checked at the database layer, not just here. A key can be scoped to host without also being able to join (`groups_join` is a separate scope) or vice versa. Costs 1 unit of the key's rate-limit budget per call.

## Request body

- object
  - `categoryMode` 'cuisine' | 'activity'
  - `mechanic` 'wheel' | 'dice' | 'rps' | 'coinflip' | 'carddraw' | 'magic8ball'
  - `displayName` string

## Response `200`

The created group session and its join code.

- object
  - `id` string, required
  - `joinCode` string, required
  - `categoryMode` string, required
  - `mechanic` string, required
  - `status` string, required

## Other responses

- `400`: The request body failed validation.
- `401`: Missing or invalid API key.
- `403`: Either the key lacks the "groups_host" scope, or its owner does not have an active subscription — the message field distinguishes the two (insufficient_scope vs. subscription_required).
- `429`: Rate limit exceeded for this API key. The budget is 30 units/60s for keys owned by an unsubscribed account, 120 units/60s for a subscribed account's keys (Stage 60) — shared across every endpoint, but each endpoint spends a different number of units per call rather than always 1 (Stage 104): search/groups_host/groups_join/places/movies cost 1, surprise_me/events cost 2, spin costs 3, bracket costs 4. Call GET /introspect to see a key's real remaining budget before it runs out.
- `502`: An upstream data source failed or returned nothing usable.

---

[API](https://skmtc.dev/localselections/apis/localselections-public-api.md) · [All operations](https://skmtc.dev/localselections/apis/localselections-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/localselections/apis/localselections-public-api/revisions/a24e9598add4?raw)