Skip to main content
POST
Create a new session

Authorizations

Authorization
string
header
required

Polymorfa organization key (titan_ prefix), project token (titan_pt_ prefix), or client token (titan_ct_ prefix), where the operation permits that audience.

Body

application/json
projectId
string
required

Project id the session belongs to. Required.

Minimum string length: 1
sessionId
string

Canonical per-org session identifier (1-64 alphanumeric chars, dots, hyphens, underscores). Caller-supplied or generated; returned in the response. This is the id used in all /api/sessions/{session}/* paths.

Minimum string length: 1
name
string

Optional human-friendly label for the session. Not an id.

Minimum string length: 1
start
boolean
connection
enum<string>

How the session connects to WhatsApp. 'linked_device' (default) pairs as a WhatsApp linked device; 'cloud_api' uses the Meta Cloud API and requires the cloudApi creds block. Immutable after create.

Available options:
linked_device,
cloud_api
testMode
boolean

Create a simulated testing number (behaves like a real session via the simulated universe). Defaults to false.

bartenderMode
enum<string>

Linked-device privacy mode. Defaults to 'magic'. 'magic' — Polymorfa holds the Signal session; full message visibility. 'passthrough' — Polymorfa holds noise creds only; neither messages nor app state are decryptable on Polymorfa's side. 'passthrough_plus' — the customer has uploaded AppStateSyncKeys for selected collections (contacts, labels, mute/archive, blocklist), so Polymorfa sees metadata mutations but never message content.

Available options:
magic,
passthrough,
passthrough_plus
cloudApi
object

Meta credentials. Required when connection='cloud_api'. Encrypted at rest before storage.

config
object

Response

Session created

success
enum<boolean>
required
Available options:
true
data
object
required