InfiniSynapse Server API Reference

This document is the HTTP API reference for the InfiniSynapse Server, intended for external users/SDKs. With a single API Key (Bearer Token) you can directly invoke it to run multi-turn AI task conversations, manage data sources, manage RAG knowledge bases, upload and download files, and more—without relying on any frontend UI.

If you only need command-line integration, refer to the "InfiniSynapse CLI API Reference" first; this document targets developers who need to issue HTTP requests directly.

1. Getting Started

Basic Information

Users in Mainland China should use the .cn domain, and overseas users should use the .com domain; for on-premises deployments, replace it with your own service address. The examples below consistently use the .cn domain; for overseas environments, simply replace it with .com.

Authentication

All business endpoints require a Bearer Token in the request header:

Authorization: Bearer <your API Key>

The server parses the user identity (userId) from the Token's sub claim, and all resources (tasks, data sources, knowledge bases, files) are isolated per user. A few endpoints marked "public read-only" require no authentication.

Language

The optional request header x-lang controls the language of the prompt text returned by the server. Possible values: zh_CN (default), en, ar, ja, ko, ru.

x-lang: zh_CN

Unified Response Structure

Most endpoints return a unified envelope:

{
  "code": 200,
  "message": "success",
  "data": { }
}

• code === 200 indicates success, and the business data is in data.
• code of 1101 / 1105: the Token has expired or is invalid, and the API Key needs to be replaced.
• Parameter validation failures return HTTP 422, with message being the first validation error message.
• File download endpoints return a binary stream directly (application/octet-stream or application/zip) and do not use this envelope.

Pagination Conventions

List endpoints (inheriting from the common pagination parameters) support the following Query parameters:

The data structure of a paginated response:

{
  "items": [ ],
  "meta": {
    "itemCount": 10,
    "totalItems": 42,
    "itemsPerPage": 10,
    "totalPages": 5,
    "currentPage": 1
  }
}

Quick Start Example

curl -X GET "https://app.infinisynapse.cn/api/ai_database/list?page=1&pageSize=10&source=all" \
  -H "Authorization: Bearer <your API Key>" \
  -H "x-lang: zh_CN"

2. AI Conversation and Task Execution

AI conversation uses an asynchronous "SSE long connection + message delivery" model: first subscribe to the event stream to receive real-time pushes, then send instructions via the message endpoint.

2.1 Subscribe to the Event Stream (SSE)

• GET /api/ai/events
• Establishes a Server-Sent Events long connection; the server actively pushes message changes, state-ready signals, notifications, and more.

Query parameters

Request headers: Authorization: Bearer <token> is required; Accept: text/event-stream is recommended.

Event types (each formatted as event: <event>\ndata: <JSON>\n\n)

curl -N "https://app.infinisynapse.cn/api/ai/events?connId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <your API Key>" \
  -H "Accept: text/event-stream"

2.2 Send a Message

• POST /api/ai/message
• Dispatches to different logic based on the body's type. Replies are pushed in real time to the SSE channel; this endpoint itself only returns the execution result.

Common type values and fields

Response

• Success is usually { "success": true };
• newTask, rollback, editing the first message, etc. include { success: true, state, forceReplace? };
• Failure may be { success: false, error } or { success: false, notification: { type, title, message } } (e.g. when billing validation fails).

# Create a new task
curl -X POST "https://app.infinisynapse.cn/api/ai/message" \
  -H "Authorization: Bearer <your API Key>" \
  -H "Content-Type: application/json" \
  -d '{"type":"newTask","text":"分析最近一个月的销售趋势","connId":"550e8400-..."}'

# Multi-turn follow-up
curl -X POST "https://app.infinisynapse.cn/api/ai/message" \
  -H "Authorization: Bearer <your API Key>" \
  -H "Content-Type: application/json" \
  -d '{"type":"askResponse","taskId":"task-001","askResponse":"messageResponse","text":"再按地区拆分"}'

2.3 Other Conversation Helper Endpoints

3. Task Management

Controller prefix: /api/ai_task.

3.1 Task Queries

3.2 Task Operations

Delete Tasks

• POST /api/ai_task/deleteTaskWithId

{ "ids": ["task-001", "task-002"] }

Cancel a Task

• POST /api/ai_task/cancelTask?taskId=task-001 (taskId as a Query parameter)

Rerun a SQL Task

• POST /api/ai_task/rerunSqlTask

{ "id": "task-001", "chat_index": 0 }

Run Extracted SQL

• POST /api/ai_task/runExtractSql

{
  "variables": { "startDate": "2024-01-01", "endDate": "2024-12-31" },
  "register_tables": "orders,users",
  "databases": "main_db",
  "sqls": "SELECT * FROM orders WHERE created_at BETWEEN :startDate AND :endDate"
}

3.3 Tasks and RAG

3.4 Task Categories

3.5 Task Files

3.6 Task Sharing (public read-only, no authentication required)

4. Data Source Management

Controller prefix: /api/ai_database. Supported database types: mysql, postgres, sqlite, sqlserver, clickhouse, snowflake, doris, starrocks, gbase, kingbase, dm, supabase, deltalake, file (connection testing also supports mongodb, elasticsearch).

4.1 List Query

• GET /api/ai_database/list

Query parameters: pagination parameters + the following optional items

4.2 Create, Update, Delete

Example add request body:

{
  "name": "production_db",
  "type": "mysql",
  "config": "{\"mysql_host\":\"127.0.0.1\",\"mysql_port\":3306,\"mysql_username\":\"root\",\"mysql_password\":\"***\",\"mysql_database\":\"sales\"}",
  "enabled": 1,
  "description": "生产环境数据库",
  "nickname": "销售数据源"
}

Note: the database name must not start with remote_ or subscribe_.

4.3 Connection Testing and Queries

4.4 File and Knowledge Base Binding

5. RAG Knowledge Base Management

Controller prefix: /api/ai_rag_sdk.

5.1 Queries

5.2 Create, Update, Delete

Example create request body:

{
  "name": "sales_kb",
  "nickname": "销售知识库",
  "description": "销售相关文档",
  "ragDocFilterRelevance": "0.5",
  "requiredExts": [".pdf", ".docx", ".txt"],
  "docDir": "/path/to/docs",
  "enabled": 1,
  "database_ids": ["uuid-1", "uuid-2"]
}

5.3 Database Binding

5.4 File Operations (supports file / oss / s3)

Example fileTree request body (remote OSS):

{
  "file_system": "oss",
  "directory": "/docs",
  "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
  "access_key_id": "***",
  "access_key_secret": "***",
  "filter": "both"
}

6. File Upload

The upload-related endpoints are registered under the root path (i.e. /api/...). Except for task uploads, ordinary uploads are organized by "directory".

curl -X POST "https://app.infinisynapse.cn/api/upload/my-folder" \
  -H "Authorization: Bearer <your API Key>" \
  -F "file=@./data.csv"

7. File Storage and Download

Controller prefix: /api/storage.

curl "https://app.infinisynapse.cn/api/storage/downloadTaskFile/task-001?path=data%2Fresult.csv" \
  -H "Authorization: Bearer <your API Key>" \
  -o result.csv

8. Error Handling

9. Typical Call Flow

1. Establish an SSE connection: GET /api/ai/events?connId=<uuid>.
2. Prepare resources: GET /api/ai_database/list, GET /api/ai_rag_sdk, and enable as needed via POST /api/ai_database/enabled, POST /api/ai_rag_sdk/enabled.
3. Create a new task: POST /api/ai/message (type=newTask), and receive real-time replies from SSE.
4. Multi-turn follow-up: POST /api/ai/message (type=askResponse).
5. View results: GET /api/ai_task/getTaskWorkspace/:id to list the artifacts, POST /api/ai_task/previewFile to preview, and GET /api/storage/downloadTaskFile/:taskId?path= to download.