Schedule a premiere

POST/v1/organization/{orgId}/marketing/video/premieres/ensure

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

A recording plays at startsAt for everyone on the event page at the same moment, with questions and polls beside it. Visitors can ask for a reminder (emailed the day before and just before the start); afterwards it plays on demand with the recording's gate. eventId defaults to the recording's event. With addToPage: true the premiere goes on the event page draft; nothing is published. The same recording on the same page is one premiere: calling again with a new time moves it. Requires write:marketing; refused for a key restricted to particular events. Also at POST /v1/marketing/video/premieres/ensure.

Request example

cURL

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/premieres/ensure' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startsAt": "<string>",
  "eventId": 123,
  "title": "<string>",
  "addToPage": true
}'

JavaScript

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/premieres/ensure', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startsAt": "<string>",
    "eventId": 123,
    "title": "<string>",
    "addToPage": true
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/premieres/ensure",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "startsAt": "<string>",
        "eventId": 123,
        "title": "<string>",
        "addToPage": True
    },
)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/premieres/ensure",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startsAt": "<string>",
  "eventId": 123,
  "title": "<string>",
  "addToPage": true
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/premieres/ensure", strings.NewReader(`{
  "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startsAt": "<string>",
  "eventId": 123,
  "title": "<string>",
  "addToPage": true
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/premieres/ensure"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"mediaId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"startsAt\": \"<string>\",\n  \"eventId\": 123,\n  \"title\": \"<string>\",\n  \"addToPage\": true\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

RegionUS Region — https://public-api.sessionboard.comEU Region — https://public-api-eu.sessionboard.com

Authorization

Send asAPI token (x-access-token)OAuth access token (Bearer)

Token

Your token stays in this page. It is sent only to the region above and is never saved; it is gone when you leave or reload the page.

Path parameters

orgId*

Body application/json

{ "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "startsAt": "<string>", "eventId": 123, "title": "<string>", "addToPage": true }

POST

Send request

Authorizations

• x-access-tokenstringheader

  Organization API token. Generate from Organization Settings → API Tokens.

• AuthorizationBearer <token>headeror

  OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

• orgIdstringpathrequired

  Your organization ID. Any other organization returns 404.

Request body

application/jsonrequired

• mediaIdstring<uuid>required

  The recording

• startsAtstringrequired

  ISO 8601 with a timezone offset, at least a minute from now

• eventIdinteger

  The event page; defaults to the recording's event

• titlestring

  The recording's title by default

  Max length

  255

• addToPageboolean

  Also put the premiere on the event page draft. Never publishes.

Example

{
  "mediaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "startsAt": "<string>",
  "eventId": 123,
  "title": "<string>",
  "addToPage": true
}

Responses

200

payload.premiere (a Premiere), payload.created, and with addToPage payload.page (preview_url, revision, is_live). payload.warning when the recording's length is not known yet.

400

A start in the past or less than a minute away.

403

• SCOPE_REQUIRED — the token lacks read:marketing (reads) or write:marketing (writes).
• ORG_WIDE_TOKEN_REQUIRED — the token is restricted to particular events; this operation reads the whole organization.
• FORBIDDEN — the organization's plan does not include Marketing, or the token's user cannot change goals (writes need an organization admin or the organization settings permission).

404

The recording or event is not in your organization.