Skip to content
OnCoreDocs
Calls

POSThttps://core-api.heysadie.ai/calls/{id}/monitor-session

id actorLabel url token expiresAt agentIdentity monitorIdentity success error code message details field metadata timestamp version path reason retryAfterSeconds

Create calls monitor session

Try it in the API Explorer

Example request

Terminal
curl -X POST "https://core-api.heysadie.ai/calls/CALL_ID/monitor-session" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actorLabel": "string"
  }'

Authentication

Authenticate with an API key in the Authorization header using the ApiKey scheme. See Authentication for how keys work and where to get them.

Authorizationstringrequired

API key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.

X-Tenant-Idstring (uuid)optional

Required when authenticating with an organization key: it selects the tenant the request acts on. Omit with tenant keys.

Request

Path parameters

idstringrequired

The resource's UUID.

Body application/json · required

actorLabelstringoptional

Opaque label naming whoever you hold responsible for this session. Recorded verbatim in the audit trail and never interpreted: we cannot authenticate a person behind an API key.

Responses

200
idstringrequired

`calls.id`, echoing the path.

urlstringrequired

LiveKit project URL the browser SDK connects to.

tokenstringrequired

Short-lived, subscribe-only LiveKit access token scoped to this call's room. Publishing is denied until you call takeover.

expiresAtstringrequired

When the token stops being accepted at connect. LiveKit checks a token only at connect, so a monitor already in the room stays in it past this time.

agentIdentitystringrequired

The agent's LiveKit participant identity, which the SDK keys the agent's audio and state off.

monitorIdentitystringrequired

The identity minted for this session. Pass it back to takeover and end.

400The request is invalid. `details` lists each field that failed
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 3 child properties
codeenumrequired

A parameter or body field broke a rule

Allowed values:"VALIDATION_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

detailsobject[]optional

One entry per field that failed

Show 2 item properties
fieldstringrequired

The offending field

messagestringrequired

The rule it broke

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

401Missing or invalid credentials
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

No valid credentials

Allowed values:"UNAUTHORIZED"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

403The credentials are valid but may not use this route
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

The credentials may not use this route

Allowed values:"FORBIDDEN"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

404
errorenumrequired
Allowed values:"not_found"
409
errorenumrequired
Allowed values:"conflict"
reasonenumrequired

`not_live`: the call has ended, or is older than the liveness bound (never retry. `agent_absent`: the call is live but no agent is in the room right now, usually because one is reconnecting) retry once or twice after a short delay. `not_monitorable`: no room name, no control secret, or not a phone call. `monitor_cap_reached`: the per-call cap is met. `session_closed`: the named session is closed or unknown. `held_by_other_monitor`: another session holds the call and its holder is still in the room. `transfer_in_progress`: the caller's leg is leaving the room: refused by the agent, not by this API.

Allowed values:"not_live""agent_absent""not_monitorable""monitor_cap_reached""session_closed""held_by_other_monitor""not_taken_over""transfer_in_progress"
429
errorenumrequired
Allowed values:"rate_limited"
retryAfterSecondsnumberrequired
500An unexpected server error
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An unexpected server failure

Allowed values:"INTERNAL_SERVER_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested