### Quick Start API Request

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

A basic cURL example demonstrating how to list AI databases with authentication and language headers.

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

--------------------------------

### Start and Verify Services

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Commands to start the Docker containers and verify their running status.

```bash
docker compose up -d --build
```

```bash
docker compose ps
```

--------------------------------

### Install Docker

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Commands to install Docker and configure user permissions on a Linux system.

```bash
curl -fsSL https://get.docker.com | sudo bash
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
```

--------------------------------

### Example AUTHING_SERVER_URL Configuration

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Example of the authentication server URL configuration using a specific server IP.

```text
AUTHING_SERVER_URL=http://192.168.1.10:3000/api
```

--------------------------------

### Skill Installation Request Body

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Example JSON payload for installing a skill from the market via the /api/ai_skill/install endpoint.

```json
{
  "skillId": "507f1f77bcf86cd799439011",
  "name": "market-research",
  "alias": "市场研究",
  "author": "InfiniSynapse",
  "version": "1.0.0",
  "intro": "市场调研与竞争分析流程",
  "tags": "[\"research\", \"report\"]"
}
```

--------------------------------

### POST /api/ai_skill/install

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Downloads a skill from the market and installs it into the current user's skill library.

```APIDOC
## POST /api/ai_skill/install

### Description
Downloads a skill from the market and installs it into the current user's skill library.

### Method
POST

### Endpoint
/api/ai_skill/install

### Parameters
#### Request Body
- **skillId** (string) - Required - Unique identifier of the skill
- **name** (string) - Required - Name of the skill
- **alias** (string) - Required - Display name of the skill
- **author** (string) - Required - Author of the skill
- **version** (string) - Required - Version of the skill
- **logo** (string) - Optional - URL or path to logo
- **intro** (string) - Optional - Introduction text
- **tags** (string) - Optional - JSON string of tags

### Request Example
{
  "skillId": "507f1f77bcf86cd799439011",
  "name": "market-research",
  "alias": "市场研究",
  "author": "InfiniSynapse",
  "version": "1.0.0",
  "intro": "市场调研与竞争分析流程",
  "tags": "[\"research\", \"report\"]"
}
```

--------------------------------

### Create Database Connection Request Body

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Example JSON payload for the POST /api/ai_database/add endpoint. Ensure the name does not start with 'remote_' or 'subscribe_'.

```json
{
  "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": "销售数据源"
}
```

--------------------------------

### POST /api/ai_skill/upload

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Uploads a local skill zip file and installs it as a user-level skill.

```APIDOC
## POST /api/ai_skill/upload

### Description
Uploads a local skill zip file and installs it as a user-level skill. The zip must contain a SKILL.md file.

### Method
POST

### Endpoint
/api/ai_skill/upload

### Parameters
#### Request Body
- **file** (binary) - Required - The skill zip file
- **name** (string) - Required - Name of the skill
- **alias** (string) - Required - Display name
- **author** (string) - Required - Author name
- **status** (string) - Required - Initial status (e.g., active)
- **version** (string) - Required - Version string
- **logo** (string) - Optional - Logo file
- **intro** (string) - Optional - Introduction
- **tags** (string) - Optional - Tags list
```

--------------------------------

### Node.js SSO Integration Example

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

A minimal Express implementation demonstrating the session creation, state validation, and token exchange flow.

```javascript
import { randomBytes } from 'node:crypto'
import express from 'express'

const PROXY_API = 'https://api.infinisynapse.cn/api'
const CLIENT_ID = process.env.INFINI_CLIENT_ID
const CLIENT_SECRET = process.env.INFINI_CLIENT_SECRET
const SELF_ORIGIN = 'https://example.com'   // 你的应用地址

const app = express()
const partnerHeaders = {
  'Content-Type': 'application/json',
  'X-Client-Id': CLIENT_ID,
  'X-Client-Secret': CLIENT_SECRET,
}

// 1. 用户点击登录：创建会话并重定向
app.get('/login', async (req, res) => {
  const state = randomBytes(16).toString('hex')
  req.session.oauthState = state   // 存入你的会话方案

  const resp = await fetch(`${PROXY_API}/auth/partner/sessions`, {
    method: 'POST',
    headers: partnerHeaders,
    body: JSON.stringify({
      returnUrl: `${SELF_ORIGIN}/auth/infini/callback`,
      state,
    }),
  })
  const json = await resp.json()
  if (json.code !== 200) return res.status(500).send(json.message)
  res.redirect(json.data.entryUrl)
})

// 2. 登录完成跳回：校验 state，用 code 换用户信息
app.get('/auth/infini/callback', async (req, res) => {
  const { code, state } = req.query
  if (!code || state !== req.session.oauthState) {
    return res.status(400).send('state 校验失败')
  }
  req.session.oauthState = undefined

  const resp = await fetch(`${PROXY_API}/auth/partner/token`, {
    method: 'POST',
    headers: partnerHeaders,
    body: JSON.stringify({ code, grant_type: 'authorization_code' }),
  })
  const json = await resp.json()
  if (json.code !== 200) return res.status(500).send(json.message)

  const infiniUser = json.data.user
  // 按 infiniUser.id 查找/创建你的本地用户，写入登录态
  req.session.userId = infiniUser.id
  res.redirect('/dashboard')
})
```

--------------------------------

### Get Available Models

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieve a list of available models based on the current configuration.

```bash
curl -X GET "https://app.infinisynapse.cn/api/ai/models" \
  -H "Authorization: Bearer <你的 API Key>"
```

--------------------------------

### GET /api/auth/partner/clients

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Lists all partner applications owned by the authenticated user.

```APIDOC
## GET /api/auth/partner/clients

### Description
Retrieves a list of applications registered by the user.

### Method
GET

### Endpoint
/api/auth/partner/clients
```

--------------------------------

### Upload Local Skill via cURL

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Example command to upload a local skill zip file using multipart/form-data. Requires a valid Bearer Token in the Authorization header.

```bash
curl -X POST "https://app.infinisynapse.cn/api/ai_skill/upload" \
  -H "Authorization: Bearer <你的 Token>" \
  -F "name=report-methodology" \
  -F "alias=报告方法论" \
  -F "author=Data Team" \
  -F "status=active" \
  -F "version=1.0.0" \
  -F 'tags=["report","methodology"]' \
  -F "file=@./report-methodology.zip"
```

--------------------------------

### GET /api/ai_database/list

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves a list of available AI databases.

```APIDOC
## GET /api/ai_database/list

### Description
Retrieves a list of available AI databases for use in tasks.

### Method
GET

### Endpoint
/api/ai_database/list
```

--------------------------------

### Update AI Settings via cURL

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Examples for updating user defaults, task-specific models, and approval settings.

```bash
# 1) 更新用户默认模型与自定义说明（不带 taskId）
curl -X POST "https://app.infinisynapse.cn/api/ai/settings" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiConfiguration": {
      "apiProvider": "openai",
      "openAiBaseUrl": "https://api.openai.com/v1",
      "openAiApiKey": "<your-openai-key>",
      "openAiModelId": "gpt-4o"
    },
    "customInstructionsSetting": "你是一个数据分析助手，回答简洁并给出可执行建议"
  }'

# 2) 仅为指定任务切换模型（同时也会更新用户默认 apiConfiguration）
curl -X POST "https://app.infinisynapse.cn/api/ai/settings" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "task-001",
    "apiConfiguration": {
      "apiProvider": "infinisynapse",
      "infinisynapseModelId": "infini-analyst"
    }
  }'

# 3) 只更新自动审批 / 能力开关
curl -X POST "https://app.infinisynapse.cn/api/ai/settings" \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "autoApprovalSettings": {
      "maxRequests": 1000,
      "enableWebSearch": true,
      "enableBrowser": false,
      "databaseReturnLimit": 200
    }
  }'
```

--------------------------------

### GET /skill/public/getSkillList

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves a list of publicly available skills from the market.

```APIDOC
## GET /skill/public/getSkillList

### Description
Retrieves a list of publicly available skills from the market.

### Method
GET

### Endpoint
/skill/public/getSkillList

### Parameters
#### Query Parameters
- **pageNum** (number) - Optional - Page number for pagination
- **pageSize** (number) - Optional - Number of items per page
- **alias** (string) - Optional - Filter by skill alias
- **tag** (string) - Optional - Filter by skill tag
- **status** (string) - Optional - Filter by skill status
```

--------------------------------

### Session Token Response Structure

Source: https://infinisynapse.cn/zh/docs/WeChat%20Mini%20Program%20Phone%20Account%20Binding%20Guide

Example JSON response returned to the frontend after initial login.

```json
{ "token": "...", "bound": false, "needBindPhone": true, "account": null }
```

--------------------------------

### Execute Task on Behalf of User

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Example request to initiate a task using the user-specific API Key obtained during the code exchange process.

```http
POST https://app.infinisynapse.cn/api/ai/message
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "type": "newTask",
  "taskId": "c3a2f9d0-你生成的UUID-用于幂等",
  "text": "分析最近 7 天的销售数据，输出图表报告",
  "images": []
}
```

--------------------------------

### GET /api/ai/models

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Fetches a list of available models based on the current OpenAI-compatible configuration.

```APIDOC
## GET /api/ai/models

### Description
Requests OpenAI-compatible models based on the user's configured Base URL and API Key. Returns an array of model ID strings.

### Method
GET

### Endpoint
/api/ai/models

### Response
#### Success Response (200)
- **models** (array) - List of available model IDs.

### Response Example
["gpt-4o", "gpt-4o-mini"]
```

--------------------------------

### GET /api/auth/partner/costs

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Provides a client-level usage summary, ranking all sub-accounts under the partner.

```APIDOC
## GET /api/auth/partner/costs

### Description
Provides a client-level usage summary, ranking all sub-accounts under the partner.

### Method
GET

### Endpoint
/api/auth/partner/costs
```

--------------------------------

### GET {console}/user/profile

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20CLI%20API%20Reference

Validates the API Key and retrieves the user ID during the CLI initialization process.

```APIDOC
## GET {console}/user/profile

### Description
Validates the API Key and retrieves the user ID during the CLI initialization process.

### Method
GET

### Endpoint
{console}/user/profile

### Request Headers
- **Authorization** (string) - Required - Bearer <api-key>

### Response
#### Success Response (200)
- **code** (integer) - Status code
- **message** (string) - Response message
- **data** (object) - Contains userId

#### Response Example
{
  "code": 200,
  "message": "success",
  "data": { "userId": "user_123" }
}
```

--------------------------------

### GET /api/ai_rag_sdk

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves a paginated list of knowledge bases based on provided filters.

```APIDOC
## GET /api/ai_rag_sdk

### Description
Retrieves a paginated list of knowledge bases.

### Method
GET

### Endpoint
/api/ai_rag_sdk

### Parameters
#### Query Parameters
- **keyword** (string) - Optional - Filter by name
- **enabled** (boolean) - Optional - Filter by enabled status
- **source** (string) - Optional - Filter by source
- **subscribeSource** (string) - Optional - Filter by subscription source
```

--------------------------------

### GET /api/ai/events

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Vibe%20Coding%20Guide

Establishes an SSE connection to receive AI task events and updates.

```APIDOC
## GET /api/ai/events

### Description
Subscribes to an event stream for AI task updates. The client must generate a unique connId.

### Method
GET

### Endpoint
/api/ai/events

### Parameters
#### Query Parameters
- **connId** (string) - Required - A unique identifier (e.g., UUID) for the connection.

### Response
#### Success Response (200)
- **text/event-stream** - Streams events like message.add, message.partial, state.ready, notification, and heartbeat.
```

--------------------------------

### Create RAG Knowledge Base Request Body

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Example JSON payload for creating a new knowledge base via the /api/ai_rag_sdk/create endpoint.

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

--------------------------------

### Prepare Data Directories and Environment File

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Create necessary data directories and initialize the .env configuration file.

```bash
mkdir -p __data/mysql __data/mongo __data/redis
mkdir -p datas persist auto-coder upload tasks
cp .env.example .env
```

--------------------------------

### Create Task with Pre-uploaded File via Bash

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Demonstrates the end-to-end process of uploading a file to a workspace, establishing an SSE connection, and initiating a new task with the file reference.

```bash
API_KEY='<你的 API Key>'
TASK_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
CONN_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
INPUT_FILE='./report-source.pdf'
MIME_TYPE='application/pdf'

# 1) 主动预上传；业务数据位于统一响应的 data 中
UPLOAD_RESPONSE="$(
  curl -fsS -X POST \
    "https://app.infinisynapse.cn/api/tools/taskUpload/${TASK_ID}?subdir=upload_documents&naming=original" \
    -H "Authorization: Bearer ${API_KEY}" \
    -F "file=@${INPUT_FILE}"
)"
UPLOAD_DATA="$(printf '%s' "${UPLOAD_RESPONSE}" | jq -ce '.data // .')"
FILE_NAME="$(printf '%s' "${UPLOAD_DATA}" | jq -er '.name')"
FILE_SIZE="$(printf '%s' "${UPLOAD_DATA}" | jq -er '.size')"
LOGICAL_PATH="$(printf '%s' "${UPLOAD_DATA}" | jq -er '.logicalPath')"
ASSET_ID="$(printf '%s' "${UPLOAD_DATA}" | jq -er '.assetId')"

# 2) newTask 前先建立 SSE。生产代码应等待 state.ready；示例使用短暂超时
SSE_LOG="${TMPDIR:-/tmp}/infinisynapse-${TASK_ID}.sse"
curl -NsS \
  "https://app.infinisynapse.cn/api/ai/events?connId=${CONN_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: text/event-stream" >"${SSE_LOG}" &
SSE_PID=$!
sleep 1

# 3) type 是原文件 MIME；fileType=reference 表示参考文档，结构化数据请用 data
NEW_TASK_BODY="$(
  jq -n \
    --arg taskId "${TASK_ID}" \
    --arg connId "${CONN_ID}" \
    --arg name "${FILE_NAME}" \
    --argjson size "${FILE_SIZE}" \
    --arg mimeType "${MIME_TYPE}" \
    --arg logicalPath "${LOGICAL_PATH}" \
    --arg assetId "${ASSET_ID}" \
    '{
      type: "newTask",
      taskId: $taskId,
      connId: $connId,
      text: "读取随任务附带的 PDF，并提炼关键结论",
      images: [],
      files: [{
        name: $name,
        size: $size,
        type: $mimeType,
        logicalPath: $logicalPath,
        fileType: "reference",
        assetId: $assetId
      }],
      chatSettings: { mode: "act" }
    }'
)"
curl -fsS -X POST "https://app.infinisynapse.cn/api/ai/message" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${NEW_TASK_BODY}"

# 实时查看 SSE；任务完成后按 Ctrl-C，再执行 kill "${SSE_PID}"（若连接仍在）
tail -f "${SSE_LOG}"
```

--------------------------------

### GET /api/ai_task/cancelTask

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Cancels an ongoing task.

```APIDOC
## GET /api/ai_task/cancelTask

### Description
Cancels a task identified by the taskId.

### Method
GET

### Endpoint
/api/ai_task/cancelTask?taskId=
```

--------------------------------

### Troubleshooting and Resource Tuning

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Commands for restarting specific services and tuning memory parameters for InfiniSQL.

```bash
docker compose up -d infini-synapse
```

```text
INFINI_SQL_SPARK_DRIVER_MEMORY=6g
INFINI_SQL_MEM_LIMIT=8g
INFINI_SQL_MEMSWAP_LIMIT=10g
```

```bash
docker compose up -d infini-sql
```

--------------------------------

### GET /api/auth/partner/users

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Lists all sub-accounts associated with the partner.

```APIDOC
## GET /api/auth/partner/users

### Description
Retrieves a paginated list of all sub-accounts under the partner account.

### Method
GET

### Endpoint
/api/auth/partner/users

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1).
- **pageSize** (integer) - Optional - Items per page (default: 50, max: 100).
- **status** (string) - Optional - Filter by status (active/disabled).
```

--------------------------------

### GET /api/ai/ping

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Performs a lightweight connectivity and authentication check.

```APIDOC
## GET /api/ai/ping

### Description
Lightweight probe to verify if the connection and authentication are active.

### Method
GET

### Endpoint
/api/ai/ping

### Response
#### Success Response (200)
- **ok** (boolean) - Status of the connection.

### Response Example
{
  "ok": true
}
```

--------------------------------

### GET /api/ai/events

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

建立 Server-Sent Events (SSE) 长连接，用于接收服务端主动推送的消息变更、状态就绪及全局通知。

```APIDOC
## GET /api/ai/events

### Description
建立 Server-Sent Events 长连接，服务端主动推送消息变更、状态就绪、通知等。

### Method
GET

### Endpoint
/api/ai/events

### Parameters
#### Query Parameters
- **connId** (string) - Optional - 客户端生成的连接 ID；多 Tab/多连接时各用一个，便于服务端定向推送。不传则服务端自动生成

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

--------------------------------

### Initialize Administrator Account

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Scripts to initialize the system administrator account with default or custom credentials.

```bash
bash deploy/init-admin.sh
```

```bash
ADMIN_USERNAME='your_admin' ADMIN_PASSWORD='YourStrongPassword' bash deploy/init-admin.sh
```

--------------------------------

### GET /api/auth/partner/users/{externalUserId}

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Queries the status of a specific sub-account.

```APIDOC
## GET /api/auth/partner/users/{externalUserId}

### Description
Queries the status of a specific sub-account.

### Method
GET

### Endpoint
/api/auth/partner/users/{externalUserId}

### Parameters
#### Path Parameters
- **externalUserId** (string) - Required - The unique identifier of the user in the partner system.
```

--------------------------------

### Clone Deployment Repository

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Download the deployment files from the official repository.

```bash
git clone https://github.com/chaozwn/infini_docker.git
cd infini_docker
```

--------------------------------

### GET /api/tools/storage/downloadTaskFile/{taskId}

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20CLI%20API%20Reference

Downloads a file from the task workspace.

```APIDOC
## GET /api/tools/storage/downloadTaskFile/{taskId}

### Description
Downloads a file from the task workspace.

### Method
GET

### Endpoint
/api/tools/storage/downloadTaskFile/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task

#### Query Parameters
- **path** (string) - Required - The filename to download
```

--------------------------------

### Project Integration Rules Template

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Existing%20Product%20Integration%20Playbook

A template for defining project-specific rules to ensure consistent and secure InfiniSynapse integration.

```text
本项目依赖 InfiniSynapse。涉及 Server API、SSE、workspace、RAG、Browser Use、
文件上传下载、私有化部署或任务分享时，先阅读
vendor/InfinisynapseAssistant/AGENTS.md，再读取对应 skill 和中文 SaaS 文档。
除非文档中有明确 endpoint，否则不要编造 API。
API Key 只允许保存在服务端，前端只调用本项目后端。
```

--------------------------------

### POST /api/ai_rag_sdk/create

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Creates a new knowledge base with the specified configuration.

```APIDOC
## POST /api/ai_rag_sdk/create

### Description
Creates a new knowledge base.

### Method
POST

### Endpoint
/api/ai_rag_sdk/create

### Request Body
- **name** (string) - Required - Internal name
- **nickname** (string) - Required - Display name
- **description** (string) - Optional - Description
- **ragDocFilterRelevance** (string) - Optional - Relevance threshold
- **requiredExts** (array) - Optional - Allowed file extensions
- **docDir** (string) - Optional - Document directory path
- **enabled** (integer) - Optional - Enabled status
- **database_ids** (array) - Optional - Associated database IDs

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

--------------------------------

### GET /api/ai_task/list

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20CLI%20API%20Reference

Retrieves a paginated list of AI tasks.

```APIDOC
## GET /api/ai_task/list

### Description
Retrieves a paginated list of AI tasks.

### Method
GET

### Endpoint
/api/ai_task/list

### Query Parameters
- **page** (integer) - Required - Page number
- **pageSize** (integer) - Required - Items per page
- **field** (string) - Required - Sorting field (e.g., 'updated_at')
- **order** (string) - Required - Sort order ('desc' or 'asc')
- **task_name** (string) - Optional - Filter by task name
```

--------------------------------

### Implement Partner Workflow in Node.js

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

A complete workflow demonstrating sub-account provisioning, file uploading, and task creation using Node.js 20+. Ensure environment variables INFINI_CLIENT_ID and INFINI_CLIENT_SECRET are set before execution.

```javascript
const { randomUUID } = require('node:crypto')
const { readFile } = require('node:fs/promises')
const { basename } = require('node:path')

const PROXY_API = 'https://api.infinisynapse.cn/api'
const APP_API = 'https://app.infinisynapse.cn/api'
const partnerHeaders = {
  'Content-Type': 'application/json',
  'X-Client-Id': process.env.INFINI_CLIENT_ID,
  'X-Client-Secret': process.env.INFINI_CLIENT_SECRET,
}

async function callPartner(path, options = {}) {
  const resp = await fetch(`${PROXY_API}${path}`, { headers: partnerHeaders, ...options })
  const json = await resp.json()
  if (json.code !== 200) throw new Error(`${path} 失败: ${json.message}`)
  return json.data
}

// 1. 首次用到某用户时：开通子账号并缓存 apiKey（幂等，可安全重试）
async function ensureInfiniAccount(user) {
  const data = await callPartner('/auth/partner/users/provision', {
    method: 'POST',
    body: JSON.stringify({
      externalUserId: user.id,
      profile: { nickname: user.nickname, email: user.email },
    }),
  })
  // 把 data.infiniUserId / data.apiKey 存入你的用户表
  return data
}

// 2. 把首条消息要使用的文件预上传到同一个 taskId
async function uploadTaskFile(apiKey, taskId, { path, type, fileType = 'reference' }) {
  const form = new FormData()
  form.append('file', new Blob([await readFile(path)], { type }), basename(path))

  const resp = await fetch(
    `${APP_API}/tools/taskUpload/${taskId}?subdir=upload_documents&naming=original`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${apiKey}` },
      body: form,
    },
  )
  const json = await resp.json()
  if (!resp.ok || json.code !== 200) {
    throw new Error(`taskUpload 失败: ${json.message || resp.statusText}`)
  }

  const uploaded = json.data
  return {
    name: uploaded.name,
    size: uploaded.size,
    type, // taskUpload 不返回 MIME，由调用方保留
    logicalPath: uploaded.logicalPath,
    fileType,
    ...(uploaded.assetId ? { assetId: uploaded.assetId } : {}),
  }
}

// 3. 代用户发起分析任务（消耗从主账号余额扣除）
async function createTask(apiKey, { taskId, connId, text, files = [] }) {
  const resp = await fetch(`${APP_API}/ai/message`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      type: 'newTask',
      taskId,
      connId,
      text,
      images: [],
      files,
    }),
  })
  return resp.json()
}

async function main() {
  const { apiKey } = await ensureInfiniAccount({ id: 'your-user-123', nickname: '小明' })
  const taskId = randomUUID()
  const connId = randomUUID()
  const sourceFile = await uploadTaskFile(apiKey, taskId, {
    path: './sales-report.pdf',
    type: 'application/pdf',
    fileType: 'reference',
  })

  // 此处应先建立 GET `${APP_API}/ai/events?connId=${connId}` 并开始消费 SSE
  await createTask(apiKey, {
    taskId,
    connId,
    text: '读取附件并分析最近 7 天的销售数据，输出图表报告',
    files: [sourceFile],
  })
}

main().catch(error => {
  console.error(error)
  process.exitCode = 1
})
```

--------------------------------

### GET /api/auth/partner/users

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Lists sub-accounts associated with the partner in a paginated format.

```APIDOC
## GET /api/auth/partner/users

### Description
Lists sub-accounts associated with the partner in a paginated format.

### Method
GET

### Endpoint
/api/auth/partner/users
```

--------------------------------

### Configure Environment Variables

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Private%20Deployment%20Guide

Essential configuration settings for database credentials, JWT secrets, and authentication server URLs.

```text
# 数据库与缓存密码（生产强烈建议修改）
DB_PASSWORD=infinisynapse@123
REDIS_PASSWORD=ChangeMeRedisPassword!
MONGO_PASSWORD=infinisynapse2025
# URI 编码后的 Mongo 密码；不含 @ : / ? # & = 等特殊字符时与 MONGO_PASSWORD 填同一个值即可
MONGO_PASSWORD_URIENC=infinisynapse2025

# JWT 密钥（必改，长度 ≥ 32）
JWT_SECRET=ChangeMeJwtSecretAtLeast32Chars

# 鉴权地址（必改！见下方说明）
AUTHING_SERVER_URL=http://<服务器IP或域名>:3000/api
```

--------------------------------

### GET /api/auth/partner/users/{externalUserId}

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Retrieves the status and details of a specific sub-account.

```APIDOC
## GET /api/auth/partner/users/{externalUserId}

### Description
Fetches the current status and metadata for a sub-account.

### Method
GET

### Endpoint
/api/auth/partner/users/{externalUserId}

### Parameters
#### Path Parameters
- **externalUserId** (string) - Required - The user ID to query.
```

--------------------------------

### Create Partner Application via API

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Use this cURL command to programmatically register a new partner application using an existing login token.

```bash
curl -X POST https://api.infinisynapse.cn/api/auth/partner/clients \
  -H "Authorization: Bearer <你的登录Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的应用",
    "allowedReturnDomains": ["example.com"],
    "webhookUrl": "https://example.com/webhook/infini"
  }'
```

--------------------------------

### GET /api/miniapp/profile

Source: https://infinisynapse.cn/zh/docs/WeChat%20Mini%20Program%20Phone%20Account%20Binding%20Guide

Retrieves the current user's profile information.

```APIDOC
## GET /api/miniapp/profile

### Description
Retrieves the current user's profile information, with the phone number masked.

### Method
GET

### Endpoint
/api/miniapp/profile

### Response
#### Success Response (200)
- **profile** (object) - User profile data including masked phone number.
```

--------------------------------

### GET /api/ai/configuration

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves the current user's saved API configuration.

```APIDOC
## GET /api/ai/configuration

### Description
Returns the current user's saved API configuration, including the provider, Base URL, API Key, and model information.

### Method
GET

### Endpoint
/api/ai/configuration

### Response
#### Success Response (200)
- **apiConfiguration** (object) - The current API configuration settings.

### Response Example
{
  "apiConfiguration": {
    "apiProvider": "openai",
    "openAiBaseUrl": "https://api.openai.com/v1",
    "openAiModelId": "gpt-4o"
  }
}
```

--------------------------------

### Create Login Session

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Initiate a login session by sending a POST request to the InfiniSynapse API from your server.

```http
POST /api/auth/partner/sessions
X-Client-Id: partner_xxxxxxxx
X-Client-Secret: psk_xxxxxxxx
Content-Type: application/json
```

--------------------------------

### 任务管理命令速查

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Vibe%20Coding%20Guide

用于创建、查询、追问及管理任务生命周期的常用命令。

```bash
agent_infini task new "分析用户增长趋势"          # 新建任务（SSE 流式输出）
agent_infini task ask <taskId> "改成柱状图展示"    # 在同一任务里多轮追问
agent_infini task ls [--page N] [--search Q]      # 任务列表
agent_infini task show <taskId>                   # 任务详情
agent_infini task context                         # 查看已启用的数据库与 RAG
agent_infini task cancel <taskId>                 # 取消运行中的任务
agent_infini task rm <id1> [id2 ...]              # 批量删除任务
agent_infini task file <taskId>                   # 列出工作区文件
agent_infini task preview <taskId> <fileName>     # 预览文件内容
agent_infini task download <taskId> <fileName> [-o dir]  # 下载文件到本地
```

--------------------------------

### POST /api/auth/partner/clients

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Creates a new partner application to obtain credentials for SSO integration.

```APIDOC
## POST /api/auth/partner/clients

### Description
Creates a new partner application for SSO integration. Requires a valid user login token in the Authorization header.

### Method
POST

### Endpoint
https://api.infinisynapse.cn/api/auth/partner/clients

### Request Body
- **name** (string) - Required - The name of the application.
- **allowedReturnDomains** (array) - Required - A list of allowed domains or IP addresses for redirection.
- **webhookUrl** (string) - Optional - A HTTPS URL for receiving notifications upon login completion.

### Request Example
{
  "name": "我的应用",
  "allowedReturnDomains": ["example.com"],
  "webhookUrl": "https://example.com/webhook/infini"
}

### Response
#### Success Response (200)
- **code** (integer) - Status code (200 for success)
- **message** (string) - Success message
- **data** (object) - Contains the created application details including clientId and clientSecret
```

--------------------------------

### GET /api/ai_database/list

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves a paginated list of database connections based on optional filters.

```APIDOC
## GET /api/ai_database/list

### Description
Retrieves a list of configured database connections.

### Method
GET

### Endpoint
/api/ai_database/list

### Parameters
#### Query Parameters
- **name** (string) - Optional - Database name (fuzzy match)
- **type** (string) - Optional - Database type
- **enabled** (number) - Optional - Enabled status: 1 or 0
- **source** (string) - Optional - Source: local, remote, subscribed, or all (default: all)
- **subscribeSource** (string) - Optional - Subscribe source: created, subscribed, or all (default: created)
```

--------------------------------

### POST /api/ai_database/add

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Creates a new database connection configuration.

```APIDOC
## POST /api/ai_database/add

### Description
Creates a new database connection.

### Method
POST

### Endpoint
/api/ai_database/add

### Request Body
- **name** (string) - Required - Database name
- **type** (string) - Required - Database type
- **config** (string) - Required - JSON string containing connection details
- **enabled** (number) - Optional - Enabled status
- **description** (string) - Optional - Database description
- **nickname** (string) - Optional - Database nickname

### Request Example
{
  "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": "销售数据源"
}
```

--------------------------------

### Integration Architecture Flow

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Existing%20Product%20Integration%20Playbook

Recommended architectural flow for integrating InfiniSynapse via a backend adapter layer.

```text
Frontend -> Product API -> AgentTaskService / InfiniSynapseAdapter -> InfiniSynapse Server API
                         -> Product DB / Queue / Artifact Store
```

--------------------------------

### GET /api/ai/state

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves the full frontend state for a specific task or the global state.

```APIDOC
## GET /api/ai/state

### Description
Returns the current state of a task or global configuration, including messages, settings, and todo items.

### Method
GET

### Endpoint
https://app.infinisynapse.cn/api/ai/state

### Parameters
#### Query Parameters
- **taskId** (string) - Optional - The task ID. If omitted, returns global state.

### Response
#### Success Response (200)
- **apiConfiguration** (object) - Current API configuration.
- **customInstructions** (string) - System instructions.
- **infiniMessages** (array) - List of messages.
- **chatSettings** (object) - Current chat mode settings.
```

--------------------------------

### POST /api/auth/partner/clients

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Self-service creation of a new partner application.

```APIDOC
## POST /api/auth/partner/clients

### Description
Allows a user to create a new partner application.

### Method
POST

### Endpoint
/api/auth/partner/clients
```

--------------------------------

### POST /api/auth/partner/sessions

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Creates a new login session for the partner, returning an entry URL for the user to authenticate.

```APIDOC
## POST /api/auth/partner/sessions

### Description
Creates a login session to initiate the SSO flow.

### Method
POST

### Endpoint
/api/auth/partner/sessions

### Request Body
- **returnUrl** (string) - Required - The URL to redirect to after authentication.
- **state** (string) - Required - A random string for CSRF protection.
```

--------------------------------

### SSO Integration Workflow Diagram

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

A visual representation of the 5-step authentication flow between the application, InfiniSynapse, and the user browser.

```text
你的应用                    InfiniSynapse                     用户浏览器
   │                            │                                │
   │ ① 创建登录会话 ────────────▶│                                │
   │ ◀──────── 返回 entryUrl ───│                                │
   │                            │                                │
   │ ② 把用户重定向到 entryUrl ─────────────────────────────────▶│
   │                            │◀── ③ 用户在 app 域完成登录 ────│
   │                            │                                │
   │ ◀───────── ④ 浏览器带一次性 code 跳回你的 returnUrl ────────│
   │                            │                                │
   │ ⑤ 用 code 换取用户信息 ───▶│                                │
   │ ◀──────── 返回用户资料 ────│                                │
```

--------------------------------

### 使用 jq 处理 JSON 输出

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Vibe%20Coding%20Guide

通过管道将 CLI 的 JSON 输出传递给 jq 进行过滤处理。

```bash
agent_infini task ls | jq '.items[].task_name'
```

--------------------------------

### GET /api/auth/partner/users/{externalUserId}/costs

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Queries consumption details for a sub-account, optionally aggregated by task.

```APIDOC
## GET /api/auth/partner/users/{externalUserId}/costs

### Description
Queries consumption details for a sub-account, optionally aggregated by task.

### Method
GET

### Endpoint
/api/auth/partner/users/{externalUserId}/costs
```

--------------------------------

### GET /api/auth/partner/users/{externalUserId}/balance

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Queries the available balance of the main account for reconciliation purposes.

```APIDOC
## GET /api/auth/partner/users/{externalUserId}/balance

### Description
Queries the available balance of the main account for reconciliation purposes.

### Method
GET

### Endpoint
/api/auth/partner/users/{externalUserId}/balance
```

--------------------------------

### POST /api/auth/partner/sessions

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Initiates a login session for the user. This request must be performed server-side to protect the client secret.

```APIDOC
## POST /api/auth/partner/sessions

### Description
Initiates a login session for the user. This request must be performed server-side to protect the client secret.

### Method
POST

### Endpoint
/api/auth/partner/sessions

### Parameters
#### Request Body
- **returnUrl** (string) - Required - The full URL to redirect to after successful login. Must be in the allowlist.
- **cancelUrl** (string) - Optional - The URL to redirect to if the user cancels the login.
- **state** (string) - Optional - A random string used for CSRF protection, returned in the callback.
- **externalUserId** (string) - Optional - The user ID in your system for account binding.
- **metadata** (object) - Optional - Arbitrary JSON object returned in the callback.

### Response
#### Success Response (200)
- **sessionId** (string) - The unique ID for the session.
- **entryUrl** (string) - The URL to redirect the user to for login.
- **expiresIn** (integer) - Session expiration time in seconds.
```

--------------------------------

### Retrieve API Configuration

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Fetch the current user's saved API configuration.

```bash
curl -X GET "https://app.infinisynapse.cn/api/ai/configuration" \
  -H "Authorization: Bearer <你的 API Key>"
```

```json
{
  "apiConfiguration": {
    "apiProvider": "openai",
    "openAiBaseUrl": "https://api.openai.com/v1",
    "openAiModelId": "gpt-4o"
  }
}
```

--------------------------------

### GET /api/auth/partner/sessions/{sessionId}

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20SSO%20Integration%20Guide

Polls the status of a specific session, including user information once authenticated.

```APIDOC
## GET /api/auth/partner/sessions/{sessionId}

### Description
Polls the session status to retrieve user information.

### Method
GET

### Endpoint
/api/auth/partner/sessions/{sessionId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to query.
```

--------------------------------

### GET /api/auth/partner/users/{externalUserId}/balance

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Partner%20Silent%20Provisioning%20Guide

Queries the shared balance of the partner's main account.

```APIDOC
## GET /api/auth/partner/users/{externalUserId}/balance

### Description
Returns the current available balance of the partner's main account, which is shared across all sub-accounts.

### Method
GET

### Endpoint
/api/auth/partner/users/{externalUserId}/balance

### Parameters
#### Path Parameters
- **externalUserId** (string) - Required - The user ID to query balance for.
```

--------------------------------

### 数据库与 RAG 知识库管理

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Vibe%20Coding%20Guide

用于列出、启用或禁用数据库连接及 RAG 知识库的命令。

```bash
agent_infini db ls [--name N] [--type T] [--enabled] [--disabled]
agent_infini db enable <id> [id...]
agent_infini db disable <id> [id...]

agent_infini rag ls [--keyword K] [--enabled] [--disabled]
agent_infini rag enable <id> [id...]
agent_infini rag disable <id> [id...]
```

--------------------------------

### GET /api/ai_task/getTaskWorkspace/:id

Source: https://infinisynapse.cn/zh/docs/InfiniSynapse%20Server%20API%20Reference

Retrieves the list of files and artifacts generated within a task's workspace.

```APIDOC
## GET /api/ai_task/getTaskWorkspace/:id

### Description
Lists all files and artifacts currently present in the specified task's workspace.

### Method
GET

### Endpoint
/api/ai_task/getTaskWorkspace/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The task ID.
```