Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

Sessions are the core resource in Titan. A session represents a WhatsApp account linked to your application. You create a session, start it to initiate the pairing process, and then keep it running to send and receive messages. Each session runs on a managed runner and reconnects automatically after disconnects.

​
Session object

​
name
string
Session identifier. Alphanumeric with dots, hyphens, and underscores (1–64 characters).
​
status
string
Current status: CONNECTING, CONNECTED, or DISCONNECTED.
​
statusReason
string
Reason for the current status. Possible values: SCAN_QR, AUTO_RECONNECT, FAILED, MANUAL_STOP, QR_TIMEOUT, LOGGED_OUT, TEMPORARY_BAN, STREAM_ERROR.
​
phoneNumber
string
Phone number of the linked WhatsApp account in E.164 format. Present after pairing.
​
pushName
string
Display name set by the WhatsApp user. Present after pairing.
​
businessName
string
Business name for WhatsApp Business accounts. Present after pairing.
​
platform
string
Platform type. smba for Business accounts, consumer for standard accounts.
​
lid
string
Linked Device ID of the authenticated account.
​
proxy
string
HTTP/HTTPS proxy URL configured for this session.
​
createdAt
string
ISO 8601 timestamp when the session was created.
​
updatedAt
string
ISO 8601 timestamp when the session was last updated.

​
Create a session

curl -X POST https://api.example.com/api/sessions \
  -H "Authorization: Bearer titan_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "start": true
  }'
POST /api/sessions Creates a new session. Pass "start": true to automatically start the session immediately after creation.
​
name
string
required
Session identifier. Must match ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$.
​
start
boolean
default:"false"
Whether to automatically start the session after creation.
​
proxy
string
HTTP/HTTPS or SOCKS5 proxy URL to route WhatsApp traffic through.
​
config
object
Custom session configuration as a JSON object.
{
  "data": {
    "name": "default",
    "status": "CONNECTING",
    "statusReason": "SCAN_QR",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
}

​
List sessions

curl https://api.example.com/api/sessions \
  -H "Authorization: Bearer titan_..."
GET /api/sessions Returns all sessions for your account. 
{
  "data": [
    {
      "name": "default",
      "status": "CONNECTED",
      "phoneNumber": "+5511999999999",
      "pushName": "My Bot",
      "platform": "smba",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

​
Get a session

curl https://api.example.com/api/sessions/default \
  -H "Authorization: Bearer titan_..."
GET /api/sessions/{session} Returns current status and account info for a single session.
​
session
string
required
Session name.
{
  "data": {
    "name": "default",
    "status": "CONNECTED",
    "statusReason": null,
    "phoneNumber": "+5511999999999",
    "pushName": "My Bot",
    "businessName": "Acme Corp",
    "platform": "smba",
    "lid": "12345678901234567890@lid",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T12:30:00Z"
  }
}

​
Start a session

curl -X POST https://api.example.com/api/sessions/default/start \
  -H "Authorization: Bearer titan_..."
POST /api/sessions/{session}/start Starts a stopped session and begins the connection process. If the session is not yet paired, it enters CONNECTING state and waits for a QR scan or pairing code.
​
session
string
required
Session name.
{
  "data": { "success": true, "message": "session started" }
}

​
Stop a session

curl -X POST https://api.example.com/api/sessions/default/stop \
  -H "Authorization: Bearer titan_..."
POST /api/sessions/{session}/stop Gracefully stops a running session. The session transitions to DISCONNECTED with reason MANUAL_STOP. Credentials are preserved and the session can be restarted.
​
session
string
required
Session name.
{
  "data": { "success": true, "message": "session stopped" }
}

​
Restart a session

curl -X POST https://api.example.com/api/sessions/default/restart \
  -H "Authorization: Bearer titan_..."
POST /api/sessions/{session}/restart Stops and immediately restarts a session. Useful when a session is stuck or experiencing connection issues.
​
session
string
required
Session name.
{
  "data": { "success": true, "message": "session restarting" }
}

​
Delete a session

curl -X DELETE https://api.example.com/api/sessions/default \
  -H "Authorization: Bearer titan_..."
DELETE /api/sessions/{session} Permanently deletes a session and removes all associated data. This does not log out the WhatsApp account — use the logout endpoint if you want to unlink the device.
​
session
string
required
Session name.
{
  "data": { "success": true, "message": "session deleted" }
}

​
Log out a session

curl -X POST https://api.example.com/api/sessions/default/logout \
  -H "Authorization: Bearer titan_..."
POST /api/sessions/{session}/logout Logs the WhatsApp account out of this linked device. This unlinks the session from the account on WhatsApp’s servers and clears the stored credentials. After logout, you need to re-pair the session with a QR code or pairing code to reconnect.
​
session
string
required
Session name.
{
  "data": { "success": true, "message": "session logged out" }
}