github/ChatLab
1
0
Fork 0
mirror of https://github.com/hellodigua/ChatLab.git synced 2026-04-24 04:21:01 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
b8a3823cef31c0a01aa095b09c1f1d65e6935461
ChatLab/docs/en/chatlab-api.md
digua 3189de3a6e style: 代码格式优化
2026-04-06 22:24:49 +08:00

500 lines
13 KiB
Markdown
Raw Blame History

# 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 `5200`.
### 2. Verify Service Status
```bash
curl http://127.0.0.1:5200/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:5200` |
| 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": "wechat",
"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:5200/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](./chatlab-format.md#message-type-reference) 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](./chatlab-format.md) 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": "wechat",
"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:5200/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:5200/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](./chatlab-format.md).
---
### 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 Claude Desktop, 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 |
Reference in New Issue View Git Blame Copy Permalink