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

# Groups

> Create or link the teams and groups your sessions are sent to.

A **group** is a team or a pickup group in the Hooper app. A session sent to a group shows up there for everyone in it. Your organization's groups are the ones you create, which are owned by your account's owner, and the ones you [link](#link-a-team-you-already-have).

Your organization also has its own private group (`default: true` on the group). Sessions sent without a `group` land there.

## Create a group and send it a game

```bash theme={null}
curl https://zeus.hooper.gg/v1/groups \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-varsity" \
  -d '{ "name": "Acme Varsity", "level": "high-school", "metadata": { "team_id": "lg-t-12" } }'
# → { "id": "grp_412", "object": "group", "name": "Acme Varsity", "type": "team", "privacy": "private", … }

curl https://zeus.hooper.gg/v1/sessions \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "source": { "type": "url", "url": "https://cdn.example.com/games/2026-08-26.mp4" }, "group": "grp_412" }'
```

* `type` is `team` (the default) or `pickup`. It can't be changed later.
* `privacy` decides who can find and join the group in the app. It defaults to `private` for a team and `public` for a pickup group.
* `metadata` holds your own ids, as on a session.
* An `Idempotency-Key` makes a retried create return the same group instead of a second one. See [Idempotency](https://developer.hooper.gg/sessions.md#idempotency).

## What you can do with a group

| Action | Allowed for | Otherwise |
| - | - | - |
| List, retrieve | Your organization's groups (`linked: true`), and the ones you can link (`linked: false`) | `404 resource_missing` |
| Send sessions | Your organization's groups | `400` on the session's `group` |
| Link | Teams and pickup groups your account's owner owns | `404 resource_missing` |
| Unlink | Your organization's groups, except its own group | `409 group_is_default` |
| Update, delete | Your organization's groups that your account's owner owns, except its own group | `403 group_not_owned`, `409 group_is_default` |

## Link a team you already have

A team or pickup group your account's owner already has in the Hooper app can be linked instead of created. `GET /v1/groups?linked=false` lists the ones you can link.

```bash theme={null}
curl -X POST https://zeus.hooper.gg/v1/groups/grp_377/link \
  -H "Authorization: Bearer $HOOPER_API_KEY"
# → { "id": "grp_377", "object": "group", "name": "Acme JV", "linked": true, … }
```

* Linking a group that is already linked changes nothing.
* `POST /v1/groups/{id}/unlink` stops new sessions to the group. Sessions already sent to it stay readable, and the group itself isn't changed.
* A group stays linked only while your account's owner owns it. If it's handed to someone else in the app, it's unlinked.
* If Hooper linked a group for you that your account's owner doesn't own, you can unlink it, but only Hooper support can link it again.

## Updating

`POST /v1/groups/{id}` changes only the fields you send. `null` clears a field (`name` can't be cleared). `metadata` is merged: each key you send is set, and a key set to `""` is removed.

```bash theme={null}
curl https://zeus.hooper.gg/v1/groups/grp_412 \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "privacy": "hidden", "metadata": { "season": "2026" } }'
```

## Deleting

`DELETE /v1/groups/{id}` removes the group from the Hooper app for everyone in it. To stop sending sessions to a group without deleting it, [unlink](#link-a-team-you-already-have) it instead.

* Sessions already sent to it stay readable through `/v1/sessions`. New sessions can't be sent to it.
* It can't be undone through the API.
* A group on a paid plan returns `409 group_has_subscription`; its owner deletes it in the Hooper app.


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