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)

Agent message fields

mini-apps or SDKs usually only need to consume data.message inside message.add / message.partial:

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":"再按地区拆分"}'

Recommended mini-app / Agent integration flow

1. Generate a connId; if you need concurrency-safe resume or polling, also generate a taskId.
2. Open GET /api/ai/events?connId=<uuid> first, and wait for state.ready or a short timeout.
3. Call POST /api/ai/message with type=newTask, the same connId, task text, optional taskId, images, autoApprovalSettings, and chatSettings: { "mode": "act" }.
4. Read progress from SSE message.partial / message.add; treat notification.type=error as task failure.
5. If you receive message.type=ask with message.ask=upload_file_to_sandbox, upload the file first, then send the upload result JSON back with type=askResponse, askResponse=messageResponse, the same taskId, and the same connId.
6. After message.ask=completion_result or message.say=completion_result, read generated reports, charts, PDFs, Word files, and other artifacts through the task file endpoints.

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

• GET /api/ai_task/cancelTask?taskId=task-001 (taskId as a Query parameter; some older clients may also use POST /api/ai/message with type=cancelTask)

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"

# Upload to a task sandbox so the Agent can continue reading it
curl -X POST "https://app.infinisynapse.cn/api/ai/upload?taskId=task-001" \
  -H "Authorization: Bearer <your API Key>" \
  -F "file=@./attachment.pdf"

# Upload to a specific subdirectory in the task workspace
curl -X POST "https://app.infinisynapse.cn/api/tools/taskUpload/task-001?subdir=upload_documents&naming=original" \
  -H "Authorization: Bearer <your API Key>" \
  -F "file=@./report-source.docx"

7. File Storage and Download

Generic file storage uses the /api/storage prefix; task workspace downloads use /api/tools/storage in the current Server API.

curl "https://app.infinisynapse.cn/api/tools/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. If the Agent requests local file upload: POST /api/ai/upload?taskId= or POST /api/tools/taskUpload/:taskId, then send the upload result back with POST /api/ai/message (type=askResponse).
5. Multi-turn follow-up: POST /api/ai/message (type=askResponse).
6. Cancel a task: GET /api/ai_task/cancelTask?taskId=.
7. View results: GET /api/ai_task/getTaskWorkspace/:id to list the artifacts, POST /api/ai_task/previewFile to preview, and GET /api/tools/storage/downloadTaskFile/:taskId?path= to download.

10. API Scenarios and Compositions from Production mini-apps

Real mini-apps should not expose the API Key in the browser. The recommended pattern is to implement your own server-side business route: keep the API Key on the server, assemble prompts there, proxy uploads, and read task artifacts. The frontend only talks to your own business route.

10.1 Common Agent Task Skeleton

Use this for any long-running Agent application, including Gaokao assistants, shopping comparison, and report writing.

1. The frontend calls your server route; the server generates a connId and, when resume or polling matters, also pre-generates a taskId.
2. The server opens GET /api/ai/events?connId=<uuid> first and starts consuming SSE.
3. The server calls POST /api/ai/message with type=newTask, the same connId, task text, optional taskId, autoApprovalSettings, and chatSettings: { "mode": "act" }.
4. Use SSE message.partial / message.add to advance state; transform message.text into progress, conclusions, or structured frontend results.
5. When message.ask=upload_file_to_sandbox, upload the file first, then send the upload result back to the Agent with POST /api/ai/message (type=askResponse).
6. After message.ask=completion_result or message.say=completion_result, read messages, workspace files, or downloads according to the task type.
7. When the user stops the run, call GET /api/ai_task/cancelTask?taskId= and mark the business task state in your own database.

10.2 Gaokao Assistants: Form Input + Optional Files + PDF Result

Gaokao school/major consulting apps are centered on "one form submission generates a structured report." These apps usually do not need the browser extension.

10.3 Shopping Comparison Assistant: Chrome Extension + Realtime Agent + Message Result

Shopping apps need the Agent to see the product page, search page, or multiple e-commerce pages the user is browsing. Usually check whether the Chrome extension is online before starting the task.

10.4 Report Writer: Batch Document Upload + Knowledge/Data Resources + Workspace Artifacts

Report-writing apps do not just need a text answer. They let the Agent continuously create Markdown, charts, PDFs, Word files, and other artifacts in the task workspace.

10.5 Composition Principles

• Connect SSE before sending the task: the most reliable long-task order is to establish /api/ai/events first, then call /api/ai/message, so early state is not missed.
• Keep credentials and state server-side: API Key, taskId, file paths, share state, and business user ID should stay on your server. The frontend should only receive business results.
• Separate the two upload modes: /api/ai/upload?taskId= responds to Agent sandbox upload requests; /api/tools/taskUpload/:taskId is better when the app proactively archives source material into the task workspace.
• Prefer the workspace for deliverables: SSE messages are enough for text-only display; use getTaskWorkspace, previewFile, and downloadTaskFile when you need download, preview, versioning, or export.
• Enable resources before the task: databases and knowledge bases should be listed and enabled before newTask, otherwise the Agent may not see the expected resources.
• Design recovery from the beginning: mini-apps should persist taskId, connId, user input, uploaded file mappings, and last status; after refresh, recover with getUiMessageById and getTaskWorkspace.