# ZingKast Agent Guide v2 — 2026-07-08

ZingKast is a webinar platform: instant, scheduled, and 24/7-replay
webinars, with hosted watch pages, live chat, recordings, and analytics.
This guide is for AI agents integrating with ZingKast on a user's behalf.

## QUICKSTART — create a webinar with ONE request, no signup

POST /api/v1/webinars with NO auth and an "agentName" field creates a
working, embeddable webinar owned by an unclaimed account that expires
in 7 days unless your user claims it (see CLAIMING below):

  curl -X POST https://zingkast.com/api/v1/webinars \
    -H "content-type: application/json" \
    -d '{
      "agentName": "MyAgent",
      "mode": "scheduled",
      "title": "Intro to Widgets",
      "scheduledStart": "2026-08-01T17:00:00.000Z"
    }'

Body fields: agentName (required for anonymous creation, 1-80 chars),
mode ("live_now" | "scheduled" | "replay"), title (1-200 chars),
description (optional). "scheduled" needs a future scheduledStart OR
scheduleRules (recurring); "replay" needs sourceVideoId + scheduleRules;
"live_now" starts a session immediately. Optional funnel fields:
themeMode, brandBg, thankYouUrl, exitUrl, metaPixelId, tiktokPixelId,
gaMeasurementId.

scheduleRules: {"frequency": "justInTime" | "hourly" | "daily" |
"weekly", "timezone": IANA string, "times": ["HH:mm", …] (daily/weekly),
"days": [0-6, …] (weekly)}. "justInTime" (replay only) is evergreen:
no pre-scheduled sessions — a live session is minted the moment a
viewer registers, so the webinar is joinable around the clock.

201 response shape (exact):

  {
    "webinarId": string,
    "hostedUrl": "https://zingkast.com/w/WEBINAR_ID",
    "embedSnippet": "<script src=\"https://zingkast.com/embed.js\" data-webinar=\"WEBINAR_ID\"><\/script>",
    "claimToken": string,      // manage THIS webinar for 7 days — keep it
    "deviceAuth": {
      "user_code": string,           // 8 chars, show to your user
      "device_code": string,         // secret, poll with this
      "verification_url": "https://zingkast.com/auth/USER_CODE",
      "poll_url": "https://zingkast.com/api/v1/auth/device/poll",
      "expires_in": 900,             // seconds (15 minutes)
      "interval": 5                  // poll every N seconds
    },
    "expiresAt": string        // ISO date the unclaimed webinar is purged
  }

PERSIST claimToken and deviceAuth immediately (e.g. to
~/.zingkast/credentials) — the claimToken is shown exactly once, and
losing it means losing management access to the webinar.

## CLAIMING — one click converts it to a permanent account + API key

The webinar above is fully functional now, but purges after 7 days
unless claimed. To claim (RFC 8628 device authorization):

1. Show your user the verification_url ("Open https://zingkast.com/auth/USER_CODE
   and click Allow"). They sign in (or sign up) and click Allow.
2. Poll poll_url every "interval" seconds:

     curl -X POST https://zingkast.com/api/v1/auth/device/poll \
       -H "content-type: application/json" \
       -d '{"device_code": "DEVICE_CODE"}'

   Responses: {"status":"pending"} — keep polling.
   {"status":"expired"} — the 15-minute window lapsed; restart with
   POST /api/v1/auth/device/start, body {"claimToken": "..."} (returns
   a fresh deviceAuth payload, same shape as above).
   {"status":"denied"} — the user declined; stop.
   {"status":"approved","apiKey":"zk_live_…"} — SUCCESS. The apiKey is
   returned on this ONE response only and can never be retrieved again.
   Later polls return {"status":"approved"} without the key.
3. Persist the apiKey to ~/.zingkast/credentials (chmod 600). The
   webinar now belongs to the user's permanent account and no longer
   expires.

## MANAGEMENT API AUTH

Three credentials work:

- API key: "Authorization: Bearer zk_live_…" — account-wide access to
  GET/POST /api/v1/webinars and GET/PATCH/DELETE /api/v1/webinars/{id}.
- Claim token: "Authorization: Bearer CLAIM_TOKEN" — scoped to the ONE
  webinar it was issued for (GET/PATCH/DELETE /api/v1/webinars/{id});
  expires with the unclaimed webinar (7 days).
- Clerk browser session — what the dashboard uses.

PATCH /api/v1/webinars/{id} accepts: title, description, and the funnel
fields listed above.

## EMBED

One line embeds a live or upcoming webinar in any page:

  <script src="https://zingkast.com/embed.js" data-webinar="WEBINAR_ID"></script>

Optional data-height sets a fixed iframe height (default: responsive
16/10 aspect-ratio box). The script replaces itself with a wrapper div
and iframe pointed at https://zingkast.com/w/WEBINAR_ID.

### EMBED EVENTS

The embedded page posts lifecycle events to the host page. embed.js listens
for these and re-dispatches them as DOM CustomEvents on window, so the host
page can just addEventListener — no postMessage wiring required:

  window.addEventListener("zingkast:registered", function (e) {
    console.log(e.detail.webinarId);
  });
  window.addEventListener("zingkast:joined", function (e) { /* ... */ });
  window.addEventListener("zingkast:ended", function (e) { /* ... */ });

Events fired: "registered" (on successful registration), "joined" (on mount
of the live or replay watch state), "ended" (when the session's ended state
renders, i.e. completed or cancelled). Each CustomEvent's detail is
{ source: "zingkast", event: string, webinarId: string }.

## PUBLIC API (no auth)

### GET /api/v1/webinars/{id}/public

Returns the webinar's public info, its next upcoming/live session, and
resolved brand (logo, accent color, theme). Response shape:

  {
    "webinar": {
      "id": string, "title": string, "description": string | null,
      "logoUrl": string | null, "accentColor": string | null,
      "mode": "live_now" | "scheduled" | "replay",  // "live_now" is labeled "Instant" in the UI
      "registrationFields": unknown, "thankYouUrl": string | null, "exitUrl": string | null,
      "metaPixelId": string | null, "tiktokPixelId": string | null,
      "gaMeasurementId": string | null
    },
    "nextSession": { "id": string, "scheduledStart": string, "status": string } | null,
    "brand": { ... resolved brand fields ... }
  }

404 if the webinar does not exist.

### POST /api/v1/sessions/{id}/register

Registers an attendee for a session. Body (JSON):

  {
    "email": string,      // required, valid email, max 320 chars
    "name": string,        // required, 1-200 chars
    "timezone": string,    // required, IANA timezone name, max 64 chars
    "customFields": { [key: string]: string }, // optional, up to 20 entries
    "utm": { ... }          // optional UTM params
  }

Returns 201 (new registration) or 200 (idempotent re-registration for
the same email) with:

  { "registrationId": string, "registrantToken": string, "watchUrl": string, "scheduledStart": string }

400 on invalid body. 404 if the session isn't open for registration
(cancelled, completed, or not found).

## BRAND FIELDS

Account-level brand fields (logo URL, accent color, theme mode,
background) are set via the dashboard today and are readable through
the public webinar endpoint's "brand" field. There is no public write
API for brand settings yet.

## COMING SOON

The following are planned but NOT available yet — do not assume they
exist:

- API-key access to session control (go-live/end) and registrant export
- Public write API for account brand settings

Re-fetch this guide (https://zingkast.com/agent) periodically — it is updated in
place as features ship.