> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-recommend-assets-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 |
| `/api/assets` | get | list assets with filtering and pagination (recommended) |
| `/api/assets` | post | upload a new asset with tags and metadata (recommended) |
| `/api/assets/{id}` | get | get asset details by ID (recommended) |
| `/api/assets/{id}/content` | get | download asset content |
| `/api/tags` | get | list all tags |
| `/upload/image` | post | upload an image (legacy) |
| `/upload/mask` | post | upload a mask (legacy) |
| `/view` | get | view an image (legacy). 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) |
### Assets API
The Assets API (`/api/assets`) provides a unified, tag-based system for managing files (images, models, outputs) with content-addressed storage and metadata support. It is the recommended way to upload, organize, and retrieve files.
#### List Assets
`GET /api/assets` returns a paginated list of assets with optional filtering:
| Parameter | Type | Description |
| --------------- | ------- | ---------------------------------------------------------------- |
| `include_tags` | string | Filter assets that have ALL of these tags (comma-separated) |
| `exclude_tags` | string | Exclude assets that have ANY of these tags (comma-separated) |
| `name_contains` | string | Filter by name substring (case-insensitive) |
| `sort` | string | Sort field: `name`, `created_at` (default), `updated_at`, `size` |
| `order` | string | Sort direction: `asc`, `desc` (default) |
| `limit` | integer | Maximum items to return (1-500, default: 20) |
| `offset` | integer | Items to skip (default: 0) |
**Response:**
```json theme={null}
{
"assets": [
{
"id": "asset-uuid",
"name": "my-image.png",
"hash": "blake3:abc123...",
"size_bytes": 102400,
"mime_type": "image/png",
"tags": ["output", "image"],
"created_at": "2024-01-29T12:00:00Z",
"preview_url": "/api/assets/asset-uuid/content"
}
],
"total": 42,
"offset": 0,
"limit": 20
}
```
#### Upload Asset
`POST /api/assets` uploads a new asset (multipart/form-data):
| Field | Type | Description |
| --------------- | ------ | ---------------------------------------------- |
| `file` | file | The file to upload (required) |
| `name` | string | Display name for the asset |
| `tags` | string | Comma-separated tags (e.g., `input,reference`) |
| `user_metadata` | string | Custom JSON metadata |
#### Get Asset Details
`GET /api/assets/{id}` returns full details for a specific asset.
#### Download Asset Content
`GET /api/assets/{id}/content` downloads the asset file with appropriate Content-Type and Content-Disposition headers.
The Assets API uses content-addressed storage with Blake3 hashes, meaning identical files are automatically deduplicated. Tags provide flexible organization without rigid folder hierarchies.
### 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({})
```
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.
You can also define a `@routes.get` if you aren't changing anything.
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, });
}
```