Create Ingest Session - API

See the Custom WebSocket guide for the full WebSocket streaming and messaging protocol.

Creates a single-use ingest session for the custom WebSocket path. The response returns a wsUrl that your client connects to in order to stream PCM16 audio into a VideoSDK room, and optionally exchange topic-based pub/sub messages. The session is single-use and expires after expiresIn seconds if the client does not connect.

Call this from your backend, since it requires your VideoSDK token.

HTTP method and endpoint

POST

|

https://api.videosdk.live/v2/ingest/sessions

Headers Parameters

Authorization

REQUIRED

values: YOUR_TOKEN_WITHOUT_ANY_PREFIX

This will be a JWT token generate using VideoSDK ApiKey and Secret.

Note that the token will not include any prefix such as "Basic " or "Bearer ". Just pass a token as value.

You can generate a new token by refering this Guide: Generate Auth token

Content-Type

REQUIRED

values: application/json

This is usefull for json body parameters, so that VideoSDK servers can understand that the incoming body parameter will be a JSON string.

Body Parameters

roomId

REQUIRED

The room the stream joins.

participant

OPTIONAL

Identity for the ingested stream. Optional nested fields: id (custom participant ID; omit to let VideoSDK generate one), name (display name in the room), and metadata (object).

agent

OPTIONAL

Attach an AI agent to the session. Required nested field when provided: id. Optional: metadata.

region

OPTIONAL

Pins the ingest region (e.g. us002, in002).

Response Parameters

data

The session: wsUrl (single-use WebSocket endpoint carrying a ref claim), callId (backend handle, also appears on lifecycle webhooks), and expiresIn (seconds before the unclaimed session expires).

POST

|

https://api.videosdk.live/v2/ingest/sessions

NodeJS

• cURL
• NodeJS
• PHP
• Python

import fetch from 'node-fetch';
const options = {
	method: "POST",
	headers: {
		"Authorization": "$YOUR_TOKEN",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
	"roomId": "abcd-efgh-ijkl",
	"participant": {
		"name": "Field Device 12",
		"metadata": {
			"deviceId": "dev_12"
		}
	},
	"agent": {
		"id": "agent_123"
	},
	"region": "us002"
}),
};
const url= `https://api.videosdk.live/v2/ingest/sessions`;
const response = await fetch(url, options);
const data = await response.json();
console.log(data);

RESPONSE

{
  "message": "Ingest session created",
  "data": {
    "wsUrl": "wss://ingest.videosdk.live/videosdk?ref=vs_k9d8j2m4x7p1w5v3r6u0",
    "callId": "550e8400-e29b-41d4-a716-446655440000",
    "expiresIn": 90
  }
}