GatherCloud Docs

Appearance

Getting started ​

Welcome to GatherCloud. This guide takes you from zero to your first live event over the API — create it, publish it, and take it live.

What you'll need ​

  • A GatherCloud account with a workspace. Events, recordings and API keys all belong to a workspace.
  • An API key. In the dashboard, go to API Keys → Create key (workspace owners and admins). The full key (gck_…) is shown once at creation — copy it into your secrets manager. Keep it server-side; never ship it in browser or mobile code. See Authentication for details.
  • A tool to make HTTP requests — curl, your language's HTTP client, or the interactive API reference, which lets you try every endpoint in the browser.

Make your first call ​

Every request goes to https://api.gathercloud.dev, is versioned under /v1, and authenticates with your key in the x-api-key header. List your events to confirm the key works (a brand-new workspace returns an empty list):

sh
curl https://api.gathercloud.dev/v1/events \
  -H "x-api-key: gck_..."

A 401 means the key is missing or wrong — double-check the header. See Errors for the full shape of error responses.

Create an event ​

An event is the thing you schedule and share; its agenda is a list of phases, each with a modality (broadcast, meeting, breakout, rotation). Here's a single-phase fireside with Q&A and a transcript:

sh
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",
    "phases": [
      { "modality": "broadcast", "featureSet": ["qa", "transcript"] }
    ]
  }'

This returns 201 with the new event in draft status. Note the id in the response — you'll use it for every call below.

The create response is the bare event and does not echo back the phases you sent. They were created all the same; fetch them any time with GET /v1/events/{id}. See Events & phases for why.

Publish and go live ​

A draft event isn't on any public surface yet. Two short steps take it live:

sh
# draft → scheduled (the dashboard shows this as "Published")
curl -X POST https://api.gathercloud.dev/v1/events/{id}/publish \
  -H "x-api-key: gck_..."

# scheduled → live (activates the first phase)
curl -X POST https://api.gathercloud.dev/v1/events/{id}/start \
  -H "x-api-key: gck_..."

Publishing fires the event.published webhook; starting fires event.started. There's no time-based auto-start — go-live is an explicit call (or a click in the Stage UI). The full lifecycle — draft → scheduled → live → ended, plus advancing through phases — is covered in Events & phases.

Get notified with webhooks ​

Rather than polling, register a webhook to receive signed notifications when things happen — an event goes live, a participant joins, a recording finishes:

sh
curl -X POST https://api.gathercloud.dev/v1/webhooks \
  -H "x-api-key: gck_..." \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/hooks/gathercloud",
    "eventTypes": ["event.started", "recording.ready"]
  }'

See Webhooks for the event catalogue, payload shapes, and signature verification.

Next steps ​