Scheduled premieres

Schedule a stream to start at a specific time. Show a countdown lobby. Optionally play a pre-recorded video file as if it were live ("YouTube-style premieres").

No-code option: Schedule, cancel and force-start premieres from the customer portal at /app/premieres.

1. Two modes — live vs VOD

Mode	What happens at scheduled time	Use for
`live` (default)	An empty room is provisioned. The host publishes to it manually at or near the scheduled time.	Real live broadcasts that need a countdown lobby
`vod`	A pre-recorded MP4 from your VOD library is broadcast into the room as if it were live. Chat works in real time.	"Drops", produced content, replays of past events

2. Schedule a premiere

POST https://api.kardocloud.com/v1/me/premieres
Authorization: Bearer kl_live_xxx
{
  "streamName":   "Q4 product launch",
  "description":  "Our CTO walks through what's new this quarter.",
  "posterUrl":    "https://your-cdn.example.com/poster.webp",
  "scheduledFor": "2026-12-01T18:00:00.000Z",
  "mode":         "LOW_LATENCY",            // optional, default LOW_LATENCY
  "vodAssetId":   null,                     // null = live mode; recordingId = VOD-as-live
  "externalId":   "campaign-q4-launch",     // your-app's correlation id
  "notifyUserIds": ["user_1", "user_2", "user_99"]  // who to push when it goes live
}
→ { "id": "prem_xxx", "status": "scheduled", "streamId": null,
    "scheduledFor": "2026-12-01T18:00:00.000Z", ... }

The premiere stays in scheduled status until its time comes. streamId is null until the stream is provisioned (at the scheduled minute).

List your premieres

GET /v1/me/premieres                 // all
GET /v1/me/premieres?status=scheduled
GET /v1/me/premieres?status=live

3. Lobby page (countdown)

The lobby is a public, no-auth endpoint your client can poll to render a "Going live in 3:42:11" countdown. It returns the poster, description, and seconds remaining.

GET https://kardocloud.com/v1/premieres/<premiereId>/lobby
→ {
    "id":            "prem_xxx",
    "streamName":    "Q4 product launch",
    "description":   "...",
    "posterUrl":     "...",
    "scheduledFor":  "2026-12-01T18:00:00.000Z",
    "status":        "scheduled",
    "streamId":      null,
    "goesLiveInSec": 13331
  }

When status flips to live, streamId becomes available — your client switches from the countdown lobby to the actual stream player.

4. Auto-start & manual start

A scheduler service on the Kardolive control plane polls every 10 seconds and auto-transitions premieres whose scheduledFor time has passed.

To override the schedule and start immediately:

POST /v1/me/premieres/<premiereId>/start
→ { ...premiere, "status": "live", "streamId": "stream_xxx", "startedAt": "..." }

5. Notify your audience

When you schedule a premiere with notifyUserIds, Kardolive automatically sends a push notification to those users' devices the moment the premiere goes live. You need the push module set up on the project — see Push notifications.

The push payload includes:

{
  "notification": { "title": "Going live now", "body": "Q4 product launch" },
  "data": { "kardolive": "1", "kind": "premiere.live",
            "premiereId": "prem_xxx", "streamId": "stream_xxx" }
}

Your mobile app reads the data.streamId and deep-links the user into the live player.

6. Cancel a premiere

POST /v1/me/premieres/<premiereId>/cancel

Sets status to cancelled. The lobby page will show a "This event has been cancelled" message. You can only cancel premieres in scheduled or starting status.

7. Webhook events

Event	When
`premiere.scheduled`	You just created a premiere
`premiere.live`	Time came; stream provisioned; pushes sent
`premiere.ended`	Underlying stream ended
`premiere.cancelled`	You cancelled before it went live

Clips → · Push notifications → · Restream / simulcast →