REST API

The Lane.Chat REST API is a small, JSON-over-HTTPS surface for identifying users, tracking events, and registering push tokens from your own backend or a native app. It's the same API the native SDKs use under the hood.

Lane.Chat is SaaS-only; every request targets the official Lane.Chat cloud.

Base URL

https://api.lane.chat/api/v1

All requests are POST with a JSON body and Content-Type: application/json.

Authentication

There are two tiers:

• POST /sdk/sessions is public. You identify your app with its public app key (app_id, looks like app_1a2b…). Call this first — it returns a short-lived session token.

• Every other endpoint requires that session token as a bearer credential:

  Authorization: Bearer <session_token>

Session tokens are per-device and expire (see expires_at in the response). Call /sdk/sessions again to obtain a fresh one — reusing the same device_id / fingerprint_hash returns the same underlying visitor.

Response envelope

Every response is a JSON object with a numeric code (0 means success):

{ "code": 0, "message": "success", "data": { /* ... */ } }

Errors carry a non-zero code and a human-readable message:

{ "code": 422, "message": "fingerprint_hash must be 16 or 64 hex chars", "errors": [] }

Common codes: 422 (validation), 401 (missing or invalid session token), 404 (app_not_found), 429 (rate limited). See Error codes.

Rate limits

Per app, per hour:

Endpoint	Limit
/sdk/sessions	10,000 / hour
/sdk/events	100,000 / hour

See Rate limits for headers and backoff guidance.

Endpoints

Start a session

POST /sdk/sessions — public. Creates (or reuses) a visitor for a device and returns a session token.

Field	Type	Required	Notes
app_id	string	yes	Your public app key (app_…)
fingerprint_hash	string	yes	16- or 64-hex device hash (canonical: SHA-256)
device_id	string	no	Stable device id (IDFV / ANDROID_ID). Derived from the hash if omitted
platform	string	no	ios, android, web, or unknown
sdk_version	string	no	Free-form, ≤ 40 chars
app_version	string	no	Free-form, ≤ 40 chars
os_version	string	no	Free-form, ≤ 40 chars

curl -X POST https://api.lane.chat/api/v1/sdk/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_1a2b3c…",
    "fingerprint_hash": "e3b0c44298fc1c149afbf4c8996fb924…",
    "device_id": "A1B2-C3D4",
    "platform": "ios"
  }'

{
  "code": 0,
  "message": "success",
  "data": {
    "session_token": "eyJ0eXAiOiJKV1Qi…",
    "expires_at": "2026-07-30T17:17:55+08:00",
    "client_id": 999212,
    "device_id": "A1B2-C3D4"
  }
}

Identify a user

POST /sdk/identify — bearer. Attaches your own user id and traits to the session's visitor, so agents see who they're talking to and one person maps to one visitor across web and native.

Field	Type	Required	Notes
user_id	string	yes	Your stable user id, ≤ 128 chars
traits	object	no	Flat key/value map (email, name, plan…)

curl -X POST https://api.lane.chat/api/v1/sdk/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session_token>" \
  -d '{
    "user_id": "user-42",
    "traits": { "email": "[email protected]", "name": "Ada", "plan": "pro" }
  }'

{ "code": 0, "message": "success", "data": { "client_id": 999212, "external_user_id": "user-42" } }

Register a push token

POST /sdk/push/register — bearer. Stores an APNs/FCM token so Lane.Chat's servers can push agent replies to the device. Your signing key stays on the server; the client only forwards the device token.

Field	Type	Required	Notes
device_token	string	yes	APNs/FCM token, ≤ 255 chars
platform	string	yes	ios or android

curl -X POST https://api.lane.chat/api/v1/sdk/push/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session_token>" \
  -d '{ "device_token": "fMEP0…", "platform": "ios" }'

{ "code": 0, "message": "success", "data": { "token_id": 553, "client_id": 999212, "platform": "ios", "registered": true } }

Track an event

POST /sdk/events — bearer. Records a product event against the visitor. Useful for triggering flows and giving agents context.

Field	Type	Required	Notes
event_name	string	yes	≤ 80 chars
properties	object	no	Flat key/value map

curl -X POST https://api.lane.chat/api/v1/sdk/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session_token>" \
  -d '{ "event_name": "checkout_started", "properties": { "cart_total": 42.0 } }'

{ "code": 0, "message": "success", "data": { "event_id": 2, "event_name": "checkout_started", "accepted": true } }

Fingerprint hash

fingerprint_hash uniquely identifies a device install. The canonical form is a 64-character SHA-256 hex digest; a 16-character legacy hash is also accepted. Send the same hash across calls so the server reuses one visitor for the device.

Opening chat

The REST API handles identity, events, and push — it does not stream messages. To show the conversation, open the hosted chat page (or use a native SDK), passing the identity so web and native share one visitor:

https://cdn.lane.chat/widget.html?app_id=app_1a2b…&fp=<fingerprint_hash>&did=<device_id>&user_id=<user_id>

The hosted chat page and the SDKs handle the live conversation — message delivery, typing, and calls — for you.