API 参考¶

InnoClaw 提供了一组由 Next.js API 路由提供的 REST API 端点。所有端点都位于 /api/ 路径下。

工作空间¶

获取工作空间列表¶

GET /api/workspaces

返回所有工作空间。

响应：

[
  {
    "id": "workspace-uuid",
    "name": "my-project",
    "rootPath": "/data/research/my-project",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
]

创建工作空间¶

POST /api/workspaces

请求体：

{
  "path": "/data/research/my-project"
}

删除工作空间¶

DELETE /api/workspaces/[workspaceId]

从数据库中删除工作空间记录。磁盘上的文件不会被删除。

文件¶

浏览目录¶

GET /api/files/browse?workspaceId={id}&path={relativePath}

返回工作空间内目录的文件列表。

读取文件¶

GET /api/files/read?workspaceId={id}&path={relativePath}

返回文件的内容。

写入文件¶

POST /api/files/write

请求体：

{
  "workspaceId": "workspace-uuid",
  "path": "relative/path/to/file.txt",
  "content": "file content here"
}

上传文件¶

POST /api/files/upload

接受包含 file、workspaceId 和 path 字段的 multipart/form-data。

删除文件¶

DELETE /api/files/delete

请求体：

{
  "workspaceId": "workspace-uuid",
  "path": "relative/path/to/file.txt"
}

重命名文件¶

POST /api/files/rename

请求体：

{
  "workspaceId": "workspace-uuid",
  "oldPath": "old/name.txt",
  "newPath": "new/name.txt"
}

创建目录¶

POST /api/files/mkdir

请求体：

{
  "workspaceId": "workspace-uuid",
  "path": "relative/path/to/new-dir"
}

对话¶

发送消息（流式）¶

POST /api/chat

Sends a message and receives a streaming AI response via RAG.

请求体：

{
  "messages": [
    { "role": "user", "content": "What is this project about?" }
  ],
  "workspaceId": "workspace-uuid"
}

响应： 包含 AI 响应令牌的 Server-Sent Events (SSE) 流。

Agent¶

Agent Chat (Streaming)¶

POST /api/agent

Sends a message to the autonomous AI agent with tool-calling capability.

请求体：

{
  "messages": [],
  "workspaceId": "workspace-uuid",
  "cwd": "/data/research/my-project",
  "skillId": "optional-skill-id",
  "paramValues": {},
  "mode": "agent"
}

Field	Type	Required	描述
`messages`	`UIMessage[]`	Yes	Chat message history
`workspaceId`	`string`	Yes	Workspace identifier
`cwd`	`string`	Yes	Current working directory for tool execution
`skillId`	`string`	No	Skill ID to use for this request
`paramValues`	`object`	No	Skill parameter values
`mode`	`string`	No	`"agent"`, `"plan"`, or `"ask"` (default: `"agent"`)

Response: Streaming response with tool calls and text.

Summarize Agent Conversation¶

POST /api/agent/summarize

Summarizes agent conversation history and optionally saves as a note.

请求体：

{
  "workspaceId": "workspace-uuid",
  "messages": [],
  "trigger": "clear",
  "preview": false,
  "locale": "en"
}

Field	Type	Required	描述
`workspaceId`	`string`	Yes	Workspace identifier
`messages`	`array`	Yes	Message array with parts and roles
`trigger`	`string`	No	`"clear"` or `"overflow"`
`preview`	`boolean`	No	If `true`, returns summary without saving
`locale`	`string`	No	`"en"` or `"zh"` (default: `"en"`)

备注¶

获取笔记列表¶

GET /api/notes?workspaceId={id}

创建笔记¶

POST /api/notes

请求体：

{
  "workspaceId": "workspace-uuid",
  "title": "My Note",
  "content": "Note content here"
}

更新笔记¶

PUT /api/notes/[noteId]

删除笔记¶

DELETE /api/notes/[noteId]

生成¶

生成笔记内容¶

POST /api/generate

请求体：

{
  "workspaceId": "workspace-uuid",
  "type": "summary"
}

Supported types: summary, faq, brief, timeline, memory, daily_report, weekly_report.

Daily Report¶

Generate Daily Report¶

POST /api/daily-report

Generates a daily activity report for a workspace.

请求体：

{
  "workspaceId": "workspace-uuid",
  "date": "2025-03-01",
  "locale": "en"
}

Field	Type	Required	描述
`workspaceId`	`string`	Yes	Workspace identifier
`date`	`string`	No	YYYY-MM-DD format (defaults to today)
`locale`	`string`	No	`"en"` or `"zh"` (default: `"en"`)

Response: Returns note object (201) or { skipped: true, reason: "..." } (200) if no activities found.

Weekly Report¶

Generate Weekly Report¶

POST /api/weekly-report

Generates a weekly activity report for a workspace.

请求体：

{
  "workspaceId": "workspace-uuid",
  "locale": "en"
}

Response: Returns note object (201) or { skipped: true, reason: "..." } (200) if no activities found.

Datasets¶

List Datasets¶

GET /api/datasets

Returns all datasets ordered by creation date (newest first).

Create Dataset (Start Download)¶

POST /api/datasets

Creates a dataset record and initiates background download.

请求体：

{
  "repoId": "username/dataset-name",
  "repoType": "dataset",
  "revision": "main",
  "name": "My Dataset",
  "allowPatterns": ["*.parquet"],
  "ignorePatterns": ["*.bin"],
  "source": "huggingface"
}

Field	Type	Required	描述
`repoId`	`string`	Yes	HuggingFace or ModelScope repository ID
`repoType`	`string`	No	`"dataset"`, `"model"`, or `"space"` (default: `"dataset"`)
`revision`	`string`	No	Specific branch or tag
`name`	`string`	No	Display name
`allowPatterns`	`string[]`	No	File glob patterns to include
`ignorePatterns`	`string[]`	No	File glob patterns to exclude
`source`	`string`	No	`"huggingface"` or `"modelscope"` (default: `"huggingface"`)

Get Dataset¶

GET /api/datasets/[datasetId]

Returns complete dataset information including parsed manifest and stats.

Delete Dataset¶

DELETE /api/datasets/[datasetId]?deleteFiles=true

Removes dataset from database. Set deleteFiles=true to also delete local files.

Get Download Status¶

GET /api/datasets/[datasetId]/status

Returns live download progress.

响应：

{
  "datasetId": "dataset-uuid",
  "status": "downloading",
  "progress": 45,
  "phase": "downloading",
  "downloadedBytes": 1048576,
  "totalBytes": 2097152,
  "downloadedFiles": 3,
  "totalFiles": 10
}

Pause Download¶

POST /api/datasets/[datasetId]/pause

Resume / Retry Download¶

POST /api/datasets/[datasetId]/retry

Cancel Download¶

POST /api/datasets/[datasetId]/cancel

Refresh Manifest¶

POST /api/datasets/[datasetId]/refresh

Recalculates manifest and stats from disk for ready datasets.

Preview Dataset¶

GET /api/datasets/[datasetId]/preview?split=default&n=20

Returns sample data from ready datasets. n is capped at 1000.

Manage Workspace Links¶

GET /api/datasets/[datasetId]/workspaces
POST /api/datasets/[datasetId]/workspaces
DELETE /api/datasets/[datasetId]/workspaces?workspaceId={id}

Link/unlink datasets to workspaces (many-to-many relationship).

Import Local Dataset¶

POST /api/datasets/import-local

请求体：

{
  "localPath": "/data/my-local-dataset",
  "name": "My Local Dataset"
}

Get HuggingFace Repo Info¶

GET /api/datasets/repo-info?repoId={repoId}&repoType=dataset

Get ModelScope Repo Info¶

GET /api/datasets/modelscope-info?repoId={repoId}&repoType=dataset

Paper Study¶

Search Papers¶

POST /api/paper-study/search

请求体：

{
  "keywords": ["transformer", "attention"],
  "maxResults": 10,
  "dateFrom": "2025-01-01",
  "dateTo": "2025-03-01",
  "sources": ["arxiv", "huggingface"]
}

Field	Type	Required	描述
`keywords`	`string[]`	Yes	At least one keyword required
`maxResults`	`number`	No	Max 30 (default: 10)
`dateFrom`	`string`	No	Start date filter
`dateTo`	`string`	No	End date filter
`sources`	`string[]`	No	`"arxiv"` and/or `"huggingface"` (default: both)

Scheduled Tasks¶

List Scheduled Tasks¶

GET /api/scheduled-tasks

Create Scheduled Task¶

POST /api/scheduled-tasks

请求体：

{
  "name": "Daily Git Sync",
  "taskType": "git_sync",
  "schedule": "0 0 * * *",
  "workspaceId": "workspace-uuid",
  "isEnabled": true
}

Field	Type	Required	描述
`name`	`string`	Yes	Task display name
`taskType`	`string`	Yes	`"daily_report"`, `"weekly_report"`, `"git_sync"`, `"source_sync"`, or `"custom"`
`schedule`	`string`	Yes	Valid cron expression (e.g. `"0 0 * * *"`)
`workspaceId`	`string`	No	Workspace to bind (null = global)
`config`	`object`	No	Task-specific JSON configuration
`isEnabled`	`boolean`	No	Default: `true`

Get / Update / Delete Scheduled Task¶

GET    /api/scheduled-tasks/[taskId]
PUT    /api/scheduled-tasks/[taskId]
DELETE /api/scheduled-tasks/[taskId]

Terminal¶

Execute Command¶

POST /api/terminal/exec

Executes a shell command in the workspace directory.

请求体：

{
  "command": "ls -la",
  "cwd": "/data/research/my-project"
}

Field	Type	Required	描述
`command`	`string`	Yes	Shell command (max 4096 chars)
`cwd`	`string`	Yes	Working directory (validated against allowed roots)

响应：

{
  "stdout": "...",
  "stderr": "...",
  "exitCode": 0,
  "cwd": "/data/research/my-project"
}

Timeout: 30 seconds. Max output: 1MB.

Cluster¶

Get Cluster Status¶

GET /api/cluster/status

Returns Kubernetes cluster overview (nodes, jobs, pods). Returns { configured: false } if KUBECONFIG_PATH is not set.

响应：

{
  "configured": true,
  "nodes": [{ "name": "...", "ready": true, "roles": "...", "cpu": "...", "memory": "...", "gpu": "..." }],
  "jobs": [{ "name": "...", "namespace": "...", "active": 1, "succeeded": 0, "failed": 0 }],
  "pods": [{ "name": "...", "namespace": "...", "phase": "Running", "nodeName": "..." }],
  "timestamp": "2025-03-01T00:00:00.000Z"
}

Get Cluster Operations¶

GET /api/cluster/operations?workspaceId={id}&limit=50&offset=0

Returns paginated cluster operation audit log. limit max: 200.

Models¶

List Available Models¶

GET /api/models?provider=openai

Fetches available models from the configured provider's API.

Parameter	Type	Required	描述
`provider`	`string`	No	`"openai"` or `"anthropic"` (default: `"openai"`)

响应：

{
  "models": [
    { "id": "gpt-4o", "name": "gpt-4o" }
  ]
}

System¶

Network Speed¶

GET /api/system/network

Returns current network speed measurement.

Feishu Push¶

Push Message to Feishu¶

POST /api/bot/feishu/push

Pushes a message or interactive card to a Feishu chat.

Headers:

Authorization: Bearer <FEISHU_PUSH_SECRET>

请求体：

{
  "chatId": "oc_xxxxxxxxxxxx",
  "title": "Agent Message",
  "content": "Message content here",
  "type": "card"
}

Field	Type	Required	描述
`chatId`	`string`	Yes	Feishu chat/group ID
`title`	`string`	No	Card title (default: `"Agent Message"`)
`content`	`string`	Yes	Message content
`type`	`string`	No	`"text"` or `"card"` (default: `"card"`)

Git¶

克隆仓库¶

POST /api/git/clone

请求体：

{
  "url": "https://github.com/user/repo.git",
  "rootPath": "/data/research"
}

拉取仓库¶

POST /api/git/pull

请求体：

{
  "workspaceId": "workspace-uuid"
}

获取 Git 状态¶

GET /api/git/status?workspaceId={id}

设置¶

获取设置¶

GET /api/settings

更新设置¶

PUT /api/settings

Skills¶

List Skills¶

GET /api/skills?workspaceId={id}

Create Skill¶

POST /api/skills

Import Skill¶

POST /api/skills/import

Export Skill¶

GET /api/skills/[skillId]/export

Update / Delete Skill¶

PUT    /api/skills/[skillId]
DELETE /api/skills/[skillId]

错误处理¶

所有 API 端点返回标准 HTTP 状态码：

状态码	描述
`200`	成功
`201`	Created (new resource)
`400`	请求错误（缺少或无效的参数）
`401`	Unauthorized (invalid authentication)
`404`	资源未找到
`500`	服务器内部错误
`503`	Service unavailable (AI not configured)

错误响应包含 JSON 正文：

{
  "error": "Description of the error"
}