REST API Reference

APIDocumentation

Complete REST API reference for Tenant and Agent integrations. All endpoints require JWT authentication.

2API Roles

27+Endpoints

JWTAuth Method

RESTProtocol

🔐 Authentication

Complete REST API reference for Tenant and Agent integrations. All endpoints require JWT authentication.

Base URL

https://connextlive.io

This is your Connextlive instance URL. All examples below use this as the host.

Authorization Header

Authorization: Bearer <your_jwt_token>

Include this header with every authenticated request.

POST/api/auth/login

Login — Get JWT Token

Authenticate with email and password. Returns a JWT token (valid 7 days) that must be sent as a Bearer token in all subsequent requests.

Request Body

emailstringrequiredUser email address

passwordstringrequiredPassword (min 6 characters)

curl -X POST https://connextlive.io/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "admin@company.com",
    "password": "yourpassword"
  }'

💬 Tenant — Conversations

Manage all conversations in your workspace. Requires CUSTOMER role.

GET/api/tenant/conversations

List Conversations

Returns paginated conversations with filtering by status/agent/search, unread counts, and per-agent stats.

Query Parameters

statusstringACTIVE | WAITING | CLOSED | all

agentIdstringFilter by agent ID (or "all")

searchstringSearch in message content and visitor ID

limitnumberItems per page (default: 50)

offsetnumberPagination offset (default: 0)

curl 'https://connextlive.io/api/tenant/conversations?status=ACTIVE&limit=20' \
  -H 'Authorization: Bearer <token>'

GET/api/tenant/conversations/:id

Get Conversation

Fetch full details of a specific conversation including visitor profile and workspace info.

curl 'https://connextlive.io/api/tenant/conversations/cnv_01HX' \
  -H 'Authorization: Bearer <token>'

POST/api/tenant/conversations/:id/resolve

Resolve Conversation

Mark a conversation as CLOSED. Triggers AI resolution analysis and topic tagging if your plan includes AI features.

curl -X POST 'https://connextlive.io/api/tenant/conversations/cnv_01HX/resolve' \
  -H 'Authorization: Bearer <token>'

PUT/api/tenant/conversations/:id/status

Update Conversation Status

Manually set the conversation status without triggering resolve-specific side effects (AI analysis, system messages).

Request Body

statusstringrequiredNew status: ACTIVE | WAITING | CLOSED

curl -X PUT 'https://connextlive.io/api/tenant/conversations/cnv_01HX/status' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"status": "WAITING"}'

POST/api/tenant/conversations/:id/assign

Assign Conversation to Agent

Assign or transfer a conversation to a specific agent. Triggers real-time socket events and push notifications.

Request Body

agentIdstringrequiredTarget agent user ID

curl -X POST 'https://connextlive.io/api/tenant/conversations/cnv_01HX/assign' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "usr_01HX..."}'

POST/api/tenant/conversations/:id/mark-read

Mark Conversation as Read

Mark all unread visitor messages in the conversation as seen, resetting the unread badge.

curl -X POST 'https://connextlive.io/api/tenant/conversations/cnv_01HX/mark-read' \
  -H 'Authorization: Bearer <token>'

DELETE/api/tenant/conversations/:id

Delete Conversation

Permanently delete a conversation and all its messages. This action is irreversible.

curl -X DELETE 'https://connextlive.io/api/tenant/conversations/cnv_01HX' \
  -H 'Authorization: Bearer <token>'

👥 Tenant — Visitors

Access and manage all visitors across your workspace sites.

GET/api/tenant/visitors

List Visitors

Paginated visitor list with search, online filter, site filter, and tag filter. Returns global stats (total, online, returning).

Query Parameters

searchstringSearch name, email, phone, IP, country, city

isOnlinebooleanFilter: true | false

siteIdstringFilter by site ID

tagsstring | string[]Filter by tag(s). Repeat param for multiple: ?tags=vip&tags=trial

pagenumberPage number (default: 1)

limitnumberPer page, max 100 (default: 25)

curl 'https://connextlive.io/api/tenant/visitors?search=jane&isOnline=true&limit=25' \
  -H 'Authorization: Bearer <token>'

GET/api/tenant/visitors/:id

Get Visitor

Full visitor profile with all metadata fields, tags, notes, and external IDs.

curl 'https://connextlive.io/api/tenant/visitors/vis_01HX' \
  -H 'Authorization: Bearer <token>'

PATCH/api/tenant/visitors/:id

Update Visitor

Update visitor metadata. All fields are optional — only provided fields are updated.

Request Body

userNamestringDisplay name

userEmailstringEmail address

userPhonestringPhone number

tagsstring[]Replaces the entire tags array

notesstringInternal notes (plain text)

curl -X PATCH 'https://connextlive.io/api/tenant/visitors/vis_01HX' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": ["vip", "enterprise"],
    "notes": "High priority account"
  }'

DELETE/api/tenant/visitors/:id

Delete Visitor

Permanently delete a visitor and all their associated data. Irreversible.

curl -X DELETE 'https://connextlive.io/api/tenant/visitors/vis_01HX' \
  -H 'Authorization: Bearer <token>'

🧑‍💼 Tenant — Agents

List active agents and pending invitations, invite new agents to your workspace.

GET/api/tenant/agents

List Agents

Returns all active agents (with CSAT scores) and pending email invitations in a single response.

curl 'https://connextlive.io/api/tenant/agents' \
  -H 'Authorization: Bearer <token>'

POST/api/tenant/agents

Invite Agent

Send an email invitation to a new agent. The invite link expires in 7 days.

Request Body

namestringrequiredAgent full name

emailstringrequiredAgent email address

curl -X POST 'https://connextlive.io/api/tenant/agents' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Bob Smith", "email": "bob@company.com"}'

⚙️ Tenant — Workspace

Read and update workspace configuration: name, language, timezone, notification and widget settings.

GET/api/tenant/workspace

Get Workspace

Retrieve full workspace configuration. Auto-creates a default workspace if none exists for the tenant.

curl 'https://connextlive.io/api/tenant/workspace' \
  -H 'Authorization: Bearer <token>'

PUT/api/tenant/workspace

Update Workspace

Update workspace fields. Only provided keys are updated; omitted keys remain unchanged.

Request Body

namestringWorkspace display name

companyNamestringCompany legal name

contactEmailstringSupport contact email

languagestringLanguage code: en | tr | de | es

timezonestringIANA timezone string e.g. UTC, Europe/Berlin

settingsobjectNotification and widget settings (merged, not replaced)

curl -X PUT 'https://connextlive.io/api/tenant/workspace' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Support",
    "language": "en",
    "timezone": "UTC",
    "settings": {
      "notifications": { "visitorSound": true, "agentSound": false }
    }
  }'

🔑 Tenant — API Keys

Manage widget API keys used to embed the Connextlive chat widget on external websites.

One-time secret

The plain API key is returned only once at creation. Store it securely — it cannot be retrieved again.

GET/api/tenant/api-keys

List API Keys

Returns all API keys. The plain key is never exposed — only SHA-256 hash and metadata are returned.

curl 'https://connextlive.io/api/tenant/api-keys' \
  -H 'Authorization: Bearer <token>'

POST/api/tenant/api-keys

Create API Key

Generate a new API key. The plainKey field is returned only once — store it immediately. Subsequent requests cannot recover it.

Request Body

namestringrequiredDescriptive name (max 100 chars)

domainsstring (JSON array)Allowed origin domains as JSON array string, e.g. "["company.com"]"

statusstringACTIVE | INACTIVE (default: ACTIVE)

curl -X POST 'https://connextlive.io/api/tenant/api-keys' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production Widget",
    "domains": "["company.com", "www.company.com"]",
    "status": "ACTIVE"
  }'

DELETE/api/tenant/api-keys/:id

Delete API Key

Permanently revoke an API key. Widgets embedding with this key will stop authenticating immediately.

curl -X DELETE 'https://connextlive.io/api/tenant/api-keys/key_01HX' \
  -H 'Authorization: Bearer <token>'

👤 Agent — Profile

Get the authenticated agent's own profile. All agent endpoints require AGENT role.

GET/api/agent/profile

Get Agent Profile

Returns the logged-in agent's full profile including tenant info and avatar URL (pre-signed if stored on S3).

curl 'https://connextlive.io/api/agent/profile' \
  -H 'Authorization: Bearer <agent_token>'

💬 Agent — Conversations

List, read, reply to, and manage conversations visible to the agent's tenant.

GET/api/agent/conversations

List Conversations

Returns conversations scoped to the agent's tenant. Includes global status counts (active/waiting/closed) and per-conversation unread badges.

Query Parameters

statusstringactive | waiting | closed — or comma-separated: active,waiting

searchstringSearch visitor name or email

limitnumber1–50 (default: 20)

offsetnumberPagination offset (default: 0)

curl 'https://connextlive.io/api/agent/conversations?status=active,waiting&limit=20' \
  -H 'Authorization: Bearer <agent_token>'

GET/api/agent/conversations/:id

Get Conversation

Detailed view of a single conversation. Validates the conversation belongs to the agent's tenant.

curl 'https://connextlive.io/api/agent/conversations/cnv_01HX' \
  -H 'Authorization: Bearer <agent_token>'

GET/api/agent/conversations/:id/messages

List Messages

Ordered (oldest-first) paginated message history. Includes file attachment URLs.

Query Parameters

pagenumberPage number (default: 1)

limitnumberMax 100 (default: 50)

curl 'https://connextlive.io/api/agent/conversations/cnv_01HX/messages?page=1' \
  -H 'Authorization: Bearer <agent_token>'

POST/api/agent/conversations/:id/messages

Send Message

Send a text message or file attachment. Automatically claims the conversation, sets status to ACTIVE, and sends offline-visitor email notification. Supports multipart/form-data for up to 5 files (10MB each).

Request Body

contentstringMessage text content

messageTypestringTEXT (default) — automatically set to FILE when attachments are present

attachmentsfile[]Multipart: up to 5 files, 10MB each (image/jpeg, image/png, image/webp, application/pdf, office docs, zip)

# Text message
curl -X POST 'https://connextlive.io/api/agent/conversations/cnv_01HX/messages' \
  -H 'Authorization: Bearer <agent_token>' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Hi! How can I help you today?"}'

# File attachment (multipart)
curl -X POST 'https://connextlive.io/api/agent/conversations/cnv_01HX/messages' \
  -H 'Authorization: Bearer <agent_token>' \
  -F 'content=Please see the attached guide' \
  -F 'attachments=@/path/to/guide.pdf'

POST/api/agent/conversations/:id/resolve

Resolve Conversation

Close the conversation. Creates a localized system message visible to the visitor. Triggers AI resolution analysis and topic tagging (plan-dependent).

curl -X POST 'https://connextlive.io/api/agent/conversations/cnv_01HX/resolve' \
  -H 'Authorization: Bearer <agent_token>'

POST/api/agent/conversations/:id/assign

Transfer Conversation

Transfer a conversation to another agent. Caller must be the currently assigned agent. Triggers push notification to the target agent.

Request Body

agentIdstringrequiredID of the target agent to assign

curl -X POST 'https://connextlive.io/api/agent/conversations/cnv_01HX/assign' \
  -H 'Authorization: Bearer <agent_token>' \
  -H 'Content-Type: application/json' \
  -d '{"agentId": "usr_target_agent_id"}'

POST/api/agent/conversations/:id/mark-read

Mark as Read

Mark all unread visitor messages in the conversation as seen by the agent.

curl -X POST 'https://connextlive.io/api/agent/conversations/cnv_01HX/mark-read' \
  -H 'Authorization: Bearer <agent_token>'

👥 Agent — Visitors

View visitors associated with the agent's tenant.

GET/api/agent/visitors

List Visitors

Paginated visitor list scoped to the agent's tenant. Supports name/email search and online filter.

Query Parameters

searchstringSearch by name or email

isOnlinebooleanFilter: true | false

pagenumberPage number (default: 1)

limitnumberPer page (default: 25)

curl 'https://connextlive.io/api/agent/visitors?isOnline=true' \
  -H 'Authorization: Bearer <agent_token>'

GET/api/agent/visitors/:id

Get Visitor

Full visitor profile accessible by the agent.

curl 'https://connextlive.io/api/agent/visitors/vis_01HX' \
  -H 'Authorization: Bearer <agent_token>'

⚠️ Error Reference

All error responses follow a consistent JSON structure with statusCode and statusMessage fields.

Status	Meaning	When it occurs
200	OK	Request succeeded
400	Bad Request	Missing or invalid request body / query params
401	Unauthorized	Token missing, expired, or invalid
403	Forbidden	Token valid but wrong role or wrong tenant ownership
404	Not Found	Resource does not exist or belongs to another tenant
405	Method Not Allowed	Wrong HTTP method for this endpoint
500	Internal Server Error	Unexpected server-side failure

Error Response Shape

{
  "statusCode": 401,
  "statusMessage": "Authorization token required",
  "data": null
}