ScreenParty

Creates a private ScreenParty room where friends watch the same video in sync, in their browsers, with chat and voice. Use it when the user wants to watch something together now, or plan a watch party at a set time. Without start_time the room is ready now: the first person to open room_link becomes the host (controls playback), so tell the user to open it before sharing. With start_time it returns a countdown page with "add to calendar" for guests; the room opens 15 minutes early, and organiser_link lets the user open it any time and host it. Share room_link or schedule_page with guests; keep organiser_link and organiser_key for the user only (they also cancel it with cancel_watch_party).

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 60,
      "description": "What people will watch, e.g. \"Lesson 3: Past tense\". Defaults to \"Watch party\"."
    },
    "video_url": {
      "type": "string",
      "description": "Optional video the room opens with. A direct video link (mp4, webm, m3u8) or a public YouTube video URL. Paid streaming services are not supported."
    },
    "start_time": {
      "type": "string",
      "description": "Optional. ISO 8601 date-time WITH a time zone, e.g. 2026-11-07T20:00:00+08:00 (ask the user for their time zone if unknown). Omit for a room that opens now. Up to 60 days ahead."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "room_code": {
      "type": "string",
      "description": "5-character room code."
    },
    "room_link": {
      "type": "string",
      "description": "Link guests open to join the room."
    },
    "schedule_page": {
      "type": "string",
      "description": "Countdown page with \"add to calendar\"; best link to share for a later party."
    },
    "organiser_link": {
      "type": "string",
      "description": "Private: opens the room as host, even before it opens to guests."
    },
    "organiser_key": {
      "type": "string",
      "description": "Private: needed to cancel with cancel_watch_party."
    },
    "starts_at": {
      "type": "string",
      "description": "ISO time it starts."
    },
    "opens_at": {
      "type": "string",
      "description": "ISO time guests can enter (15 minutes before)."
    }
  },
  "required": [
    "ok"
  ]
}

Looks up a room or scheduled watch party by its 5-character code (from create_watch_room or from a ScreenParty link such as …/s/AB2CD or …room.html?room=AB2CD). Returns its title, start time, whether guests can enter yet and whether people are in it right now. Use it to answer "when does it start?" or "is it open?". Read-only; it never reveals who is in the room.

{
  "type": "object",
  "properties": {
    "room_code": {
      "type": "string",
      "maxLength": 10,
      "description": "The 5-character room code, e.g. AB2CD."
    }
  },
  "required": [
    "room_code"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "room_code": {
      "type": "string",
      "description": "Room code."
    },
    "title": {
      "type": "string",
      "description": "Title of a scheduled party."
    },
    "starts_at": {
      "type": "string",
      "description": "ISO start time."
    },
    "opens_at": {
      "type": "string",
      "description": "ISO time guests can enter."
    },
    "open_to_guests": {
      "type": "boolean"
    },
    "live": {
      "type": "boolean",
      "description": "Someone is in the room now."
    },
    "room_link": {
      "type": "string",
      "description": "Join link."
    },
    "schedule_page": {
      "type": "string",
      "description": "Countdown page."
    }
  },
  "required": [
    "ok"
  ]
}

Cancels a watch party made with create_watch_room: its countdown page and link stop working. Needs the organiser_key (or organiser_link) that create_watch_room returned, so only the organiser can cancel. A room that is already open carries on until everyone leaves. Cannot be undone; confirm with the user first.

{
  "type": "object",
  "properties": {
    "room_code": {
      "type": "string",
      "maxLength": 10,
      "description": "The 5-character room code. Not needed when organiser_link is given."
    },
    "organiser_key": {
      "type": "string",
      "maxLength": 99,
      "description": "The organiser_key from create_watch_room."
    },
    "organiser_link": {
      "type": "string",
      "description": "Alternatively, the organiser_link from create_watch_room."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "room_code": {
      "type": "string",
      "description": "The cancelled room code."
    }
  },
  "required": [
    "ok"
  ]
}

Creates a permanent public page (…/r/<slug>) with a name, an optional one-line description, colour and video. Everyone who opens it lands in that page's room, any time, so it suits teachers, classes, clubs and communities who reuse one link every week (for a one-off, use create_watch_room). Returns public_link to share and a private edit_link: the user opens it to add a logo and background and download a poster with a QR code, and it is needed for update_branded_link and delete_branded_link. Give edit_link only to the user, never to guests.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 40,
      "description": "Name shown on the page, e.g. \"Ms. Lee's English Class\"."
    },
    "slug": {
      "type": "string",
      "maxLength": 30,
      "description": "Optional. The link ending: 3-30 lowercase Latin letters, digits and hyphens (e.g. lee-english). Made from the name if omitted."
    },
    "tagline": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional one line, e.g. \"Every Tuesday at 8 pm\"."
    },
    "color": {
      "type": "string",
      "description": "Optional theme colour as #rrggbb."
    },
    "video_url": {
      "type": "string",
      "description": "Optional video to load in the room. A direct video link (mp4, webm, m3u8) or a public YouTube video URL. Paid streaming services are not supported."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "public_link": {
      "type": "string",
      "description": "Link to share."
    },
    "edit_link": {
      "type": "string",
      "description": "Private edit link."
    },
    "slug": {
      "type": "string",
      "description": "The link ending."
    }
  },
  "required": [
    "ok"
  ]
}

Shows what a branded page (…/r/<slug>) currently says: name, description, colour, video, whether it has a logo or background, and whether people are in its room right now. Use it before changing a page or to check a slug the user mentions. Read-only; needs no key.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "maxLength": 60,
      "description": "The slug after /r/, or the whole public link."
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "slug": {
      "type": "string",
      "description": "Slug."
    },
    "name": {
      "type": "string",
      "description": "Name."
    },
    "tagline": {
      "type": "string",
      "description": "One-line description."
    },
    "color": {
      "type": "string",
      "description": "#rrggbb."
    },
    "video_url": {
      "type": "string",
      "description": "Video the room opens with, if any."
    },
    "has_logo": {
      "type": "boolean"
    },
    "has_background": {
      "type": "boolean"
    },
    "live": {
      "type": "boolean",
      "description": "Someone is in the room now."
    },
    "public_link": {
      "type": "string",
      "description": "Public link."
    }
  },
  "required": [
    "ok"
  ]
}

Changes the name, description, colour or video of a branded page made with create_branded_link. Pass only the fields to change; the link itself (slug) stays the same, so posters and shared links keep working. Needs the private edit_link (or slug and edit_key). Pass video_url as an empty string to remove the video. Logo and background are changed on the edit page, not here.

{
  "type": "object",
  "properties": {
    "edit_link": {
      "type": "string",
      "description": "The private edit link returned by create_branded_link (…/r/<slug>/edit#k=<key>). Alternatively pass slug and edit_key."
    },
    "slug": {
      "type": "string",
      "maxLength": 60,
      "description": "The page's slug (the part after /r/). Needed with edit_key when edit_link is not given."
    },
    "edit_key": {
      "type": "string",
      "maxLength": 99,
      "description": "The key after #k= in the edit link."
    },
    "name": {
      "type": "string",
      "maxLength": 40,
      "description": "New name."
    },
    "tagline": {
      "type": "string",
      "maxLength": 120,
      "description": "New one-line description; empty string removes it."
    },
    "color": {
      "type": "string",
      "description": "New theme colour as #rrggbb."
    },
    "video_url": {
      "type": "string",
      "description": "New video, or empty string for none. A direct video link (mp4, webm, m3u8) or a public YouTube video URL. Paid streaming services are not supported."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "public_link": {
      "type": "string",
      "description": "Public link (unchanged)."
    },
    "slug": {
      "type": "string",
      "description": "Slug."
    }
  },
  "required": [
    "ok"
  ]
}

Permanently deletes a branded page made with create_branded_link; its public link and posters stop working. Needs the private edit_link (or slug and edit_key). Cannot be undone; confirm with the user first.

{
  "type": "object",
  "properties": {
    "edit_link": {
      "type": "string",
      "description": "The private edit link returned by create_branded_link (…/r/<slug>/edit#k=<key>). Alternatively pass slug and edit_key."
    },
    "slug": {
      "type": "string",
      "maxLength": 60,
      "description": "The page's slug (the part after /r/). Needed with edit_key when edit_link is not given."
    },
    "edit_key": {
      "type": "string",
      "maxLength": 99,
      "description": "The key after #k= in the edit link."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "false when the call failed; then code says why."
    },
    "code": {
      "type": "string",
      "description": "Error code when ok is false."
    },
    "slug": {
      "type": "string",
      "description": "The deleted slug."
    }
  },
  "required": [
    "ok"
  ]
}