Create a session

curl --request POST \
  --url https://api.example.com/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "avatar_id": "<string>",
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud",
    "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
'

import requests

url = "https://api.example.com/v1/sessions"

payload = {
    "avatar_id": "<string>",
    "transport": {
        "audio_source": "data_stream",
        "room_name": "demo-room",
        "type": "livekit",
        "url": "wss://my-app.livekit.cloud",
        "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    avatar_id: '<string>',
    transport: {
      audio_source: 'data_stream',
      room_name: 'demo-room',
      type: 'livekit',
      url: 'wss://my-app.livekit.cloud',
      worker_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  })
};

fetch('https://api.example.com/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "avatar_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "idle_timeout_seconds": 123,
  "max_duration_seconds": 123,
  "metadata": {},
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud"
  },
  "billing_surface": "api",
  "ended_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "failure": {
    "code": "<string>",
    "message": "<string>"
  },
  "first_frame_at": "2023-11-07T05:31:56Z",
  "object": "session",
  "started_at": "2023-11-07T05:31:56Z",
  "usage": {
    "billable_seconds": 1,
    "frames": 1
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

Create a session

curl --request POST \
  --url https://api.example.com/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "avatar_id": "<string>",
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud",
    "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
'

import requests

url = "https://api.example.com/v1/sessions"

payload = {
    "avatar_id": "<string>",
    "transport": {
        "audio_source": "data_stream",
        "room_name": "demo-room",
        "type": "livekit",
        "url": "wss://my-app.livekit.cloud",
        "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    avatar_id: '<string>',
    transport: {
      audio_source: 'data_stream',
      room_name: 'demo-room',
      type: 'livekit',
      url: 'wss://my-app.livekit.cloud',
      worker_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  })
};

fetch('https://api.example.com/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "avatar_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "idle_timeout_seconds": 123,
  "max_duration_seconds": 123,
  "metadata": {},
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud"
  },
  "billing_surface": "api",
  "ended_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "failure": {
    "code": "<string>",
    "message": "<string>"
  },
  "first_frame_at": "2023-11-07T05:31:56Z",
  "object": "session",
  "started_at": "2023-11-07T05:31:56Z",
  "usage": {
    "billable_seconds": 1,
    "frames": 1
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Live API key minted in the dashboard. Pass as Authorization: Bearer sk_live_…. Keys are scoped to a single environment (staging / prod).

Headers

X-Protoface-Session-Grant

string | null

Idempotency-Key

string | null

Required string length: 1 - 255

Body

application/json

Request body for POST /v1/sessions.

avatar_id

string

required

Stable av_… avatar id. Must reference a platform stock avatar or customer avatar the caller's API key can access.

transport

LiveKitTransportConfig · object

required

Discriminated union of transport configs, keyed by type.

LiveKitTransportConfig
WebSocketTransportConfig
PipecatTransportConfig

Show child attributes

Example:

{
  "audio_source": "data_stream",
  "room_name": "demo-room",
  "type": "livekit",
  "url": "wss://my-app.livekit.cloud",
  "worker_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

idle_timeout_seconds

integer

default:30

End the session automatically after this many seconds without received audio. Only applies to transports that observe inbound audio; ignored otherwise.

Required range: 1 <= x <= 600

max_duration_seconds

integer | null

Optional customer-requested hard ceiling on session duration. The API clamps this to the caller's plan limit and returns the effective value on the Session resource.

Required range: 1 <= x <= 3600

metadata

object

Customer-owned free-form JSON, <= 8 KB. Keys prefixed with _avatar. are managed by Protoface.

Show child attributes

quality

enum<string>

default:standard

Quality tier; drives the billing multiplier.

Available options:

mock,

lite,

standard,

pro

Response

Successful Response

Public session resource — what GET /v1/sessions/{id} returns.

avatar_id

string

required

created_at

string<date-time>

required

string

required

sess_… prefixed ULID.

idle_timeout_seconds

integer

required

max_duration_seconds

integer

required

metadata

object

required

Show child attributes

quality

enum<string>

required

Output quality tier.

Available options:

mock,

lite,

standard,

pro

status

enum<string>

required

Public session lifecycle.

Terminal states are ended, failed, canceled. ending is the graceful-drain state while a worker finishes publishing in-flight frames.

Available options:

created,

queued,

starting,

running,

ending,

ended,

failed,

canceled

transport

LiveKitTransportConfig · object

required

BYO LiveKit transport.

The customer owns the room and mints worker_token; we never touch their LiveKit API key or secret.

LiveKitTransportConfig
WebSocketTransportConfig
PipecatTransportConfig

Show child attributes

Example:

{
  "audio_source": "data_stream",
  "room_name": "demo-room",
  "type": "livekit",
  "url": "wss://my-app.livekit.cloud"
}

billing_surface

enum<string>

default:api

Service that created the session. Use this to group usage reporting.

Available options:

api,

playground,

embed,

share,

public_demo,

pipecat,

video_generation

ended_at

string<date-time> | null

failed_at

string<date-time> | null

failure

SessionFailure · object | null

Populated when Session.status == failed.

Show child attributes

first_frame_at

string<date-time> | null

Set on session.first_frame.

object

string

default:session

Allowed value: "session"

started_at

string<date-time> | null

Set when worker emits session.starting.

usage

SessionUsage · object

Live usage counters embedded in the Session resource.

Eventually-consistent — lags the latest worker heartbeat by up to one interval. Canonical billing data lives in UsageEvent.

Show child attributes

List sessions Retrieve a session