> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# ComfyUI Server Routes (HTTP and WebSocket API)

> ComfyUI Server API routes: built-in GET, POST, and WebSocket endpoints for prompts, queue, history, models, and user data, plus how to add custom routes.

## Routes

The server defines a series of `get` and `post` methods
which can be found by searching for `@routes` in `server.py`. When you submit a workflow
in the web client, it is posted to `/prompt` which validates the prompt and adds it to an execution queue,
returning either a `prompt_id` and `number` (the position in the queue), or `error` and `node_errors` if validation fails.
The prompt queue is defined in `execution.py`, which also defines the `PromptExecutor` class.

### Built in routes

`server.py` defines the following routes:

#### 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

If you want to send a message from the client to the server during execution, you will need to add a custom route to the server.
For anything complicated, you will need to dive into the [aiohttp framework docs](https://docs.aiohttp.org/), but most cases can
be handled as follows:

```Python theme={null}
from server import PromptServer
from aiohttp import web
routes = PromptServer.instance.routes
@routes.post('/my_new_path')
async def my_function(request):
    the_data = await request.post()
    # the_data now holds a dictionary of the values sent
    MyClass.handle_my_message(the_data)
    return web.json_response({})
```

<Tip>Unless you know what you are doing, don't try to define `my_function` within a class.
The `@routes.post` decorator does a lot of work! Instead, define the function as above
and then call a classmethod.</Tip>

<Tip>You can also define a `@routes.get` if you aren't changing anything.</Tip>

The client can use this new route by sending a `FormData` object with code something like this,
which would result in `the_data`, in the above code, containing `message` and `node_id` keys:

```Javascript theme={null}
import { api } from "../../scripts/api.js";
function send_message(node_id, message) {
    const body = new FormData();
    body.append('message',message);
    body.append('node_id', node_id);
    api.fetchApi("/my_new_path", { method: "POST", body, });
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.