Skip to content

Update ComfyUI server API routes documentation #354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christian-byrne merged 2 commits into from
Aug 11, 2025
Merged

Update ComfyUI server API routes documentation #354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d4f410b
[docs] update ComfyUI server API routes documentation
christian-byrne Aug 11, 2025
9c9f10a
[docs] update Chinese translation for API routes documentation
christian-byrne Aug 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 52 additions & 21 deletions development/comfyui-server/comms_routes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,27 +14,58 @@ The prompt queue is defined in `execution.py`, which also defines the `PromptExe

`server.py` defines the following routes:

| path | get/post | purpose |
| ------------------------------ | -------- | ------------------------------------------------------------------------- |
| `/` | get | load the comfy webpage |
| `/embeddings` | get | retrieve a list of the names of embeddings available |
| `/extensions` | get | retrieve a list of the extensions registering a `WEB_DIRECTORY` |
| `/workflow_templates` | get | retrieve a map of custom node modules and associated template workflows |
| `/upload/image` | post | upload an image |
| `/upload/mask` | post | upload a mask |
| `/view` | get | view an image. Lots of options, see `@routes.get("/view")` in `server.py` |
| `/view_metadata`/{folder_name} | get | retrieve metadata for a model |
| `/system_stats` | get | retrieve information about the system (python version, devices, vram etc) |
| `/prompt` | get | retrieve current status |
| `/prompt` | post | submit a prompt to the queue |
| `/object_info` | get | retrieve details of all node types |
| `/object_info/{node_class}` | get | retrieve details of one node type |
| `/history` | get | retrieve the queue history |
| `/history/{prompt_id}` | get | retrieve the queue history for a specific prompt |
| `/history` | post | clear history or delete history item |
| `/queue` | get | retrieve the state of the queue |
| `/interrupt` | post | stop the current workflow |
| `/free` | post | free memory by unloading specified models |
#### Core API Routes

| path | get/post/ws | purpose |
| ------------------------------ | ----------- | ------------------------------------------------------------------------- |
| `/` | get | load the comfy webpage |
| `/ws` | websocket | WebSocket endpoint for real-time communication with the server |
| `/embeddings` | get | retrieve a list of the names of embeddings available |
| `/extensions` | get | retrieve a list of the extensions registering a `WEB_DIRECTORY` |
| `/features` | get | retrieve server features and capabilities |
| `/models` | get | retrieve a list of available model types |
| `/models/{folder}` | get | retrieve models in a specific folder |
| `/workflow_templates` | get | retrieve a map of custom node modules and associated template workflows |
| `/upload/image` | post | upload an image |
| `/upload/mask` | post | upload a mask |
| `/view` | get | view an image. Lots of options, see `@routes.get("/view")` in `server.py` |
| `/view_metadata`/{folder_name} | get | retrieve metadata for a model |
| `/system_stats` | get | retrieve information about the system (python version, devices, vram etc) |
| `/prompt` | get | retrieve current queue status and execution information |
| `/prompt` | post | submit a prompt to the queue |
| `/object_info` | get | retrieve details of all node types |
| `/object_info/{node_class}` | get | retrieve details of one node type |
| `/history` | get | retrieve the queue history |
| `/history/{prompt_id}` | get | retrieve the queue history for a specific prompt |
| `/history` | post | clear history or delete history item |
| `/queue` | get | retrieve the current state of the execution queue |
| `/queue` | post | manage queue operations (clear pending/running) |
| `/interrupt` | post | stop the current workflow execution |
| `/free` | post | free memory by unloading specified models |
| `/userdata` | get | list user data files in a specified directory |
| `/v2/userdata` | get | enhanced version that lists files and directories in structured format |
| `/userdata/{file}` | get | retrieve a specific user data file |
| `/userdata/{file}` | post | upload or update a user data file |
| `/userdata/{file}` | delete | delete a specific user data file |
| `/userdata/{file}/move/{dest}` | post | move or rename a user data file |
| `/users` | get | get user information |
| `/users` | post | create a new user (multi-user mode only) |

### WebSocket Communication

The `/ws` endpoint provides real-time bidirectional communication between the client and server. This is used for:
- Receiving execution progress updates
- Getting node execution status in real-time
- Receiving error messages and debugging information
- Live updates when queue status changes

The WebSocket connection sends JSON messages with different types such as:
- `status` - Overall system status updates
- `execution_start` - When a prompt execution begins
- `execution_cached` - When cached results are used
- `executing` - Updates during node execution
- `progress` - Progress updates for long-running operations
- `executed` - When a node completes execution

### Custom routes

Expand Down
73 changes: 52 additions & 21 deletions zh-CN/development/comfyui-server/comms_routes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,27 +14,58 @@ title: "路由"

`server.py` 定义了以下路由：

| 路径 | get/post | 用途 |
| ------------------------------ | -------- | ---------------------------------------------------------------- |
| `/` | get | 加载 Comfy 网页 |
| `/embeddings` | get | 获取可用的嵌入模型名称列表 |
| `/extensions` | get | 获取注册了 `WEB_DIRECTORY` 的扩展列表 |
| `/workflow_templates` | get | 获取自定义节点模块及其关联模板工作流的映射 |
| `/upload/image` | post | 上传图片 |
| `/upload/mask` | post | 上传蒙版 |
| `/view` | get | 查看图片。更多选项请参见 `server.py` 中的 `@routes.get("/view")` |
| `/view_metadata`/{folder_name} | get | 获取模型的元数据 |
| `/system_stats` | get | 获取系统信息（Python 版本、设备、显存等） |
| `/prompt` | get | 获取当前状态 |
| `/prompt` | post | 提交提示到队列 |
| `/object_info` | get | 获取所有节点类型的详细信息 |
| `/object_info/{node_class}` | get | 获取特定节点类型的详细信息 |
| `/history` | get | 获取队列历史记录 |
| `/history/{prompt_id}` | get | 获取特定提示的队列历史记录 |
| `/history` | post | 清除历史记录或删除历史记录项 |
| `/queue` | get | 获取队列状态 |
| `/interrupt` | post | 停止当前工作流 |
| `/free` | post | 通过卸载指定模型释放内存 |
#### 核心 API 路由

| 路径 | get/post/ws | 用途 |
| ------------------------------ | ----------- | ---------------------------------------------------------------- |
| `/` | get | 加载 Comfy 网页 |
| `/ws` | websocket | 用于与服务器进行实时通信的 WebSocket 端点 |
| `/embeddings` | get | 获取可用的嵌入模型名称列表 |
| `/extensions` | get | 获取注册了 `WEB_DIRECTORY` 的扩展列表 |
| `/features` | get | 获取服务器功能和能力 |
| `/models` | get | 获取可用模型类型列表 |
| `/models/{folder}` | get | 获取特定文件夹中的模型 |
| `/workflow_templates` | get | 获取自定义节点模块及其关联模板工作流的映射 |
| `/upload/image` | post | 上传图片 |
| `/upload/mask` | post | 上传蒙版 |
| `/view` | get | 查看图片。更多选项请参见 `server.py` 中的 `@routes.get("/view")` |
| `/view_metadata`/{folder_name} | get | 获取模型的元数据 |
| `/system_stats` | get | 获取系统信息（Python 版本、设备、显存等） |
| `/prompt` | get | 获取当前队列状态和执行信息 |
| `/prompt` | post | 提交提示到队列 |
| `/object_info` | get | 获取所有节点类型的详细信息 |
| `/object_info/{node_class}` | get | 获取特定节点类型的详细信息 |
| `/history` | get | 获取队列历史记录 |
| `/history/{prompt_id}` | get | 获取特定提示的队列历史记录 |
| `/history` | post | 清除历史记录或删除历史记录项 |
| `/queue` | get | 获取执行队列的当前状态 |
| `/queue` | post | 管理队列操作（清除待处理/运行中的任务） |
| `/interrupt` | post | 停止当前工作流执行 |
| `/free` | post | 通过卸载指定模型释放内存 |
| `/userdata` | get | 列出指定目录中的用户数据文件 |
| `/v2/userdata` | get | 增强版本，以结构化格式列出文件和目录 |
| `/userdata/{file}` | get | 获取特定的用户数据文件 |
| `/userdata/{file}` | post | 上传或更新用户数据文件 |
| `/userdata/{file}` | delete | 删除特定的用户数据文件 |
| `/userdata/{file}/move/{dest}` | post | 移动或重命名用户数据文件 |
| `/users` | get | 获取用户信息 |
| `/users` | post | 创建新用户（仅限多用户模式） |

### WebSocket 通信

`/ws` 端点提供客户端与服务器之间的实时双向通信。用于：
- 接收执行进度更新
- 实时获取节点执行状态
- 接收错误消息和调试信息
- 队列状态变化时的实时更新

WebSocket 连接发送不同类型的 JSON 消息，例如：
- `status` - 整体系统状态更新
- `execution_start` - 当提示执行开始时
- `execution_cached` - 当使用缓存结果时
- `executing` - 节点执行期间的更新
- `progress` - 长时间运行操作的进度更新
- `executed` - 当节点完成执行时

### 自定义路由

Expand Down