API Reference

Version: v0.2.0-alpha

Web API Endpoints

Base URL: http://localhost:8080

Authentication

Most endpoints require authentication via session cookies managed through the Web UI. Before system initialization, all requests except the help page will be redirected to the initialization page.

Dashboard

Get Dashboard Statistics

GET /api/dashboard/stats

Returns system overview data (number of beings, running status, etc.).

Get Performance Metrics

GET /api/dashboard/metrics

Returns real-time performance metric data.

Chat System

Chat Page

GET /chat

Returns the chat interface page.

Streaming Chat (SSE)

GET /api/chat/stream

Streaming chat via Server-Sent Events (SSE).

Response: Server-Sent Event stream

data: {"type": "chunk", "content": "I"}
data: {"type": "chunk", "content": "'m"}
data: {"type": "chunk", "content": " thinking..."}
data: {"type": "complete", "sessionId": "uuid"}

Get Conversation List

GET /api/chat/conversations

Returns a list of all active Chat Sessions.

Response Example:

{
  "conversations": [
    {
      "sessionId": "85ccff8e-7497-1991-7a38-ffa1b7d9c50d",
      "beingId": "being-uuid",
      "type": "single",
      "displayName": "与小游聊天",
      "lastMessage": "最后消息内容",
      "lastTime": "2026-05-20T10:30:00Z"
    }
  ]
}

Get Message History

GET /api/chat/messages

Query parameter: channelId — Channel/Session ID

Returns the message history for the specified session.

Get Chat History

GET /api/chat/history

Returns global chat history records.

Send Message

POST /api/chat/send

Request Body:

{
  "channelId": "85ccff8e-7497-1991-7a38-ffa1b7d9c50d",
  "content": "测试消息内容"
}

Response:

{
  "success": true,
  "messageId": "50156b26-f3b9-4735-be3d-51e547bd3a4a"
}

Stop AI Thinking

POST /api/chat/stop

Stops the currently ongoing AI response generation.

Request Body:

{
  "channelId": "85ccff8e-7497-1991-7a38-ffa1b7d9c50d"
}

Upload File

POST /api/chat/upload

Uploads a file to the Chat Session (supports multipart/form-data).

Silicon Being Management

Being Management Page

GET /beings

Returns the Silicon Being management interface page.

Get Being List

GET /api/beings or GET /api/beings/list

Returns a list of all registered Silicon Beings.

Response Example:

{
  "beings": [
    {
      "id": "being-uuid",
      "name": "Assistant",
      "status": "running",
      "soulPath": "path/to/soul.md"
    }
  ]
}

Status values: idle | running | waiting_permission | stopped

Get Being Detail

GET /api/beings/detail

Query parameter: beingId — Silicon Being ID

Returns detailed information about the specified Silicon Being.

Get Being Activity Status

GET /api/beings/activity

Returns activity status information for each Silicon Being.

Soul File Editor Page

GET /beings/soul

Returns the Soul File editor interface.

Save Soul File

POST /api/beings/soul/save

Request Body:

{
  "beingId": "being-uuid",
  "soulContent": "# Personality\nYou are helpful..."
}

AI Config Editor Page

GET /beings/ai-config

Returns the AI configuration editor interface.

Save AI Config

POST /api/beings/ai-config/save

Request Body:

{
  "beingId": "being-uuid",
  "aiClientType": "DashScope",
  "config": {
    "apiKey": "...",
    "region": "beijing",
    "model": "qwen3.6-plus"
  }
}

Get Available AI Model List

GET /api/beings/ai-config/models

Query parameters: clientType, apiKey, region

Returns the list of available models for the specified AI client.

Chat History View

Chat History Page

GET /chat-history

Returns the chat history main page.

Chat History Detail Page

GET /chat-history-detail

Returns the chat history detail page for the specified session.

Group Chat History Detail Page

GET /group-chat-history-detail

Returns the history detail page for Group Chat Sessions.

Broadcast History Detail Page

GET /broadcast-history-detail

Returns the history detail page for Broadcast Channels.

Get History Conversation List

GET /api/chat-history/conversations

Returns a list of all historical conversations.

Get History Messages

GET /api/chat-history/messages

Query parameter: sessionId — Session ID

Returns the message records for the specified historical session.

Timer Management

Timer Page

GET /timers

Returns the Timer management interface page.

Get Timer List

GET /api/timers/list

Returns a list of all timers.

Timer Cycle Detail Page

GET /timer-cycles/{timerId}

Returns the execution cycle detail page for the specified timer.

Get Timer Cycle List

GET /api/timer-cycles/list

Query parameter: timerId — Timer ID

Returns a list of all execution cycles for the specified timer.

Single Execution Cycle Detail Page

GET /timer-cycle/{cycleIndex}

Returns the detail page for a single execution.

Get Cycle Messages

GET /api/timer-cycle/messages

Query parameter: cycleIndex — Cycle index

Returns the related messages for the specified execution cycle.

Task Management

Task Page

GET /tasks

Returns the Task management interface page.

Get Task List

GET /api/tasks/list

Returns a list of all tasks.

Task Cycle Detail Page

GET /task-cycles/{taskId}

Returns the execution cycle detail page for the specified task.

Get Task Cycle List

GET /api/task-cycles/list

Query parameter: taskId — Task ID

Returns a list of all execution cycles for the specified task.

Single Execution Cycle Detail Page

GET /task-cycle/{cycleIndex}

Returns the detail page for a single task execution.

Get Cycle Messages

GET /api/task-cycle/messages

Query parameter: cycleIndex — Cycle index

Returns the related messages for the specified task execution cycle.

Permission System

Permission Management Page

GET /permissions

Returns the Permission Manager interface page.

Get Permission Rule List

GET /api/permissions/list

Returns all currently configured permission rules.

Response Example:

{
  "rules": [
    {
      "permissionType": "NetworkAccess",
      "resourcePrefix": "api.github.com",
      "result": "Allowed",
      "description": "Allow GitHub API access"
    }
  ]
}

Save Permission Rule

POST /api/permissions/save

Request Body:

{
  "permissionType": "FileAccess",
  "resourcePrefix": "C:\\Projects",
  "result": "Allowed",
  "description": "Allow project directory access"
}

Permission Request Page

GET /permission/request

Displays the permission request page, allowing users to approve or deny permission requests from Silicon Beings.

Query Parameters:

Parameter	Type	Description
`userId`	`Guid`	The Silicon Being ID requesting permission
`type`	`string`	Permission Type
`resource`	`string`	Requested resource path
`allowCode`	`string`	Code identifier for the allow action
`denyCode`	`string`	Code identifier for the deny action

Check Pending Permission Requests

GET /permission/check

Query parameter: userId — Silicon Being ID

Response:

{
  "pending": true
}

Respond to Permission Request

GET /permission/respond

Query Parameters:

Parameter	Type	Description
`userId`	`Guid`	Silicon Being ID
`allowed`	`bool`	Whether to allow
`addToCache`	`bool`	Whether to cache the decision
`cacheDuration`	`double`	Cache duration (hours)

Response:

{
  "success": true
}

Logging System

Log Page

GET /logs

Returns the log viewer interface page.

Get Log List

GET /api/logs/list

Query parameters support filtering by level and time range.

Response Example:

{
  "logs": [
    {
      "timestamp": "2026-04-20T10:30:00Z",
      "level": "error",
      "message": "Failed to connect to AI service",
      "source": "OllamaClient"
    }
  ]
}

Get Logs Grouped by Being

GET /api/logs/beings

Returns log statistics grouped by Silicon Being.

Get Available Log Levels

GET /api/logs/levels

Returns the list of available Log Levels in the system.

Usage Statistics

Usage Statistics Page

GET /usage

Returns the usage statistics interface page.

Get Usage Summary

GET /api/usage/summary

Returns a Token usage and cost summary.

Get Trend Data

GET /api/usage/trend

Query parameters: startDate, endDate

Returns usage trend data for the specified time period.

Export Usage Data

GET /api/usage/export

Exports usage data in a downloadable format.

Audit Trail

Audit Page

GET /audit

Returns the audit trail interface page.

Get Audit List

GET /api/audit/list

Returns a list of audit log entries.

Get Audit Summary

GET /api/audit/summary

Returns summary statistics of audit data.

Get Audit Grouped by Being

GET /api/audit/beings

Returns audit statistics grouped by Silicon Being.

Configuration Management

Configuration Page

GET /config

Returns the system configuration interface page.

Save Configuration

POST /config/save

Request Body:

{
  "language": "ZhCN",
  "port": 8080,
  "aiClients": {
    "Ollama": {
      "baseUrl": "http://localhost:11434",
      "model": "qwen2.5:7b"
    },
    "DashScope": {
      "apiKey": "...",
      "region": "beijing",
      "model": "qwen3.6-plus"
    },
    "VolcengineArk": {
      "apiKey": "...",
      "endpoint": "...",
      "model": "..."
    },
    "Herdsman": {
      "endpoint": "http://localhost:8000",
      "model": "..."
    },
    "LongCat": {
      "apiKey": "...",
      "endpoint": "...",
      "model": "..."
    },
    "QiniuAI": {
      "apiKey": "...",
      "endpoint": "...",
      "model": "..."
    }
  }
}

Get AI Configuration Options

GET /config/aioptions

Returns available AI client types and their dynamic options (available models, regions, etc.).

Memory System

Memory Page

GET /memory

Returns the memory management interface page.

Get Memory List

GET /api/memory/list

Returns a list of memory entries for Silicon Beings.

Get Memory Detail

GET /api/memory/detail/{id}

Path parameter: id — Memory entry ID

Returns the full content of the specified memory entry.

Get Memory Statistics

GET /api/memory/stats

Returns statistics for the memory system.

Search Memory

GET /api/memory/search

Query parameter: keyword — Search keyword

Searches for matching memory entries.

Get Memory Grouped by Being

GET /api/memory/beings

Returns memory statistics grouped by Silicon Being.

Get Memory Trace

GET /api/memory/trace/{id}

Path parameter: id — Memory entry ID

Returns the source trace chain for the specified memory entry.

Get Memory Timeline HTML

GET /api/memory/timeline-html

Returns an HTML view of the memory timeline.

Work Notes

Work Notes Page

GET /work-notes

Returns the Work Note System interface page.

Get Work Notes List

GET /api/work-notes/list

Returns a list of work notes.

Read Work Note

GET /api/work-notes/read

Query parameter: noteId — Note ID

Returns the content of the specified note.

Get Note Directory

GET /api/work-notes/directory

Returns the note directory structure.

Search Work Notes

GET /api/work-notes/search

Query parameter: keyword — Search keyword

Searches for matching work notes.

Create Work Note

POST /api/work-notes/create

Request Body:

{
  "title": "笔记标题",
  "content": "笔记内容",
  "keywords": ["关键词1", "关键词2"]
}

Update Work Note

POST /api/work-notes/update

Request Body:

{
  "noteId": "note-uuid",
  "title": "更新后的标题",
  "content": "更新后的内容"
}

Delete Work Note

POST /api/work-notes/delete

Request Body:

{
  "noteId": "note-uuid"
}

Knowledge Network

Knowledge Network Page

GET /knowledge

Returns the Knowledge Network management interface page.

Get Knowledge Graph

GET /api/knowledge/graph

Returns knowledge triple graph data (subject-relation-object).

Project Management

Project Page

GET /project

Returns the Project System interface page.

Project Work Notes Page

GET /project/{id}/work-notes

Path parameter: id — Project ID

Returns the work notes page for the specified project.

Project Tasks Page

GET /project/{id}/tasks

Path parameter: id — Project ID

Returns the task management page for the specified project.

Project Tool Permissions Page

GET /project/{id}/tool-permissions

Path parameter: id — Project ID

Returns the tool permission management page for the specified project.

Project Workflow Page

GET /project/{id}/workflow

Path parameter: id — Project ID

Returns the workflow management page for the specified project.

Get Project Workflow Detail

GET /api/projects/workflow-detail

Query parameter: projectId — Project ID

Returns the workflow details associated with the project.

Assign Project Role

POST /api/projects/assign-role

Request Body:

{
  "projectId": "project-uuid",
  "beingId": "being-uuid",
  "roleName": "developer"
}

Remove Project Role

POST /api/projects/remove-role

Request Body:

{
  "projectId": "project-uuid",
  "beingId": "being-uuid",
  "roleName": "developer"
}

Get Project List

GET /api/projects/list

Returns a list of all projects.

Get Project Workflow Template List

GET /api/projects/list-workflow-templates

Returns a list of available workflow templates.

Create Project

POST /api/projects/create

Request Body:

{
  "name": "My Project",
  "description": "Project description"
}

Archive Project

POST /api/projects/{id}/archive

Path parameter: id — Project ID

Archives the specified project.

Restore Project

POST /api/projects/{id}/restore

Path parameter: id — Project ID

Restores an archived project.

Destroy Project

POST /api/projects/{id}/destroy

Path parameter: id — Project ID

Permanently deletes the specified project (irreversible).

Get Project Detail

GET /api/projects/detail

Query parameter: projectId — Project ID

Returns detailed information about the project.

Update Project

POST /api/projects/update

Request Body:

{
  "projectId": "project-uuid",
  "name": "Updated Name",
  "description": "Updated description"
}

Assign Member to Project

POST /api/projects/assign

Request Body:

{
  "projectId": "project-uuid",
  "beingId": "being-uuid"
}

Remove Member from Project

POST /api/projects/remove

Request Body:

{
  "projectId": "project-uuid",
  "beingId": "being-uuid"
}

Get Project Work Notes List

GET /api/projects/{id}/work-notes/list

Path parameter: id — Project ID

Returns a list of work notes for the specified project.

Read Project Work Note

GET /api/projects/{id}/work-notes/read

Path parameter: id — Project ID

Returns the content of a work note in the specified project.

Create Project Work Note

POST /api/projects/{id}/work-notes/create

Path parameter: id — Project ID

Creates a new work note in the specified project.

Update Project Work Note

POST /api/projects/{id}/work-notes/update

Path parameter: id — Project ID

Updates a work note in the specified project.

Delete Project Work Note

POST /api/projects/{id}/work-notes/delete

Path parameter: id — Project ID

Deletes a work note in the specified project.

Get Project Task List

GET /api/projects/{id}/tasks/list

Path parameter: id — Project ID

Returns a list of tasks for the specified project.

Create Project Task

POST /api/projects/{id}/tasks/create

Path parameter: id — Project ID

Creates a new task in the specified project.

Update Project Task

POST /api/projects/{id}/tasks/update

Path parameter: id — Project ID

Updates a task in the specified project.

Delete Project Task

POST /api/projects/{id}/tasks/delete

Path parameter: id — Project ID

Deletes a task in the specified project.

Assign Task Assignee

POST /api/projects/{id}/tasks/assign

Path parameter: id — Project ID

Assigns an assignee to a project task.

Remove Task Assignee

POST /api/projects/{id}/tasks/remove-assignee

Path parameter: id — Project ID

Removes the assignee from a project task.

Mark Task Complete

POST /api/projects/{id}/tasks/complete

Path parameter: id — Project ID

Marks a project task as completed.

Mark Task Failed

POST /api/projects/{id}/tasks/fail

Path parameter: id — Project ID

Marks a project task as failed.

Cancel Task

POST /api/projects/{id}/tasks/cancel

Path parameter: id — Project ID

Cancels a project task.

Tool Permission Management

Get Silicon Being Tool Permissions

GET /api/beings/tool-permissions

Query parameter: beingId — Silicon Being ID

Returns the tool permission configuration for the specified Silicon Being.

Update Silicon Being Tool Permissions

PUT /api/beings/tool-permissions

Request Body:

{
  "beingId": "being-uuid",
  "permissions": {
    "network": "allowed",
    "disk_read": "allowed",
    "disk_write": "denied"
  }
}

Get Tool Permission Templates

GET /api/beings/tool-permissions/templates

Returns a list of available tool permission templates.

Apply Tool Permission Template

POST /api/beings/tool-permissions/apply-template

Request Body:

{
  "beingId": "being-uuid",
  "templateName": "readonly"
}

Get Project Tool Permissions

GET /api/projects/{id}/tool-permissions

Path parameter: id — Project ID

Returns the tool permission configuration for the specified project.

Update Project Tool Permissions

PUT /api/projects/{id}/tool-permissions

Path parameter: id — Project ID

Request Body:

{
  "permissions": {
    "network": "allowed",
    "disk_read": "allowed",
    "disk_write": "denied"
  }
}

Executor Management

Executor Page

GET /executor

Returns the Executor management interface page.

Get Executor Status

GET /api/executors/status

Returns the running status of each Executor (Disk, Network, CommandLine).

Code Browser

Code Browser Page

GET /code

Returns the code browser interface page.

Get Code Type List

GET /api/code/types

Returns the list of supported code types/languages.

Get Code Detail

GET /api/code/detail

Query parameters: filePath, lineNumber

Returns code details for the specified file.

Code Hover Tips

Get Hover Tip

GET /api/code/hover POST /api/code/hover

Gets hover tip information for a code position (similar to IDE IntelliSense).

Register Code Position

POST /api/code/register

Registers a code position to monitor.

Update Code Position

POST /api/code/update

Updates a registered code position.

Unregister Code Position

POST /api/code/unregister

Unregisters a code position that no longer needs monitoring.

Help Documentation System

Help Page

GET /help or GET /help/index

Returns the help documentation main page.

Help Topic Page

GET /help/{topic}

Path parameter: topic — Topic identifier

Returns the help documentation page for the specified topic.

Search Help Documentation

GET /api/help/search

Query parameter: keyword — Search keyword

Searches for matching help documentation topics.

Initialization

Initialization Wizard Page

GET /init

Returns the first-run initialization wizard page.

Submit Initialization

POST /init

Submits the first-run initialization configuration.

Browse Data Directory

GET /init/browse

Opens a directory browser to select the data storage location.

Get AI Config Metadata

GET /init/ai-config-metadata

Returns available AI client types and their configuration field metadata.

System Control

Graceful Shutdown

POST /api/system/shutdown

Note: Only requests from localhost are allowed

Triggers the application's graceful shutdown process:

Stops the Main Loop
Saves the current configuration
Closes the HTTP listener

Response:

{
  "status": "shutting_down",
  "message": "Application is shutting down gracefully"
}

About

About Page

GET /about

Returns the about page, containing system information and a list of loaded plugins.

Plugin List Data:

{
  "plugins": {
    "plugin-id": {
      "name": "My Plugin",
      "version": "1.0.0",
      "description": "Plugin description",
      "author": "Author Name"
    }
  }
}

Error Responses

All endpoints return standardized error responses:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You don't have permission to access this resource",
    "details": "Required: FileAccess, Denied by GlobalACL"
  }
}

Common Error Codes

Code	HTTP Status	Description
`PERMISSION_DENIED`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request parameters
`INTERNAL_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	AI service unavailable

SSE Events

Server-Sent Events are used for real-time updates:

Chat Events

const eventSource = new EventSource('/api/chat/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'chunk':
      console.log('Streaming:', data.content);
      break;
    case 'tool_call':
      console.log('Tool executing:', data.tool);
      break;
    case 'complete':
      console.log('Chat complete, session:', data.sessionId);
      break;
    case 'error':
      console.error('Error:', data.message);
      break;
  }
};

AI Client Interface

IAIClient Interface

public interface IAIClient
{
    string Name { get; }
    
    Task<AIResponse> ChatAsync(AIRequest request);
    
    IAsyncEnumerable<string> StreamChatAsync(AIRequest request);
}

AIRequest Structure

public class AIRequest
{
    public List<Message> Messages { get; set; }
    public List<ToolDefinition> Tools { get; set; }
    public double Temperature { get; set; } = 0.7;
    public int MaxTokens { get; set; } = 2000;
    public string Model { get; set; }
}

AIResponse Structure

public class AIResponse
{
    public string Content { get; set; }
    public List<ToolCall> ToolCalls { get; set; }
    public TokenUsage Usage { get; set; }
    public string Model { get; set; }
}

Tool System Interface

ITool Interface

public interface ITool
{
    string Name { get; }
    string Description { get; }
    ToolDefinition Definition { get; }
    
    Task<ToolResult> ExecuteAsync(ToolCall call);
}

ToolCall Structure

public class ToolCall
{
    public string Id { get; set; }
    public string Name { get; set; }
    public Dictionary<string, object> Parameters { get; set; }
}

ToolResult Structure

public class ToolResult
{
    public bool Success { get; set; }
    public string Output { get; set; }
    public string Error { get; set; }
}

Next Steps

🚀 Check out the Getting Started Guide
🛠️ Read the Development Guide
📚 View the Architecture Documentation
🔒 Learn about the Security Model

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Web API Endpoints

Authentication

Dashboard

Get Dashboard Statistics

Get Performance Metrics

Chat System

Chat Page

Streaming Chat (SSE)

Get Conversation List

Get Message History

Get Chat History

Send Message

Stop AI Thinking

Upload File

Silicon Being Management

Being Management Page

Get Being List

Get Being Detail

Get Being Activity Status

Soul File Editor Page

Save Soul File

AI Config Editor Page

Save AI Config

Get Available AI Model List

Chat History View

Chat History Page

Chat History Detail Page

Group Chat History Detail Page

Broadcast History Detail Page

Get History Conversation List

Get History Messages

Timer Management

Timer Page

Get Timer List

Timer Cycle Detail Page

Get Timer Cycle List

Single Execution Cycle Detail Page

Get Cycle Messages

Task Management

Task Page

Get Task List

Task Cycle Detail Page

Get Task Cycle List

Single Execution Cycle Detail Page

Get Cycle Messages

Permission System

Permission Management Page

Get Permission Rule List

Save Permission Rule

Permission Request Page

Check Pending Permission Requests

Respond to Permission Request

Logging System

Log Page

Get Log List

Get Logs Grouped by Being

Get Available Log Levels

Usage Statistics

Usage Statistics Page

Get Usage Summary

Get Trend Data

Export Usage Data

Audit Trail

Audit Page

Get Audit List

Get Audit Summary

Get Audit Grouped by Being

Configuration Management

Configuration Page

Save Configuration

Get AI Configuration Options

Memory System

Memory Page