Start a session
Activates a practice session for a learner against a published scenario (or an
active deployment key). The session is created in active state; the response
carries the credentials needed to connect.
Chat mode returns conversationToken; voice mode returns a LiveKit
participantToken and room. Repeat calls with the same idempotencyKey
return the same active session with a fresh token.
curl --request POST \
--url https://dash.trainertwin.com/api/v1/sessions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"userId": "user_123"
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({userId: 'user_123'})
};
fetch('https://dash.trainertwin.com/api/v1/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://dash.trainertwin.com/api/v1/sessions"
payload = { "userId": "user_123" }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"session": {
"id": "session_123",
"agentSlug": "react-mock-interview",
"status": "assigned",
"mode": "chat",
"runtimeToken": "<string>"
},
"conversationToken": "<string>",
"participantToken": "<string>",
"room": "<string>"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}Authorizations
Organization API key generated in Dashboard → account menu → Developer API (dash.trainertwin.com/developer).
Body
deploymentKey or scenario is required; deploymentKey takes precedence.
"user_123"
^[a-zA-Z0-9][a-zA-Z0-9._-]*$"react-mock-interview"
Public key of an active deployment; takes precedence over scenario.
chat, voice Optional context document to attach to the session (an organization document or one uploaded by the learner).
Retry-safe key scoped to the deployment; reusing it returns the same active session instead of creating a new one.
curl --request POST \
--url https://dash.trainertwin.com/api/v1/sessions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"userId": "user_123"
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({userId: 'user_123'})
};
fetch('https://dash.trainertwin.com/api/v1/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://dash.trainertwin.com/api/v1/sessions"
payload = { "userId": "user_123" }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"session": {
"id": "session_123",
"agentSlug": "react-mock-interview",
"status": "assigned",
"mode": "chat",
"runtimeToken": "<string>"
},
"conversationToken": "<string>",
"participantToken": "<string>",
"room": "<string>"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}{
"error": "Resource not found"
}