Live Streams

Manage live streaming sessions, schedules, recurring streams, and viewer interactions.

Live Streaming

The Live Streams API enables you to create, manage, and interact with live streaming sessions. Streams can be one-time events or recurring sessions with scheduled occurrences.

Overview

The Live Streams API provides:

Create and manage live streaming sessions
Schedule one-time and recurring streams
Get currently live streams
View upcoming streams
Stream statistics and analytics
Live chat integration
Viewer management

Base Path: /v1/livestreams

Public Endpoints: /v1/livestreams/public

Authentication Required

Most endpoints require internal admin authentication. Public endpoints (/livestreams/public) are available for mobile apps and can use optional authentication.

Public livestream responses include IVS fields when the stream uses IVS: playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, streamKey, enableRecording. The ingestEndpoint is OBS-ready (rtmps://host:443/app). streamKey is only returned on public endpoints (no host verification).

Host and hostId in responses

In responses, hostId is the educator user ID (ObjectId). The host field is populated by the API: it may be an object (e.g. name, email, profileImage) or, for legacy data, a string. Do not send host when creating or updating livestreams; only hostId is accepted.

Livestream responses may include optional image URLs: thumbnail (stream thumbnail) and banner_image (header/banner image for detail or listing cards). Both can be set when creating or updating a livestream.

Get Upcoming Public Livestreams

Get all upcoming public livestreams.

GET /v1/livestreams/public/upcoming

Query Parameters: Same as public livestreams endpoint.

Example Response: Same structure as Get Public Livestreams, including IVS fields (playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, streamKey, enableRecording) when the stream uses IVS.

Get Currently Live Public Streams (by Status)

Returns streams whose status field is live. Use this when you need streams that have been explicitly marked as live (e.g. by the host or system).

GET /v1/livestreams/public/live

Query Parameters: None.

Get Currently Live Public Streams (by Schedule)

Returns streams that are "live" according to the schedule: current time is between the stream's start and end, and for recurring streams, within the correct occurrence (daily/weekly/monthly). Use this when you want to show streams that are in their scheduled window regardless of the stored status field. Cancelled streams are never returned.

One-time streams: Included when the current time (UTC) is between startDate and endDate.
Recurring streams: Included when the current time falls within the occurrence window (scheduled time to end time on the correct day). Pass the optional timezone query parameter to evaluate in a specific timezone (e.g. user's local time); omit to use server time.

GET /v1/livestreams/public/live/scheduled

Query Parameters:

Parameter	Type	Description
timezone	string	Optional. IANA timezone (e.g. `America/New_York`, `Europe/London`) to determine "live" in that timezone. Recurring streams use this for occurrence windows; one-time streams remain UTC. Omit to use server time for recurring.

Test the live endpoints

Use the request testers below to call the live endpoints. Public livestream endpoints support optional authentication (API key and Bearer token are optional for unauthenticated access).

1. Live by status — returns streams with status: 'live':

2. Live by schedule — returns streams currently in their scheduled window. Edit the endpoint to add or change the timezone query (e.g. America/New_York, Europe/London) to evaluate in that timezone:

Get educators currently live (by schedule)

Returns unique educators (hosts) who are currently live by schedule. Uses the same logic as Get Currently Live Public Streams (by Schedule): current time within start/end and occurrence (with optional timezone). One educator per host; deduped by host ID.

GET /v1/livestreams/public/live/scheduled/educators

Query Parameters:

Parameter	Type	Description
timezone	string	Optional. IANA timezone (e.g. `America/New_York`) to evaluate "live" in that timezone.

Example Response: data is an array of educator objects. Each object includes educator fields (e.g. _id, name, headline, specialty, avatar, bio, stats) and a user field with the host user info (same shape as livestream responses). Educators without a resolved profile appear as { _id: "<hostId>", user: null } or with user populated when the user record exists.

Get Public Livestreams by Educator

Get all public livestreams for a specific educator with optional pagination.

GET /v1/livestreams/public/by-educator/:educatorId

Path Parameters:

Parameter	Type	Description
educatorId	string	Educator ID (host ID)

Query Parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page (default: 20)

Example Request:

# Development
curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/public/by-educator/507f1f77bcf86cd799439012?page=1&limit=10" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token" # Optional

# Production
curl -X GET "https://api-gateway.prod.1houseglobalservices.com/v1/livestreams/public/by-educator/507f1f77bcf86cd799439012?page=1&limit=10" \
  -H "X-API-Key: your-production-api-key" \
  -H "Authorization: Bearer your-jwt-token" # Optional

const educatorId = '507f1f77bcf86cd799439012';
const response = await fetch(
  `https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/public/by-educator/${educatorId}?page=1&limit=10`,
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token', // Optional
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();

import requests

educator_id = "507f1f77bcf86cd799439012"
url = f"https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/public/by-educator/{educator_id}"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",  # Optional
    "Content-Type": "application/json"
}
params = {
    "page": 1,
    "limit": 10
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

Try it out:

Example Response: Same structure as Get Public Livestreams: data array of livestream objects and pagination object. Includes IVS fields (playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, streamKey, enableRecording) when the stream uses IVS.

Get Public Livestream by ID

Get details of a specific public livestream.

GET /v1/livestreams/public/:livestreamId

Example Request:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/public/507f1f77bcf86cd799439011" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token" # Optional

Example Response: Same structure as a single livestream object in the Get Public Livestreams list, including IVS fields (playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, streamKey, enableRecording) when the stream uses IVS.

Admin Endpoints

These endpoints require internal admin authentication and provide full management capabilities.

Get All Livestreams

Get all livestreams with advanced filtering and pagination.

GET /v1/livestreams

Query Parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page (default: 20)
search	string	Search by title or description
status	string	Filter by status
category	string	Filter by category
host	string	Filter by host (educator) ID; same as hostId
hostId	string	Filter by educator/host user ID (ObjectId)
isRecurring	boolean	Filter recurring streams
sortBy	string	Sort field (default: `startDate`)
sortOrder	string	Sort order: `asc` or `desc` (default: `desc`)

Example Response:

{
  "success": true,
  "status": 200,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Trading Strategies for Beginners",
      "description": "Learn the fundamentals of trading",
      "hostId": "507f1f77bcf86cd799439012",
      "host": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "category": "Education",
      "status": "live",
      "startDate": "2025-01-15T10:00:00.000Z",
      "endDate": "2025-01-15T11:00:00.000Z",
      "event_id": "vimeo_event_123",
      "thumbnail": "https://example.com/thumb.jpg",
      "banner_image": "https://example.com/banner.jpg",
      "viewerCount": 150,
      "isRecurring": false,
      "playbackUrl": "https://0696941182a8.us-east-1.playback.live-video.net/api/video/v1/us-east-1.353922334510.channel.GXY8nbaZjUQx.m3u8",
      "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app",
      "ivsChannelArn": "arn:aws:ivs:us-east-1:353922334510:channel/GXY8nbaZjUQx",
      "ivsChannelId": "GXY8nbaZjUQx",
      "enableRecording": false,
      "createdAt": "2025-01-10T00:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Get Livestream by ID

Get detailed information about a specific livestream.

GET /v1/livestreams/:livestreamId

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "Trading Strategies for Beginners",
    "description": "Learn the fundamentals of trading",
    "hostId": "507f1f77bcf86cd799439012",
    "host": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "category": "Education",
    "status": "live",
    "startDate": "2025-01-15T10:00:00.000Z",
    "endDate": "2025-01-15T11:00:00.000Z",
    "event_id": "vimeo_event_123",
    "thumbnail": "https://example.com/thumb.jpg",
    "banner_image": "https://example.com/banner.jpg",
    "viewerCount": 150,
    "isRecurring": false,
    "playbackUrl": "https://0696941182a8.us-east-1.playback.live-video.net/api/video/v1/us-east-1.353922334510.channel.GXY8nbaZjUQx.m3u8",
    "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app",
    "ivsChannelArn": "arn:aws:ivs:us-east-1:353922334510:channel/GXY8nbaZjUQx",
    "ivsChannelId": "GXY8nbaZjUQx",
    "enableRecording": false,
    "createdAt": "2025-01-10T00:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}

Create Livestream

Create a new livestream session.

POST /v1/livestreams

Request Body:

{
  "title": "Advanced Trading Techniques",
  "description": "Learn advanced trading strategies",
  "hostId": "507f1f77bcf86cd799439012",
  "category": "Education",
  "startDate": "2025-01-20T14:00:00.000Z",
  "endDate": "2025-01-20T15:00:00.000Z",
  "event_id": "vimeo_event_456",
  "startTime": "2025-01-20T14:00:00",
  "duration": 60,
  "isRecurring": false
}

Required Fields:

title - Stream title
description - Stream description
hostId - Educator (host) user ID — the _id of the user who will host the stream (must be a user with educator permission). Do not send educator name; only the ID is accepted.
startDate - ISO 8601 format start date/time
category - Stream category (plain text field)

Educator must be specified by ID only

When creating or updating a livestream, you must provide the educator's user ID in hostId. Do not pass a host field with the educator's name. The API does not accept manually specified educator names; host info (name, avatar) is resolved from the user record by hostId.

Optional Fields:

event_id - External event ID (e.g., Vimeo event ID)
startTime - Start time in datetime-local format (YYYY-MM-DDTHH:mm)
endDate - ISO 8601 format end date/time (auto-calculated from duration if not provided)
duration - Duration in minutes (used to calculate endDate if endDate not provided)
thumbnail - Thumbnail image URL for the stream
banner_image - Banner/header image URL for the stream (e.g. for detail or listing cards)
isRecurring - Boolean for recurring streams
recurrencePattern - daily, weekly, or monthly (required if isRecurring is true)
recurrenceEndDate or recurrenceEnd - End date for recurring streams (required if isRecurring is true)

Recurring Streams

When creating a recurring stream, you must provide:

isRecurring: true
recurrencePattern: daily, weekly, or monthly
recurrenceEndDate: ISO 8601 format end date for the recurrence series

Example Request:

curl -X POST "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Advanced Trading Techniques",
    "description": "Learn advanced trading strategies",
    "hostId": "507f1f77bcf86cd799439012",
    "category": "Education",
    "startDate": "2025-01-20T14:00:00.000Z",
    "endDate": "2025-01-20T15:00:00.000Z"
  }'

const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/livestreams',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Advanced Trading Techniques',
      description: 'Learn advanced trading strategies',
      hostId: '507f1f77bcf86cd799439012',
      category: 'Education',
      startDate: '2025-01-20T14:00:00.000Z',
      endDate: '2025-01-20T15:00:00.000Z',
    }),
  }
);

const data = await response.json();

import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",
    "Content-Type": "application/json"
}
data = {
    "title": "Advanced Trading Techniques",
    "description": "Learn advanced trading strategies",
    "hostId": "507f1f77bcf86cd799439012",
    "category": "Education",
    "startDate": "2025-01-20T14:00:00.000Z",
    "endDate": "2025-01-20T15:00:00.000Z"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "_id": "507f1f77bcf86cd799439099",
    "title": "Advanced Trading Techniques",
    "description": "Learn advanced trading strategies",
    "hostId": "507f1f77bcf86cd799439012",
    "category": "Education",
    "status": "scheduled",
    "startDate": "2025-01-20T14:00:00.000Z",
    "endDate": "2025-01-20T15:00:00.000Z",
    "event_id": "vimeo_event_456",
    "thumbnail": "https://example.com/thumb.jpg",
    "banner_image": "https://example.com/banner.jpg",
    "isRecurring": false,
    "playbackUrl": "https://0696941182a8.us-east-1.playback.live-video.net/api/video/v1/us-east-1.353922334510.channel.GXY8nbaZjUQx.m3u8",
    "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app",
    "ivsChannelArn": "arn:aws:ivs:us-east-1:353922334510:channel/GXY8nbaZjUQx",
    "ivsChannelId": "GXY8nbaZjUQx",
    "enableRecording": false,
    "createdAt": "2025-01-10T00:00:00.000Z",
    "updatedAt": "2025-01-10T00:00:00.000Z"
  }
}

Update Livestream

Update an existing livestream.

PUT /v1/livestreams/:livestreamId

Request Body: Same fields as create, all optional. Use hostId (educator user ID) only — do not send host (educator name).

Example Response: Same structure as Get Livestream by ID: the updated livestream object including IVS fields (playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, enableRecording) when the stream uses IVS. streamKey is not returned on admin endpoints.

Delete Livestream

Delete a livestream.

DELETE /v1/livestreams/:livestreamId

Update Livestream Status

Update the status of a livestream.

PUT /v1/livestreams/:livestreamId/status

Request Body:

{
  "status": "live"
}

Valid Status Values:

scheduled - Stream is scheduled but not started
live - Stream is currently live
ended - Stream has ended

Start Livestream

Start a livestream session.

POST /v1/livestreams/:livestreamId/start

End Livestream

End a livestream session.

POST /v1/livestreams/:livestreamId/end

Special Endpoints

Get Upcoming Livestreams

Get all upcoming livestreams (both one-time and recurring).

GET /v1/livestreams/upcoming

Example Response: Same structure as Get All Livestreams: data array of livestream objects with IVS fields (playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, enableRecording) when the stream uses IVS. streamKey is not returned on admin endpoints.

Get Currently Live Streams

Get all streams that are currently live.

GET /v1/livestreams/live

Get Recurring Livestreams

Get all recurring livestreams.

GET /v1/livestreams/recurring

Get Livestream Statistics

Get aggregated statistics for livestreams.

GET /v1/livestreams/stats

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "total": 150,
    "live": 5,
    "scheduled": 45,
    "ended": 100,
    "totalViewers": 5000,
    "averageViewers": 33,
    "categories": {
      "Education": 80,
      "Trading": 50,
      "Community": 20
    }
  }
}

Get Livestream Categories

Get all available livestream categories.

GET /v1/livestreams/categories

Get Livestream Hosts

Get all livestream hosts.

GET /v1/livestreams/hosts

Get Livestreams Calendar

Get livestreams formatted for calendar view.

GET /v1/livestreams/calendar

Query Parameters:

Parameter	Type	Description
startDate	string	ISO 8601 format start date
endDate	string	ISO 8601 format end date

Get Weekly Schedule

Get all livestreams (one-time and recurring) for a specific week based on a given day and timezone.

POST /v1/livestreams/schedule/week

Request Body:

{
  "day": "2025-01-15T10:00:00.000Z",
  "timezone": "America/New_York"
}

Request Body Parameters:

Parameter	Type	Description
day	string	ISO 8601 date string for any day in the week
timezone	string	IANA timezone identifier (e.g., "America/New_York", "Europe/London")

Example Request:

curl -X POST "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/schedule/week" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "day": "2025-01-15T10:00:00.000Z",
    "timezone": "America/New_York"
  }'

const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/schedule/week',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      day: '2025-01-15T10:00:00.000Z',
      timezone: 'America/New_York',
    }),
  }
);

const data = await response.json();

import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/schedule/week"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",
    "Content-Type": "application/json"
}
data = {
    "day": "2025-01-15T10:00:00.000Z",
    "timezone": "America/New_York"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

Example Response:

{
  "success": true,
  "status": 200,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Trading Strategies for Beginners",
      "description": "Learn the fundamentals of trading",
      "hostId": "507f1f77bcf86cd799439012",
      "category": "Education",
      "status": "scheduled",
      "startDate": "2025-01-15T10:00:00.000Z",
      "endDate": "2025-01-15T11:00:00.000Z",
      "occurrenceDate": "2025-01-15T15:00:00.000Z",
      "occurrenceEndDate": "2025-01-15T16:00:00.000Z",
      "weekday": 3,
      "startTime": "10:00 AM",
      "isRecurring": false,
      "playbackUrl": "https://0696941182a8.us-east-1.playback.live-video.net/api/video/v1/us-east-1.353922334510.channel.GXY8nbaZjUQx.m3u8",
      "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app",
      "ivsChannelArn": "arn:aws:ivs:us-east-1:353922334510:channel/GXY8nbaZjUQx",
      "ivsChannelId": "GXY8nbaZjUQx",
      "enableRecording": false,
      "user": {
        "_id": "507f1f77bcf86cd799439012",
        "name": "John Doe",
        "email": "john@example.com"
      }
    },
    {
      "_id": "507f1f77bcf86cd799439022",
      "title": "Weekly Market Analysis",
      "description": "Recurring weekly analysis",
      "hostId": "507f1f77bcf86cd799439013",
      "category": "Trading",
      "status": "scheduled",
      "startDate": "2025-01-13T14:00:00.000Z",
      "endDate": "2025-01-13T15:00:00.000Z",
      "isRecurring": true,
      "recurrencePattern": "weekly",
      "recurrenceEndDate": "2025-12-31T23:59:59.000Z",
      "occurrenceDate": "2025-01-20T19:00:00.000Z",
      "occurrenceEndDate": "2025-01-20T20:00:00.000Z",
      "weekday": 1,
      "startTime": "2:00 PM",
      "playbackUrl": "https://0696941182a8.us-east-1.playback.live-video.net/api/video/v1/us-east-1.353922334510.channel.GXY8nbaZjUQx.m3u8",
      "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app",
      "ivsChannelArn": "arn:aws:ivs:us-east-1:353922334510:channel/GXY8nbaZjUQx",
      "ivsChannelId": "GXY8nbaZjUQx",
      "enableRecording": false,
      "user": {
        "_id": "507f1f77bcf86cd799439013",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    }
  ],
  "message": "Weekly schedule retrieved successfully"
}

Weekday Numbers

The weekday field represents the day of the week in the specified timezone:

0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday

Week Calculation

The week is calculated from Sunday (day 0) to Saturday (day 6) based on the timezone provided. The day parameter can be any date within the week - the endpoint will automatically calculate the full week range.

Recurring Streams

For recurring streams, the endpoint generates all occurrences within the week based on the recurrence pattern:

Daily: Every day within the week
Weekly: Same day of week as the original start date
Monthly: Same day of month as the original start date (if it falls within the week)

Start Time

The startTime field contains the time only (12-hour format with AM/PM) for the livestream occurrence in the specified timezone. For example, "2:30 PM" represents 2:30 PM in the timezone. This field is useful for displaying the time without the date.

Get Available Timezones

Get all available IANA timezones with their common names for use in schedule requests.

GET /v1/livestreams/timezones

Example Request:

curl -X GET "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/timezones" \
  -H "X-API-Key: your-development-api-key" \
  -H "Authorization: Bearer your-jwt-token"

const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/timezones',
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();

import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/livestreams/timezones"
headers = {
    "X-API-Key": "your-development-api-key",
    "Authorization": "Bearer your-jwt-token",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
result = response.json()

Example Response:

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "America/New_York",
      "commonName": "Eastern Time (US & Canada)",
      "displayName": "Eastern Time (US & Canada) (America/New_York)",
      "offset": "EST"
    },
    {
      "id": "America/Chicago",
      "commonName": "Central Time (US & Canada)",
      "displayName": "Central Time (US & Canada) (America/Chicago)",
      "offset": "CST"
    },
    {
      "id": "Europe/London",
      "commonName": "Greenwich Mean Time (London)",
      "displayName": "Greenwich Mean Time (London) (Europe/London)",
      "offset": "GMT"
    },
    {
      "id": "Asia/Tokyo",
      "commonName": "Japan Standard Time",
      "displayName": "Japan Standard Time (Asia/Tokyo)",
      "offset": "JST"
    }
  ],
  "message": "Timezones retrieved successfully"
}

Timezone Format

All timezones use IANA timezone identifiers (e.g., "America/New_York", "Europe/London"). The id field should be used in the timezone parameter when calling the weekly schedule endpoint.

Livestream IVS Details (Session Details)

Get detailed livestream session information including host (user) and IVS (Amazon Interactive Video Service) stream details. Use this endpoint when you need playback URL, ingest endpoint, or other IVS metadata to embed or broadcast the stream.

POST /v1/session/live-stream/details

Request Body:

Parameter	Type	Description
session	string	Livestream ID (`_id`)

{
  "session": "507f1f77bcf86cd799439011"
}

IVS fields in session (when the livestream uses IVS):

Field	Description
`playbackUrl`	URL for viewers (use with Amazon IVS Web Player or compatible player)
`ingestEndpoint`	RTMPS endpoint for broadcasters (OBS, etc.)
`ivsChannelArn`	IVS channel ARN
`ivsChannelId`	IVS channel ID
`enableRecording`	Whether recording is enabled

The streamKey is not returned in session responses. Public livestream endpoints do return streamKey (no host verification). Hosts (broadcasters) can use the Get broadcast credentials endpoint for the decrypted stream key and OBS-ready ingest URL, or use streamKey from public endpoints.

Example Request:

curl -X POST "https://api-gateway.dev.1houseglobalservices.com/v1/session/live-stream/details" \
  -H "X-API-Key: your-development-api-key" \
  -H "Content-Type: application/json" \
  -d '{"session": "507f1f77bcf86cd799439011"}'

const response = await fetch(
  'https://api-gateway.dev.1houseglobalservices.com/v1/session/live-stream/details',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-development-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ session: '507f1f77bcf86cd799439011' }),
  }
);
const data = await response.json();

import requests

url = "https://api-gateway.dev.1houseglobalservices.com/v1/session/live-stream/details"
headers = {
    "X-API-Key": "your-development-api-key",
    "Content-Type": "application/json"
}
payload = {"session": "507f1f77bcf86cd799439011"}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

Try it out:

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "session": {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Trading Strategies for Beginners",
      "description": "Learn the fundamentals of trading",
      "hostId": "507f1f77bcf86cd799439012",
      "category": "Education",
      "status": "live",
      "startDate": "2025-01-15T10:00:00.000Z",
      "endDate": "2025-01-15T11:00:00.000Z",
      "event_id": "evt_abc123",
      "playbackUrl": "https://0696941182a8.us-east-1.playback.live-video.net/api/video/v1/us-east-1.353922334510.channel.GXY8nbaZjUQx.m3u8",
      "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app",
      "ivsChannelArn": "arn:aws:ivs:us-east-1:353922334510:channel/GXY8nbaZjUQx",
      "ivsChannelId": "GXY8nbaZjUQx",
      "enableRecording": false
    },
    "user": {
      "_id": "507f1f77bcf86cd799439012",
      "id": "507f1f77bcf86cd799439012",
      "name": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "thumbnail_url": "https://cdn.1houseglobal.com/avatar.jpg"
    },
    "event": "evt_abc123"
  }
}

IVS in public endpoints

The public livestream endpoints (GET /v1/livestreams/public, /public/upcoming, /public/live, /public/live/scheduled, /public/live/scheduled/educators, /public/by-educator/:educatorId, /public/:livestreamId) return IVS fields (playbackUrl, ingestEndpoint, ivsChannelArn, ivsChannelId, streamKey, enableRecording) in each livestream object when the stream uses IVS. The ingestEndpoint is OBS-ready (rtmps://host:443/app). The streamKey is included on public endpoints only (no host verification). Session and admin responses do not include streamKey; use the broadcast-credentials endpoint for that.

Get broadcast credentials (OBS)

Hosts only. Returns the decrypted stream key and an OBS-ready ingest URL for broadcasting. Access is allowed when the JWT user is the livestream host: hostId references an Educator; the JWT carries a User id. You are allowed if the Educator’s hostId equals your user id, or if your user id matches the Educator’s linked userId.

GET /v1/livestreams/:livestreamId/broadcast-credentials

Headers: Authorization: Bearer <JWT>

Response:

{
  "success": true,
  "data": {
    "ingestEndpoint": "rtmps://0696941182a8.global-contribute.live-video.net:443/app/",
    "streamKey": "sk_us-east-1_abcd1234..."
  }
}

OBS Setup (recommended: Amazon IVS):

In OBS: Settings > Stream > Service: choose Amazon IVS.
Stream key: use only the streamKey from this response. OBS uses AWS’s default ingest; you do not enter a custom Server.

OBS Setup (Custom):

Service: choose Custom.
Server: use ingestEndpoint from this response (e.g. rtmps://...:443/app/).
Stream key: use only the streamKey from this response. No other value (including any streamKey from session or livestream APIs) will work.

Use the decrypted stream key from this endpoint only

Older or internal responses may have included an encrypted streamKey; that value will not work in OBS. Always use GET /v1/livestreams/:livestreamId/broadcast-credentials to obtain the decrypted key. For Custom, the Stream key must be exactly the streamKey from this endpoint.

Live Stream Chat

Live streams support real-time chat functionality. See the Realtime documentation for WebSocket chat integration.

Chat Integration

Live streams automatically create chat rooms. Use the stream's _id as the roomId when connecting to the chat WebSocket.

Live Stream Authentication

For embedded live streams, you can generate a bearer token for viewer authentication:

POST /v1/auth/token

Request Body:

{
  "userId": "507f1f77bcf86cd799439012",
  "roomId": "507f1f77bcf86cd799439011",
  "username": "John Doe"
}

Example Response:

{
  "success": true,
  "status": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "bearerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "1h",
    "tokenType": "Bearer"
  }
}

Token Expiration

Live stream session tokens expire after 1 hour. Refresh tokens as needed for long-running sessions.

Data Models

Livestream Object

interface Livestream {
  _id: string;
  title: string;
  description: string;
  hostId?: string;  // Educator user ID — required on create/update; only ID is accepted, not name
  host?: string | User;  // Populated by API (read-only); do not send on create/update
  category: string; // Plain text field (not a dropdown)
  status: 'scheduled' | 'live' | 'ended';
  startDate: string; // ISO 8601
  startTime?: string; // datetime-local format (YYYY-MM-DDTHH:mm)
  endDate?: string; // ISO 8601
  duration?: number; // Duration in minutes
  event_id?: string; // External event ID
  viewerCount?: number;
  isRecurring: boolean;
  recurrencePattern?: 'daily' | 'weekly' | 'monthly';
  recurrenceEndDate?: string; // ISO 8601
  recurrenceEnd?: string; // Alternative field name for recurrence end date
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
  // IVS (Amazon Interactive Video Service) – present when stream uses IVS
  playbackUrl?: string;    // For viewers (Amazon IVS Web Player or compatible)
  ingestEndpoint?: string; // RTMPS endpoint for broadcasters (OBS-ready: rtmps://host:443/app)
  ivsChannelArn?: string;
  ivsChannelId?: string;
  streamKey?: string;     // Public endpoints only; for broadcast use broadcast-credentials
  enableRecording?: boolean;
}

Error Handling

Common error responses:

400 Bad Request

{
  "success": false,
  "status": 400,
  "message": "Missing required fields: title, description",
  "error": {
    "missingFields": ["title", "description"]
  }
}

404 Not Found

{
  "success": false,
  "status": 404,
  "message": "Livestream not found"
}

401 Unauthorized

{
  "success": false,
  "status": 401,
  "message": "Unauthorized - Invalid or missing authentication"
}

Best Practices

Use Public Endpoints for Mobile Apps

Use the /v1/livestreams/public endpoints for mobile applications. These endpoints support optional authentication and are optimized for client-side use.

Handle Recurring Streams

When working with recurring streams:

Check isRecurring flag
Use recurrencePattern to determine occurrence schedule
Calculate next occurrence based on pattern and startDate
Respect recurrenceEndDate to know when series ends

Poll for Live Status

For real-time updates, poll every 30-60 seconds:

By status: Use GET /v1/livestreams/public/live to get streams whose status is live.
By schedule: Use GET /v1/livestreams/public/live/scheduled to get streams that are in their scheduled window. Pass the timezone query parameter (e.g. ?timezone=America/New_York) to evaluate in the user's timezone, which is recommended for recurring streams.

Use Session Details for IVS and Host Info

When you need stream, host (user), and IVS details (playback URL, ingest endpoint, channel IDs), use the /v1/session/live-stream/details endpoint instead of making separate API calls.

Cache Stream Data

Cache livestream data on the client side to reduce API calls. Refresh every 5-10 minutes for scheduled streams, more frequently for live streams.

Realtime API - WebSocket chat and real-time updates
Authentication - User authentication and tokens
Wallet - Tips and payments for live streams

Live Streams

On this page