---
id: routes---comfyui
title: "Routes - ComfyUI"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
duplicate_of: ""
source_trust_level: "B"
confidence_score: 1.0
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["web", "wikify"]
raw_sources: ["https://docs.comfy.org/development/comfyui-server/comms_routes"]
applied_in: []
github_commit: ""
---

# [[Routes - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
[[ComfyUI]] 서버의 [[Routes]]는 클라이언트와 서버 간의 데이터 교환, 작업 큐 관리, 실시간 상태 업데이트를 위한 HTTP 메서드 및 [[WebSocket]] 엔드포인트의 집합체이다.

## 🧠 핵심 개념 (Core concepts)
- **Core API Routes**: 서버의 기능을 수행하기 위해 정의된 다양한 [[GET]], [[POST]] 메서드들의 모음으로, 모델 관리, 이미지 업로드, 시스템 정보 조회 등을 포함한다.
- **WebSocket Communication**: 클라이언트와 서버 간의 양방향 실동기화를 지원하며, 실행 진행 상황 및 노드 상태를 실시간으로 전달하는 통로이다.
- **Custom Routes**: 개발자가 [[aiohttp]] 프레임워크를 사용하여 서버에 새로운 경로를 추가하고 클라이언트와의 메시지 송수신 기능을 확장할 수 있는 메커니즘이다.
- **Execution Queue Management**: [[prompt]] 제출, 큐 상태 조회, 실행 중단 및 히스토리 관리 등 작업 흐름의 제어를 담당한다.

## 🧩 추출된 패턴 (Extracted patterns)
- **Request/Response Pattern**: 특정 경로(예: `/prompt`)로 데이터를 제출하면 서버가 검증 후 실행 큐에 추가하고 결과를 반환하는 구조를 가진다.
- **Real-time Update Pattern**: [[WebSocket]]을 통해 `status`, `progress`, `executed` 등 다양한 타입의 JSON 메시지를 클라이언트에 브리캐스팅한다.
- **Extensibility Pattern**: `@routes.post`와 같은 데코레이터를 활용하여 기존 서버 구조를 변경하지 않고 새로운 기능을 추가할 수 있는 확장성을 제공한다.

## 📖 세부 내용 (Details)

### 1. Core API Routes (Built-in routes)
[[server.py]]에 정의된 주요 경로들의 기능은 다음과 같다.

| path | method | 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 (includes various options) |
| `/view_metadata/` | 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) |

### 2. WebSocket Communication
[[WebSocket]] 엔드포인트인 `/ws`는 실시간 양방향 통신을 위해 사용되며, 다음과 같은 정보를 전달한다.
- **주요 용도**: 실행 진행 상황 업데이트 수신, 노드 실행 상태 실시간 확인, 에러 메시지 및 디버깅 정보 수신, 큐 상태 변경 시 라이브 업데이트.
- **JSON 메시지 타입**:
    - `status`: 전체 시스템 상태 업데이트
    - `execution_start`: 프롬프트 실행 시작 시점
    - `execution_cached`: 캐시된 결과 사용 시
    - `executing`: 노드 실행 중 업데이트
    - `progress`: 장기 실행 작업의 진행률 업데이트
    - `executed`: 노드 실행 완료 시

### 3. Custom Routes Implementation
클라이언트에서 서버로 메시지를 보내기 위해 새로운 경로를 정의하는 방법이다.
- **서버 측 구현**: `aiohttp` 프레임워크를 활용하며, `@routes.post('/path')` 데코레이터를 사용한다. 함수 내부에서는 `request.post()`를 통해 데이터를 수신할 수 있다.
- **클라이언트 측 호출**: `FormData` 객체를 사용하여 `api.fetchApi`를 통해 새로운 경로에 요청을 보낼 수 있다.

## ⚖️ 모의 및 업데이트 (Contradictions & updates)
본문 내에서 상충되는 정보는 발견되지 않았습니다.

## 🛠️ 적용 사례 (Applied in summary)
- **Custom Node 개발**: 서버의 기능을 확장하기 위해 `@routes.post`를 사용하여 새로운 경로를 생성하고, `FormData`를 통해 데이터를 전송하는 예시가 제시됨.

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual
- **출처 신뢰도:** B (Primary Source — 웹사이트 본문 직접 추출)
- **중복 검사 결과:** 신규 생성 (New discovery)

## 🔗 관련 문서 링크 (Related document links)
- [[ComfyUI Server]]: 서버의 전반적인 구조와 역할을 이해하기 위한 핵심 개념입니다.
- [[WebSocket]]: 실시간 데이터 스트리밍 및 양방향 통신의 기술적 기반입니다.
- [[aiohttp]]: 커스텀 라우트를 구현할 때 사용하는 프레임워크입니다.
- [[PromptExecutor]]: 실행 큐를 정의하고 관리하는 클래스입니다.

## 📝 변경 이履歴 (Change history)
- 2026-05-20: Astra /wikify 로 https://docs.comfy.org/development/comfyui-server/comms_routes 본문에서 초안 생성.