API Reference

July 3, 2026 ยท View on GitHub

InnoClaw provides a set of REST API endpoints served by Next.js API routes. All endpoints are under the /api/ path.

Auth

Login

POST /api/auth/login

Creates a browser session for a local user account.

Register

POST /api/auth/register

Creates a local user account and signs the user in.

Current Session

GET /api/auth/me

Returns the signed-in user and session expiry, or 401 if the request is unauthenticated.

CLI Session Handoff

POST /api/auth/cli-session

Requires an authenticated browser session. Mints a fresh CLI session for the same user and returns the cookie triple needed by the terminal client.

Request Body:

{
  "nonce": "cli-login-nonce"
}

Response:

{
  "nonce": "cli-login-nonce",
  "expiresAt": "2026-06-20T00:00:00.000Z",
  "user": {
    "id": "user-123",
    "email": "user@example.com",
    "name": "User",
    "role": "user",
    "isActive": true,
    "lastLoginAt": null,
    "createdAt": "2026-05-20T00:00:00.000Z",
    "updatedAt": "2026-05-20T00:00:00.000Z"
  },
  "cookies": {
    "innoclaw_session": "token",
    "innoclaw_session_expires": "2026-06-20T00:00:00.000Z",
    "innoclaw_session_sig": "signature"
  }
}

Workspaces

List Workspaces

GET /api/workspaces

Returns all workspaces.

When auth is enabled, this endpoint requires a valid browser or CLI session cookie set. With AUTH_MODE=disabled, the trusted no-auth path returns the anonymous admin context.

Response:

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

Create Workspace

POST /api/workspaces

Request Body:

{
  "name": "my-project",
  "folderPath": "/data/research/my-project"
}

Delete Workspace

DELETE /api/workspaces/[workspaceId]

Removes the workspace record from the database. Files on disk are not deleted.

Files

Browse Directory

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

Returns the file listing for a directory within a workspace.

Read File

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

Returns the content of a file.

Write File

POST /api/files/write

Request Body:

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

Upload File

POST /api/files/upload

Accepts multipart/form-data with file, workspaceId, and path fields.

Delete File

DELETE /api/files/delete

Request Body:

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

Rename File

POST /api/files/rename

Request Body:

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

Create Directory

POST /api/files/mkdir

Request Body:

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

Chat

Send Message (Streaming)

POST /api/chat

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

Request Body:

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

Response: Server-Sent Events (SSE) stream with AI response tokens.

Agent

Agent Chat (Streaming)

POST /api/agent

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

Request Body:

{
  "messages": [],
  "workspaceId": "workspace-uuid",
  "cwd": "/data/research/my-project",
  "skillId": "optional-skill-id",
  "paramValues": {},
  "mode": "agent"
}
FieldTypeRequiredDescription
messagesUIMessage[]YesChat message history
workspaceIdstringYesWorkspace identifier
cwdstringYesCurrent working directory for tool execution
skillIdstringNoSkill ID to use for this request
paramValuesobjectNoSkill parameter values
modestringNo"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.

Request Body:

{
  "workspaceId": "workspace-uuid",
  "messages": [],
  "trigger": "clear",
  "preview": false,
  "locale": "en"
}
FieldTypeRequiredDescription
workspaceIdstringYesWorkspace identifier
messagesarrayYesMessage array with parts and roles
triggerstringNo"clear" or "overflow"
previewbooleanNoIf true, returns summary without saving
localestringNo"en" or "zh" (default: "en")

Notes

List Notes

GET /api/notes?workspaceId={id}

Create Note

POST /api/notes

Request Body:

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

Update Note

PUT /api/notes/[noteId]

Delete Note

DELETE /api/notes/[noteId]

Generate

Generate Note Content

POST /api/generate

Request Body:

{
  "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.

Request Body:

{
  "workspaceId": "workspace-uuid",
  "date": "2025-03-01",
  "locale": "en"
}
FieldTypeRequiredDescription
workspaceIdstringYesWorkspace identifier
datestringNoYYYY-MM-DD format (defaults to today)
localestringNo"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.

Request Body:

{
  "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.

Request Body:

{
  "repoId": "username/dataset-name",
  "repoType": "dataset",
  "revision": "main",
  "name": "My Dataset",
  "allowPatterns": ["*.parquet"],
  "ignorePatterns": ["*.bin"],
  "source": "huggingface"
}
FieldTypeRequiredDescription
repoIdstringYesHuggingFace or ModelScope repository ID
repoTypestringNo"dataset", "model", or "space" (default: "dataset")
revisionstringNoSpecific branch or tag
namestringNoDisplay name
allowPatternsstring[]NoFile glob patterns to include
ignorePatternsstring[]NoFile glob patterns to exclude
sourcestringNo"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.

Response:

{
  "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.

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

Request Body:

{
  "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

Request Body:

{
  "keywords": ["transformer", "attention"],
  "maxResults": 10,
  "dateFrom": "2025-01-01",
  "dateTo": "2025-03-01",
  "sources": ["arxiv", "huggingface"]
}
FieldTypeRequiredDescription
keywordsstring[]YesAt least one keyword required
maxResultsnumberNoMax 30 (default: 10)
dateFromstringNoStart date filter
dateTostringNoEnd date filter
sourcesstring[]No"arxiv" and/or "huggingface" (default: both)

Scheduled Tasks

List Scheduled Tasks

GET /api/scheduled-tasks

Create Scheduled Task

POST /api/scheduled-tasks

Request Body:

{
  "name": "Daily Git Sync",
  "taskType": "git_sync",
  "schedule": "0 0 * * *",
  "workspaceId": "workspace-uuid",
  "isEnabled": true
}
FieldTypeRequiredDescription
namestringYesTask display name
taskTypestringYes"daily_report", "weekly_report", "git_sync", "source_sync", or "custom"
schedulestringYesValid cron expression (e.g. "0 0 * * *")
workspaceIdstringNoWorkspace to bind (null = global)
configobjectNoTask-specific JSON configuration
isEnabledbooleanNoDefault: 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.

Request Body:

{
  "command": "ls -la",
  "cwd": "/data/research/my-project"
}
FieldTypeRequiredDescription
commandstringYesShell command (max 4096 chars)
cwdstringYesWorking directory (validated against allowed roots)

Response:

{
  "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. Generic K8s Job tools also require either the generic K8S_CONTEXT/namespace/image fallback variables or a private K8S_JOB_PROFILES_FILE.

Response:

{
  "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.

ParameterTypeRequiredDescription
providerstringNo"openai" or "anthropic" (default: "openai")

Response:

{
  "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>

Request Body:

{
  "chatId": "oc_xxxxxxxxxxxx",
  "title": "Agent Message",
  "content": "Message content here",
  "type": "card"
}
FieldTypeRequiredDescription
chatIdstringYesFeishu chat/group ID
titlestringNoCard title (default: "Agent Message")
contentstringYesMessage content
typestringNo"text" or "card" (default: "card")

Git

Clone Repository

POST /api/git/clone

Request Body:

{
  "repoUrl": "https://github.com/user/repo.git",
  "targetFolderName": "repo"
}

Pull Repository

POST /api/git/pull

Request Body:

{
  "workspaceId": "workspace-uuid"
}

Get Git Status

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

Settings

Get Settings

GET /api/settings

Update 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]

Error Handling

All API endpoints return standard HTTP status codes:

StatusDescription
200Success
201Created (new resource)
400Bad request (missing or invalid parameters)
401Unauthorized (invalid authentication)
404Resource not found
500Internal server error
503Service unavailable (AI not configured)

Error responses include a JSON body:

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