Reconnect a session

POST

sessions

{id}

reconnect

curl --request POST \
  --url https://api.facemode.io/api/sessions/{id}/reconnect \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{}'

{
  "room": {
    "type": "livekit",
    "url": "<string>",
    "token": "<string>",
    "name": "<string>"
  },
  "egressType": "livekit",
  "roomUrl": "<string>",
  "roomToken": "<string>",
  "inputProvider": "deepgram",
  "ingestion": {
    "ready": true,
    "authority": "websocket",
    "url": "wss://worker.example.com/ws/6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "wsToken": "<string>",
    "headers": {}
  },
  "workerStatus": "PENDING",
  "workerAssignment": {
    "version": 123,
    "provider": "<string>",
    "targetType": "<string>",
    "tier": "<string>",
    "jobId": "<string>",
    "workerId": "<string>",
    "endpointKind": "<string>",
    "websocketBase": "<string>",
    "selectedAt": "2023-11-07T05:31:56Z",
    "assignedAt": "2023-11-07T05:31:56Z",
    "generation": 123,
    "terminationRequestedAt": "2023-11-07T05:31:56Z",
    "terminationReason": "<string>",
    "failure": {
      "code": "<string>",
      "message": "<string>"
    }
  }
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

Call this when the ingestion WebSocket drops or its wsToken expires. The session must be ACTIVE (SESSION_NOT_ACTIVE otherwise). The response has the same ingestion block as create - connect with the new wsToken, which invalidates the previous one.

curl -X POST https://api.facemode.io/api/sessions/6ba7b810-9dad-11d1-80b4-00c04fd430c8/reconnect \
  -H "x-api-key: fm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Body rules:

{} (or no body) refreshes the credential for the existing room binding. roomUrl/roomToken in the response are then null.
room retargets the egress with fresh credentials - room.type must equal the session’s egressType (ROOM_TYPE_MISMATCH).
inputProvider, when present, must equal the session’s stored provider (INPUT_PROVIDER_MISMATCH).
Only room and inputProvider are accepted; other fields return REQUEST_FIELD_UNKNOWN.

Authorizations

x-api-key

string

header

required

FaceMode API key (fm_...).

Path Parameters

string<uuid>

required

Session ID (UUID).

Body

application/json

room

object

Optional new room. type must match the session's egressType.

Hide child attributes

room.type

enum<string>

required

Room provider.

Available options:

livekit,

daily

room.url

string

required

Room URL. For LiveKit this is the WebSocket URL (wss://...); for Daily, the room URL (https://...daily.co/...).

room.token

string

required

Access token granting the worker permission to join and publish.

room.name

string

Optional room name. For LiveKit, when omitted the name is decoded from the token's video.room claim.

inputProvider

enum<string> | null

Optional. When present it must equal the session's stored provider.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

Response

Reconnect credentials minted. Use ingestion.url and ingestion.wsToken to open a new WebSocket.

room

object

Egress room the avatar joins and publishes video into.

Hide child attributes

room.type

enum<string>

required

Room provider.

Available options:

livekit,

daily

room.url

string

required

Room URL. For LiveKit this is the WebSocket URL (wss://...); for Daily, the room URL (https://...daily.co/...).

room.token

string

required

Access token granting the worker permission to join and publish.

room.name

string

Optional room name. For LiveKit, when omitted the name is decoded from the token's video.room claim.

egressType

enum<string>

Available options:

livekit,

daily

roomUrl

string | null

Echo of the new room URL, or null when no room was supplied.

roomToken

string | null

Echo of the new room token, or null when no room was supplied.

inputProvider

enum<string> | null

Upstream speech provider producing the audio streamed into the session. Used for provider-specific handling; custom or omitted means canonical PCM streaming.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

ingestion

object

Audio ingestion endpoint for the session. url and wsToken are present only when ready is true.

Hide child attributes

ingestion.ready

boolean

True when the session can accept a WebSocket connection.

ingestion.authority

enum<string>

Ingestion channel; always websocket.

Available options:

websocket

ingestion.url

string

WebSocket URL in the form wss://<host>/ws/{session_id}.

Example:

"wss://worker.example.com/ws/6ba7b810-9dad-11d1-80b4-00c04fd430c8"

ingestion.wsToken

string

Short-lived (15 minute), single-use credential. Pass it as the facemode.<wsToken> WebSocket subprotocol, or as the token query parameter.

ingestion.headers

object | null

Optional extra headers required by the ingestion endpoint, when applicable.

Hide child attributes

ingestion.headers.{key}

string

workerStatus

enum<string> | null

Media worker lifecycle: PENDING/ASSIGNING mean capacity is still being allocated, ASSIGNED/ACTIVE mean a worker owns the session, ENDING means cleanup is in flight, ENDED/FAILED are terminal.

Available options:

PENDING,

ASSIGNING,

ASSIGNED,

ACTIVE,

ENDING,

ENDED,

FAILED

workerAssignment

object | null

Worker placement metadata for the session. Treat as opaque - fields may change. Useful for correlating jobId with support tickets.

Hide child attributes

workerAssignment.version

integer

workerAssignment.provider

string | null

Compute provider identifier.

workerAssignment.targetType

string | null

workerAssignment.tier

string | null

Capacity tier selected for the session.

workerAssignment.jobId

string | null

workerAssignment.workerId

string | null

workerAssignment.endpointKind

string | null

workerAssignment.websocketBase

string | null

Base WebSocket URL the ingestion.url is derived from.

workerAssignment.selectedAt

string<date-time> | null

workerAssignment.assignedAt

string<date-time> | null

workerAssignment.generation

integer | null

Ownership generation, incremented on each fenced reconnect.

workerAssignment.terminationRequestedAt

string<date-time> | null

workerAssignment.terminationReason

string | null

Why the session is ending, for example user_requested, worker_requested, no_audio_timeout, beta_max_duration, legacy_inactive. Null until termination is requested.

workerAssignment.failure

object | null

Hide child attributes

workerAssignment.failure.code

string

workerAssignment.failure.message

string

API Reference

Sessions

Avatars

API Keys

Reconnect a session

Authorizations

Path Parameters

Body

Response