Events & phases

An event is the thing you schedule and share — a fireside, meeting, breakout session or speed-networking rotation. Its agenda is a list of phases, each with a modality:

Modality	What happens
broadcast	Hosts & speakers on a stage, streamed to a watch-only audience (HLS)
meeting	One room, everyone joins with camera & mic
breakout	Parallel small-group rooms, optional timer & extensions
rotation	Speed networking — attendees shuffle through timed rounds

Most events have a single phase; multi-phase agendas (e.g. broadcast → breakouts → broadcast) are fully supported.

Create an event

POST /v1/events

curl -X POST https://api.gathercloud.dev/v1/events \
  -H "x-api-key: gck_..." \
  -H "content-type: application/json" \
  -d '{
    "type": "fireside",
    "title": "Quarterly AMA",
    "scheduledAt": "2026-07-01T17:00:00Z",
    "visibility": "public",
    "allowAnonymousVoting": true,
    "metadata": { "description": "Ask the founders anything." },
    "phases": [
      { "modality": "broadcast", "featureSet": ["qa", "transcript"] }
    ]
  }'

Field	Type	Notes
type	string, required	Free-form label (fireside, meeting, …)
title	string, required
scheduledAt	ISO timestamp	Planned start
visibility	public | unlisted | private	Default unlisted
allowAnonymousVoting	boolean	Let signed-out viewers vote on Q&A (public events)
metadata	object	Your own data; the dashboard uses description and scheduledEndAt
phases	array	Each: modality (required), config, featureSet

Phase featureSet values: qa, chat, polls, reactions, transcript, capture. Phase config (per modality): roomSize, durationSeconds, extendable (breakout); rounds, roundSeconds (rotation).

Returns 201 with the event object.

Read & list

• GET /v1/events — newest first (up to 100).
• GET /v1/events/:id — includes the phases array.

Update

PATCH /v1/events/:id — any of title, scheduledAt (null clears it), visibility, allowAnonymousVoting, metadata (replaced wholesale).

Delete

DELETE /v1/events/:id — permanent; removes phases, Q&A and invites.

Lifecycle

Events move draft → scheduled → live → ended:

Call	Effect
POST /v1/events/:id/publish	draft → scheduled; fires event.published
POST /v1/events/:id/start	Goes live and activates the first phase
POST /v1/events/:id/advance	Ends the active phase, starts the next (ends the event after the last)
POST /v1/events/:id/end	Ends the event immediately

Phases

• POST /v1/events/:id/phases — append a phase (modality, config, featureSet).
• PATCH /v1/phases/:id — update config / featureSet.
• POST /v1/phases/:id/extend — add { "seconds": 300 } (10–3600) to the active phase's timer.

Users & roles

Attendee roles are per event: host, speaker, participant, viewer (plus workspace_admin). When you pre-provision users from your own directory:

• GET /v1/users / POST /v1/users — upsert by externalSub ({ externalSub, email, name, picture }).
• POST /v1/events/:id/memberships — { "userId": "…", "role": "speaker" }.

Events created from the dashboard automatically make their creator a host.

Q&A

GET /v1/events/:id/questions — questions with vote tallies, sorted by votes.