This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
π‘ Special Arguments
When developping your own Tools, Functions (Filters, Pipes or Actions), Pipelines etc, you can use special arguments explore the full spectrum of what Open-WebUI has to offer.
This page aims to detail the type and structure of each special argument as well as provide an example.
bodyβ
A dict usually destined to go almost directly to the model. Although it is not strictly a special argument, it is included here for easier reference and because it contains itself some special arguments.
Example
{
"stream": true,
"model": "my-cool-model",
# lowercase string with - separated words: this is the ID of the model
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this picture?"
},
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAdYAAAGcCAYAAABk2YF[REDACTED]"
# Images are passed as base64 encoded data
}
}
]
},
{
"role": "assistant",
"content": "The image appears to be [REDACTED]"
},
],
"features": {
"image_generation": false,
"code_interpreter": false,
"web_search": false
},
"stream_options": {
"include_usage": true
},
"metadata": "[The exact same dict as __metadata__]",
"files": "[The exact same list as __files__]"
}
__user__β
A dict with user information.
Note that if the UserValves class is defined, its instance has to be accessed via __user__["valves"]. Otherwise, the valves keyvalue is missing entirely from __user__.
Example
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"email": "cheesy_dude@openwebui.com",
"name": "Patrick",
"role": "user",
# role can be either `user` or `admin`
"valves": "[the UserValve instance]"
}
__metadata__β
A dict with wide ranging information about the chat, model, files, etc.
Example
{
"user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"chat_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"session_id": "xxxxxxxxxxxxxxxxxxxx",
"tool_ids": null,
# tool_ids is a list of str.
"tool_servers": [],
"files": "[Same as in body['files']]",
# If no files are given, the files key exists in __metadata__ and its value is []
"features": {
"image_generation": false,
"code_interpreter": false,
"web_search": false
},
"variables": {
"{{USER_NAME}}": "cheesy_username",
"{{USER_LOCATION}}": "Unknown",
"{{CURRENT_DATETIME}}": "2025-02-02 XX:XX:XX",
"{{CURRENT_DATE}}": "2025-02-02",
"{{CURRENT_TIME}}": "XX:XX:XX",
"{{CURRENT_WEEKDAY}}": "Monday",
"{{CURRENT_TIMEZONE}}": "Europe/Berlin",
"{{USER_LANGUAGE}}": "en-US"
},
"model": "[The exact same dict as __model__]",
"direct": false,
"function_calling": "native",
"type": "user_response",
"interface": "open-webui"
}
__model__β
A dict with information about the model.
Example
{
"id": "my-cool-model",
"name": "My Cool Model",
"object": "model",
"created": 1746000000,
"owned_by": "openai",
# either openai or ollama
"info": {
"id": "my-cool-model",
"user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"base_model_id": "gpt-4o",
# this is the name of model that the model endpoint serves
"name": "My Cool Model",
"params": {
"system": "You are my best assistant. You answer [REDACTED]",
"function_calling": "native"
# custom options appear here, for example "Top K"
},
"meta": {
"profile_image_url": "/static/favicon.png",
"description": "Description of my-cool-model",
"capabilities": {
"vision": true,
"usage": true,
"citations": true
},
"position": 17,
"tags": [
{
"name": "for_friends"
},
{
"name": "vision_enabled"
}
],
"suggestion_prompts": null
},
"access_control": {
"read": {
"group_ids": [],
"user_ids": []
},
"write": {
"group_ids": [],
"user_ids": []
}
},
"is_active": true,
"updated_at": 1740000000,
"created_at": 1740000000
},
"preset": true,
"actions": [],
"tags": [
{
"name": "for_friends"
},
{
"name": "vision_enabled"
}
]
}
__messages__β
A list of the previous messages.
See the body["messages"] value above.
__chat_id__β
The str of the chat_id.
See the __metadata__["chat_id"] value above.
__session_id__β
The str of the session_id.
See the __metadata__["session_id"] value above.
__message_id__β
The str of the message_id.
See the __metadata__["message_id"] value above.
__event_emitter__β
A Callable used to display event information to the user.
__event_call__β
A Callable used for Actions.
__files__β
A list of files sent via the chat. Note that images are not considered files and are sent directly to the model as part of the body["messages"] list.
The actual binary of the file is not part of the arguments for performance reason, but the file remain nonetheless accessible by its path if needed. For example using docker the python syntax for the path could be:
from pathlib import Path
the_file = Path(f"/app/backend/data/uploads/{__files__[0]["files"]["id"]}_{__files__[0]["files"]["filename"]}")
assert the_file.exists()
Note that the same files dict can also be accessed via __metadata__["files"] (and its value is [] if no files are sent) or via body["files"] (but the files key is missing entirely from body if no files are sent).
Example
[
{
"type": "file",
"file": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"filename": "Napoleon - Wikipedia.pdf",
"user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"hash": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"data": {
"content": "Napoleon - Wikipedia\n\n\nNapoleon I\n\nThe Emperor Napoleon in His Study at the\nTuileries, 1812\n\nEmperor of the French\n\n1st reign 18 May 1804 β 6 April 1814\n\nSuccessor Louis XVIII[a]\n\n2nd reign 20 March 1815Β β 22Β June 1815\n\nSuccessor Louis XVIII[a]\n\nFirst Consul of the French Republic\n\nIn office\n13 December 1799Β β 18 May 1804\n\nBorn Napoleone Buonaparte\n15 August 1769\nAjaccio, Corsica, Kingdom of\nFrance\n\nDied 5 May 1821 (agedΒ 51)\nLongwood, Saint Helena\n\nBurial 15 December 1840\nLes Invalides, Paris\n\nNapoleon\nNapoleon Bonaparte[b] (born Napoleone\nBuonaparte;[1][c] 15 August 1769 β 5 May 1821), later\nknown [REDACTED]",
# The content value is the output of the document parser, the above example is with Tika as a document parser
},
"meta": {
"name": "Napoleon - Wikipedia.pdf",
"content_type": "application/pdf",
"size": 10486578,
# in bytes, here about 10Mb
"data": {},
"collection_name": "file-96xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# always begins by 'file'
},
"created_at": 1740000000,
"updated_at": 1740000000
},
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"url": "/api/v1/files/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Napoleon - Wikipedia.pdf",
"collection_name": "file-96xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
"status": "uploaded",
"size": 10486578,
"error": "",
"itemId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# itemId is not the same as file["id"]
}
]
__request__β
An instance of fastapi.Request. You can read more at the migration page or at fastapi's documentation.
__task__β
A str for the type of task. Its value is just a shorthand for __metadata__["task"] if present, otherwise None.
Possible values
[
"title_generation",
"tags_generation",
"emoji_generation",
"query_generation",
"image_prompt_generation",
"autocomplete_generation",
"function_calling",
"moa_response_generation"
]
__task_body__β
A dict containing the body needed to accomplish a given __task__. Its value is just a shorthand for __metadata__["task_body"] if present, otherwise None.
Its structure is the same as body above, with modifications like using the appropriate model and system message etc.
__tools__β
A list of ToolUserModel instances.
For details the attributes of ToolUserModel instances, the code can be found in tools.py.