ChatLab API Documentation

ChatLab provides a local RESTful API service that allows external tools, scripts, and MCP to query chat records, execute SQL queries, and import chat data via HTTP.

Quick Start

1. Enable the Service

Open ChatLab → Settings → ChatLab API → Enable Service.

Once enabled, an API Token is automatically generated. The default port is 3110.

2. Verify Service Status

bash

curl http://127.0.0.1:3110/api/v1/status \
  -H "Authorization: Bearer YOUR_TOKEN"

Response example:

json

{
  "success": true,
  "data": {
    "name": "ChatLab API",
    "version": "1.0.0",
    "uptime": 3600,
    "sessionCount": 5
  },
  "meta": {
    "timestamp": 1711468800,
    "version": "0.0.2"
  }
}

General Information

Item	Description
Base URL	`http://127.0.0.1:3110`
API Prefix	`/api/v1`
Authentication	Bearer Token
Data Format	JSON
Bind Address	`127.0.0.1` (localhost only)

Authentication

All requests must include the Authorization header:

Authorization: Bearer clb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The Token can be viewed and regenerated in Settings → ChatLab API.

Unified Response Format

Success response:

json

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": 1711468800,
    "version": "0.0.2"
  }
}

Error response:

json

{
  "success": false,
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session not found: abc123"
  }
}

Endpoint List

System

Method	Path	Description
GET	`/api/v1/status`	Service status
GET	`/api/v1/schema`	ChatLab Format JSON Schema

Data Query (Export)

Method	Path	Description
GET	`/api/v1/sessions`	List all sessions
GET	`/api/v1/sessions/:id`	Get single session details
GET	`/api/v1/sessions/:id/messages`	Query messages (paginated)
GET	`/api/v1/sessions/:id/members`	Get member list
GET	`/api/v1/sessions/:id/stats/overview`	Get overview statistics
POST	`/api/v1/sessions/:id/sql`	Execute custom SQL (read-only)
GET	`/api/v1/sessions/:id/export`	Export ChatLab Format JSON

Data Import

Method	Path	Description
POST	`/api/v1/import`	Import chat records (new session)
POST	`/api/v1/sessions/:id/import`	Incremental import to existing session

Endpoint Details

GET /api/v1/status

Get the running status of the API service.

Response:

Field	Type	Description
`name`	string	Service name (`ChatLab API`)
`version`	string	ChatLab application version
`uptime`	number	Service uptime in seconds
`sessionCount`	number	Total number of sessions

GET /api/v1/schema

Get the JSON Schema definition for ChatLab Format, useful for building compliant import data.

GET /api/v1/sessions

Get all imported sessions.

Response example:

json

{
  "success": true,
  "data": [
    {
      "id": "session_abc123",
      "name": "Tech Discussion Group",
      "platform": "whatsapp",
      "type": "group",
      "messageCount": 58000,
      "memberCount": 120
    }
  ]
}

GET /api/v1/sessions/:id

Get detailed information for a single session.

Path parameters:

Parameter	Type	Description
`id`	string	Session ID

GET /api/v1/sessions/:id/messages

Query messages from a specific session with pagination and filtering support.

Query parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	100	Items per page (max 1000)
`startTime`	number	-	Start timestamp (Unix seconds)
`endTime`	number	-	End timestamp (Unix seconds)
`keyword`	string	-	Keyword search
`senderId`	string	-	Filter by sender's platformId
`type`	number	-	Filter by message type

Request example:

bash

curl "http://127.0.0.1:3110/api/v1/sessions/abc123/messages?page=1&limit=50&keyword=hello" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "success": true,
  "data": {
    "messages": [
      {
        "senderPlatformId": "123456",
        "senderName": "John",
        "timestamp": 1703001600,
        "type": 0,
        "content": "Hello!"
      }
    ],
    "total": 1500,
    "page": 1,
    "limit": 50,
    "totalPages": 30
  }
}

GET /api/v1/sessions/:id/members

Get all members of a specific session.

GET /api/v1/sessions/:id/stats/overview

Get overview statistics for a specific session.

Response:

json

{
  "success": true,
  "data": {
    "messageCount": 58000,
    "memberCount": 120,
    "timeRange": {
      "start": 1609459200,
      "end": 1703001600
    },
    "messageTypeDistribution": {
      "0": 45000,
      "1": 8000,
      "5": 3000,
      "80": 2000
    },
    "topMembers": [
      {
        "platformId": "123456",
        "name": "John",
        "messageCount": 5800,
        "percentage": 10.0
      }
    ]
  }
}

Field	Description
`messageCount`	Total message count
`memberCount`	Total member count
`timeRange`	Earliest/latest message timestamps (Unix seconds)
`messageTypeDistribution`	Count per message type (key is message type enum value)
`topMembers`	Top 10 active members (sorted by message count descending)

POST /api/v1/sessions/:id/sql

Execute a read-only SQL query against a specific session's database. Only SELECT statements are allowed.

Request body:

json

{
  "sql": "SELECT sender, COUNT(*) as count FROM messages GROUP BY sender ORDER BY count DESC LIMIT 10"
}

Response:

json

{
  "success": true,
  "data": {
    "columns": ["sender", "count"],
    "rows": [
      ["123456", 5800],
      ["789012", 3200]
    ]
  }
}

For database schema details, refer to ChatLab internal documentation or use SELECT * FROM sqlite_master WHERE type='table' to inspect the tables.

GET /api/v1/sessions/:id/export

Export complete session data in ChatLab Format JSON.

Limit: Maximum 100,000 messages per export. If the session exceeds this limit, a 400 EXPORT_TOO_LARGE error is returned. For larger sessions, use the paginated /messages API.

Response:

json

{
  "success": true,
  "data": {
    "chatlab": {
      "version": "0.0.2",
      "exportedAt": 1711468800,
      "generator": "ChatLab API"
    },
    "meta": {
      "name": "Tech Discussion Group",
      "platform": "whatsapp",
      "type": "group"
    },
    "members": [...],
    "messages": [...]
  }
}

POST /api/v1/import

Import chat records into ChatLab, creating a new session.

Supported Content-Types

Content-Type	Format	Use Case	Body Limit
`application/json`	ChatLab Format JSON	Small to medium data (quick testing, script integration)	50MB
`application/x-ndjson`	ChatLab JSONL format	Large-scale data (production integration)	Unlimited

JSON Mode Example

bash

curl -X POST http://127.0.0.1:3110/api/v1/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatlab": {
      "version": "0.0.2",
      "exportedAt": 1711468800
    },
    "meta": {
      "name": "Import Test",
      "platform": "qq",
      "type": "group"
    },
    "members": [
      { "platformId": "123", "accountName": "Test User" }
    ],
    "messages": [
      {
        "sender": "123",
        "accountName": "Test User",
        "timestamp": 1711468800,
        "type": 0,
        "content": "Hello World"
      }
    ]
  }'

JSONL Mode Example

bash

cat data.jsonl | curl -X POST http://127.0.0.1:3110/api/v1/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @-

Response:

json

{
  "success": true,
  "data": {
    "mode": "new",
    "sessionId": "session_xyz789"
  }
}

For the full ChatLab Format specification, see ChatLab Format Specification.

POST /api/v1/sessions/:id/import

Incrementally import chat records into an existing session. Duplicate messages are automatically skipped.

Deduplication rules:

The unique key for each message is timestamp + senderPlatformId + contentLength. If a message's timestamp, sender, and content length match an existing message exactly, it is considered a duplicate and skipped.

Path parameters:

Parameter	Type	Description
`id`	string	Target session ID

Content-Type and request body format are the same as POST /api/v1/import.

Response:

json

{
  "success": true,
  "data": {
    "mode": "incremental",
    "sessionId": "session_abc123",
    "newMessageCount": 150
  }
}

Concurrency & Limits

Limit	Value	Description
JSON body size	50MB	`application/json` mode
JSONL body size	Unlimited	`application/x-ndjson` streaming mode
Export message limit	100,000	`/export` endpoint
Max page size	1,000	`/messages` endpoint
Import concurrency	1	Only one import operation allowed at a time

Error Codes

Error Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing token
`SESSION_NOT_FOUND`	404	Session not found
`INVALID_FORMAT`	400	Request body does not conform to ChatLab Format
`SQL_READONLY_VIOLATION`	400	SQL is not a SELECT statement
`SQL_EXECUTION_ERROR`	400	SQL execution error
`EXPORT_TOO_LARGE`	400	Message count exceeds export limit (100K)
`BODY_TOO_LARGE`	413	Request body exceeds 50MB (JSON mode only)
`IMPORT_IN_PROGRESS`	409	Another import is already in progress
`IMPORT_FAILED`	500	Import failed
`SERVER_ERROR`	500	Internal server error

Security

Localhost only: API binds to 127.0.0.1, not exposed to the network
Token authentication: All endpoints require a valid Bearer Token
Read-only SQL: /sql endpoint only allows SELECT queries
Disabled by default: API service must be manually enabled

Use Cases

1. MCP Integration

Connect the ChatLab API to AI tools like ClaudeCode, enabling AI to directly query and analyze chat records.

2. Automation Scripts

Write scripts to periodically export chat records from other platforms, convert to ChatLab Format, and automatically import via the Push API.

3. Data Analysis

Use the SQL endpoint to run custom queries, combined with Python/R for advanced data analysis.

4. Data Backup

Periodically export important session data via the /export endpoint as JSON backups.

5. Scheduled Pulling

Configure external data source URLs in the Settings page. ChatLab will automatically fetch and import new data at the configured interval.

Version History

Version	Description
v1	Initial release — session query, message search, SQL, export, import (JSON + JSONL), Pull scheduler

ChatLab API Documentation ​

Quick Start ​

1. Enable the Service ​

2. Verify Service Status ​

General Information ​

Authentication ​

Unified Response Format ​

Endpoint List ​

System ​

Data Query (Export) ​

Data Import ​

Endpoint Details ​

GET /api/v1/status ​

GET /api/v1/schema ​

GET /api/v1/sessions ​

GET /api/v1/sessions/:id ​

GET /api/v1/sessions/:id/messages ​

GET /api/v1/sessions/:id/members ​

GET /api/v1/sessions/:id/stats/overview ​

POST /api/v1/sessions/:id/sql ​

GET /api/v1/sessions/:id/export ​

POST /api/v1/import ​

Supported Content-Types ​

JSON Mode Example ​

JSONL Mode Example ​

POST /api/v1/sessions/:id/import ​

Concurrency & Limits ​

Error Codes ​

Security ​

Use Cases ​

1. MCP Integration ​

2. Automation Scripts ​

3. Data Analysis ​

4. Data Backup ​

5. Scheduled Pulling ​

Version History ​

ChatLab API Documentation

Quick Start

1. Enable the Service

2. Verify Service Status

General Information

Authentication

Unified Response Format

Endpoint List

System

Data Query (Export)

Data Import

Endpoint Details

GET /api/v1/status

GET /api/v1/schema

GET /api/v1/sessions

GET /api/v1/sessions/:id

GET /api/v1/sessions/:id/messages

GET /api/v1/sessions/:id/members

GET /api/v1/sessions/:id/stats/overview

POST /api/v1/sessions/:id/sql

GET /api/v1/sessions/:id/export

POST /api/v1/import

Supported Content-Types

JSON Mode Example

JSONL Mode Example

POST /api/v1/sessions/:id/import

Concurrency & Limits

Error Codes

Security

Use Cases

1. MCP Integration

2. Automation Scripts

3. Data Analysis

4. Data Backup

5. Scheduled Pulling

Version History