Skip to main content
POST
/
api
/
roleplay
/
session
Session - Create Session
curl --request POST \
  --url https://app.replay.sale/api/roleplay/session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "premadeRoleplayId": "550e8400-e29b-41d4-a716-446655440000",
  "userUniqueIdentifier": "user-123",
  "userName": "John Doe",
  "recordVideo": false
}
'
{
  "success": true,
  "data": {
    "roleplayId": "123e4567-e89b-12d3-a456-426614174000",
    "roomName": "John Doe::123e4567-e89b-12d3-a456-426614174000",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "websocketUrl": "wss://livekit.example.com"
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication. Get your API key from your company settings.

Body

application/json
​
premadeRoleplayId
string<uuid>
required

UUID of the premade roleplay to use for room creation.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
userUniqueIdentifier
string
required

Unique identifier for the external user. Used for user resolution:

Existing User: If a user with the same userUniqueIdentifier exists for the company, their record is used New User: If no matching user exists, an Integration user is automatically created with the provided userName and userUniqueIdentifier, associated with the company's Integration team

This ensures consistent user tracking across multiple API calls.

Minimum string length: 1
Example:

"user-123"

​
userName
string
required

Name of the user who will participate in the roleplay. Used for displaying and using the user's name in the roleplay.

Minimum string length: 1
Example:

"John Doe"

​
recordVideo
boolean
required

Whether to record video for the roleplay session.

true: Video recording will be captured false: No video recording

Note: Audio is always recorded.

Example:

false

Response

Room created successfully. Use the returned credentials to connect to the LiveKit room.

Next Steps:

  1. Use the accessToken and websocketUrl to connect via LiveKit SDK
  2. The AI agent will automatically join the room
  3. Begin the roleplay
​
success
boolean
required

Indicates if the room was created successfully

Example:

true

​
data
object
required