fix(pipes): fix mcp tool filtering and force-enable autonomous web search

- Fix issue where mcp tool filtering logic (function_name_filter_list) in admin backend caused all tools to be hidden due to ID prefix mismatch
- Force enable web_search tool for Copilot Agent regardless of UI toggles, providing full autonomy for search-related intents
- Updated README and version to v0.9.1
This commit is contained in:
fujie
2026-03-04 00:11:28 +08:00
parent a8a324500a
commit c6279240b9
26 changed files with 3109 additions and 59 deletions

View File

@@ -0,0 +1,74 @@
# OpenWebUI API Documentation — Phase Run Order
## Overview
This task set reads the OpenWebUI backend source code and generates a complete
API reference in `api_docs/` inside the open-webui repository.
**Source repo:** `/Users/fujie/app/python/oui/open-webui`
**Output directory:** `/Users/fujie/app/python/oui/open-webui/api_docs/`
**Task files dir:** `plugins/debug/copilot-sdk/tasks/owui-api-docs/phases/`
---
## Phase Execution Order
Run phases sequentially. Each phase depends on the previous.
| Order | Task File | Coverage | ~Lines Read |
|-------|-----------|----------|-------------|
| 1 | `01_route_index.txt` | main.py + all 26 router files → master route table | ~15,000 |
| 2 | `02_auth_users_groups_models.txt` | auths, users, groups, models | ~4,600 |
| 3 | `03_chats_channels_memories_notes.txt` | chats, channels, memories, notes | ~5,500 |
| 4 | `04_files_folders_knowledge_retrieval.txt` | files, folders, knowledge, retrieval | ~5,200 |
| 5 | `05_ollama_openai_audio_images.txt` | ollama, openai, audio, images | ~6,900 |
| 6 | `06_tools_functions_pipelines_skills_tasks.txt` | tools, functions, pipelines, skills, tasks | ~3,200 |
| 7 | `07_configs_prompts_evaluations_analytics_scim_utils.txt` | configs, prompts, evaluations, analytics, scim, utils | ~3,400 |
| 8 | `08_consolidation_index.txt` | Consolidates all outputs → README.md + JSON | (reads generated files) |
---
## Output Files (after all phases complete)
```
open-webui/api_docs/
├── README.md ← Master index + quick reference
├── 00_route_index.md ← Complete route table (200+ endpoints)
├── 02_auths.md
├── 02_users.md
├── 02_groups.md
├── 02_models.md
├── 03_chats.md
├── 03_channels.md
├── 03_memories.md
├── 03_notes.md
├── 04_files.md
├── 04_folders.md
├── 04_knowledge.md
├── 04_retrieval.md
├── 05_ollama.md
├── 05_openai.md
├── 05_audio.md
├── 05_images.md
├── 06_tools.md
├── 06_functions.md
├── 06_pipelines.md
├── 06_skills.md
├── 06_tasks.md
├── 07_configs.md
├── 07_prompts.md
├── 07_evaluations.md
├── 07_analytics.md
├── 07_scim.md
├── 07_utils.md
└── openwebui_api.json ← Machine-readable summary (all routes)
```
---
## Notes
- Each phase uses `--no-plan-first` (detailed instructions already provided).
- Working directory for all phases: `/Users/fujie/app/python/oui/open-webui`
- The one-click runner: `run_owui_api_docs_phases.sh`
- If a phase fails, fix the issue and re-run that single phase before continuing.

View File

@@ -0,0 +1,41 @@
Phase 1 Mission:
Scan the entire OpenWebUI backend source and produce a master route index table.
Source root: backend/open_webui/
Target output directory: api_docs/
Constraints:
- Read-only on ALL files EXCEPT under api_docs/ (create it if missing).
- Do NOT generate per-endpoint detail yet — only the master table.
- Cover every router file in backend/open_webui/routers/.
- Also read backend/open_webui/main.py to capture route prefixes (app.include_router calls).
Deliverables:
1) Create directory: api_docs/
2) Create file: api_docs/00_route_index.md
Content of 00_route_index.md must contain:
- A table with columns: Module | HTTP Method | Path | Handler Function | Auth Required | Brief Description
- One row per route decorator found in every router file.
- "Auth Required" = YES if the route depends on get_verified_user / get_admin_user / similar dependency, NO otherwise.
- "Brief Description" = first sentence of the handler's docstring, or empty string if none.
- Group rows by Module (router file name without .py).
- At the top: a summary section listing total_route_count and module_count.
Process:
1. Read main.py — extract all app.include_router() calls, note prefix and tags per router.
2. For each router file in backend/open_webui/routers/, read it fully.
3. Find every @router.get/@router.post/@router.put/@router.delete/@router.patch decorator.
4. For each decorator: record path, method, function name, auth dependency, docstring.
5. Write the combined table to api_docs/00_route_index.md.
Exit Criteria:
- api_docs/00_route_index.md exists.
- Table contains at least 100 rows (the codebase has 200+ routes).
- No placeholder or TBD.
- Total route count printed at the top.
Final output format:
- List of files created/updated.
- Total routes found.
- Any router files that could not be parsed and why.

View File

@@ -0,0 +1,82 @@
Phase 2 Mission:
Generate detailed API reference documentation for authentication, users, groups, and models endpoints.
Prerequisites:
- api_docs/00_route_index.md must already exist (from Phase 1).
Source files to read (fully):
- backend/open_webui/routers/auths.py
- backend/open_webui/routers/users.py
- backend/open_webui/routers/groups.py
- backend/open_webui/routers/models.py
- backend/open_webui/models/auths.py (Pydantic models)
- backend/open_webui/models/users.py
- backend/open_webui/models/groups.py (if exists)
- backend/open_webui/models/models.py
Output files to create under api_docs/:
- 02_auths.md
- 02_users.md
- 02_groups.md
- 02_models.md
Per-endpoint format (use this EXACTLY for every endpoint in each file):
---
### {HTTP_METHOD} {full_path}
**Summary:** One sentence description.
**Auth:** Admin only | Verified user | Public
**Request**
| Location | Field | Type | Required | Description |
|----------|-------|------|----------|-------------|
| Header | Authorization | Bearer token | Yes | JWT token |
| Body | field_name | type | Yes/No | description |
| Query | param_name | type | No | description |
| Path | param_name | type | Yes | description |
*If no request body/params, write: "No additional parameters."*
**Response `200`**
```json
{
"example_field": "example_value"
}
```
| Field | Type | Description |
|-------|------|-------------|
| field_name | type | description |
**Error Responses**
| Status | Meaning |
|--------|---------|
| 400 | Bad request / validation error |
| 401 | Not authenticated |
| 403 | Insufficient permissions |
| 404 | Resource not found |
---
Instructions:
1. Read each router file fully to understand every route.
2. Trace Pydantic model definitions from the corresponding models/ file.
3. Fill in every field from actual code — no guessing.
4. If a field is Optional with a default, mark Required = No.
5. For auth: check FastAPI dependency injection (Depends(get_verified_user) → "Verified user", Depends(get_admin_user) → "Admin only").
6. List ALL endpoints in the router — do not skip any.
Exit Criteria:
- 4 output files created.
- Every route from 00_route_index.md for these modules is covered.
- No placeholder or TBD.
Final output format:
- List of files created.
- Count of endpoints documented per file.

View File

@@ -0,0 +1,87 @@
Phase 3 Mission:
Generate detailed API reference documentation for chat, channels, memories, and notes endpoints.
Prerequisites:
- api_docs/00_route_index.md must already exist (from Phase 1).
Source files to read (fully):
- backend/open_webui/routers/chats.py
- backend/open_webui/routers/channels.py
- backend/open_webui/routers/memories.py
- backend/open_webui/routers/notes.py
- backend/open_webui/models/chats.py (Pydantic models)
- backend/open_webui/models/channels.py
- backend/open_webui/models/memories.py
- backend/open_webui/models/notes.py (if exists)
- backend/open_webui/models/messages.py (shared message models)
Output files to create under api_docs/:
- 03_chats.md
- 03_channels.md
- 03_memories.md
- 03_notes.md
Per-endpoint format:
---
### {HTTP_METHOD} {full_path}
**Summary:** One sentence description.
**Auth:** Admin only | Verified user | Public
**Request**
| Location | Field | Type | Required | Description |
|----------|-------|------|----------|-------------|
| Body | field_name | type | Yes/No | description |
*If no parameters, write: "No additional parameters."*
**Response `200`**
```json
{
"example_field": "example_value"
}
```
| Field | Type | Description |
|-------|------|-------------|
| field_name | type | description |
**Error Responses**
| Status | Meaning |
|--------|---------|
| 401 | Not authenticated |
| 403 | Insufficient permissions |
| 404 | Resource not found |
---
Special notes for this phase:
- chats.py is 1527 lines with ~40 routes — document ALL of them.
- channels.py is 2133 lines — document ALL routes; note WebSocket upgrade endpoints separately.
- For WebSocket endpoints: note the protocol (ws://) and describe events/message payload format.
- Pay special attention to chat history structure: messages array, history.messages dict.
- Note pagination parameters (skip, limit, page) where applicable.
Instructions:
1. Read each router file fully.
2. Trace Pydantic model definitions from the corresponding models/ file.
3. For complex response types (list of chats, paginated results), show the wrapper structure.
4. If a route modifies chat history, document the exact history object shape.
5. List ALL endpoints — do not skip paginated variants.
Exit Criteria:
- 4 output files created.
- Every route from 00_route_index.md for these modules is covered.
- WebSocket endpoints documented with payload shape.
- No placeholder or TBD.
Final output format:
- List of files created.
- Count of endpoints documented per file.
- Note any complex schemas that required deep tracing.

View File

@@ -0,0 +1,94 @@
Phase 4 Mission:
Generate detailed API reference documentation for files, folders, knowledge base, and retrieval endpoints.
Prerequisites:
- api_docs/00_route_index.md must already exist (from Phase 1).
Source files to read (fully):
- backend/open_webui/routers/files.py (~911 lines)
- backend/open_webui/routers/folders.py (~351 lines)
- backend/open_webui/routers/knowledge.py (~1139 lines)
- backend/open_webui/routers/retrieval.py (~2820 lines — LARGEST FILE)
- backend/open_webui/models/files.py
- backend/open_webui/models/folders.py
- backend/open_webui/models/knowledge.py
Output files to create under api_docs/:
- 04_files.md
- 04_folders.md
- 04_knowledge.md
- 04_retrieval.md
Per-endpoint format:
---
### {HTTP_METHOD} {full_path}
**Summary:** One sentence description.
**Auth:** Admin only | Verified user | Public
**Request**
| Location | Field | Type | Required | Description |
|----------|-------|------|----------|-------------|
| Body | field_name | type | Yes/No | description |
*If no parameters, write: "No additional parameters."*
**Response `200`**
```json
{
"example_field": "example_value"
}
```
| Field | Type | Description |
|-------|------|-------------|
| field_name | type | description |
**Error Responses**
| Status | Meaning |
|--------|---------|
| 401 | Not authenticated |
| 404 | Resource not found |
---
Special notes for this phase:
FILES:
- File upload uses multipart/form-data — document the form fields.
- File metadata response: id, filename, meta.content_type, size, user_id.
- File content endpoint: returns raw bytes — note Content-Type header behavior.
KNOWLEDGE:
- Knowledge base endpoints interact with vector store — note which ones trigger embedding/indexing.
- Document the "files" array in knowledge base objects (which file IDs are linked).
- Add/remove files from knowledge base: document the exact request shape.
RETRIEVAL:
- retrieval.py is 2820 lines; it configures the RAG pipeline (embedding models, chunk settings, etc.).
- Prioritize documenting: query endpoint, config GET/POST endpoints, embedding model endpoints.
- For config endpoints: document ALL configuration fields (chunk_size, chunk_overlap, top_k, etc.).
- Document the "process" endpoints (process_doc, process_web, process_youtube) with their request shapes.
Instructions:
1. Read ALL source files listed above.
2. For retrieval.py: focus on public API surface (router endpoints), not internal helper functions.
3. Document file upload endpoints with multipart form fields clearly marked.
4. Trace vector DB config models in retrieval.py to document all configurable fields.
Exit Criteria:
- 4 output files created.
- retrieval.py endpoints fully documented including all config fields.
- File upload endpoints show form-data field names.
- No placeholder or TBD.
Final output format:
- List of files created.
- Count of endpoints documented per file.
- Note any tricky schemas (nested config objects, etc.).

View File

@@ -0,0 +1,98 @@
Phase 5 Mission:
Generate detailed API reference documentation for AI provider endpoints: Ollama, OpenAI-compatible, Audio, and Images.
Prerequisites:
- api_docs/00_route_index.md must already exist (from Phase 1).
Source files to read (fully):
- backend/open_webui/routers/ollama.py (~1884 lines)
- backend/open_webui/routers/openai.py (~1466 lines)
- backend/open_webui/routers/audio.py (~1397 lines)
- backend/open_webui/routers/images.py (~1164 lines)
Output files to create under api_docs/:
- 05_ollama.md
- 05_openai.md
- 05_audio.md
- 05_images.md
Per-endpoint format:
---
### {HTTP_METHOD} {full_path}
**Summary:** One sentence description.
**Auth:** Admin only | Verified user | Public
**Request**
| Location | Field | Type | Required | Description |
|----------|-------|------|----------|-------------|
| Body | field_name | type | Yes/No | description |
**Response `200`**
```json
{
"example_field": "example_value"
}
```
| Field | Type | Description |
|-------|------|-------------|
| field_name | type | description |
**Streaming:** Yes / No *(add this line for endpoints that support SSE/streaming)*
**Error Responses**
| Status | Meaning |
|--------|---------|
| 401 | Not authenticated |
| 503 | Upstream provider unavailable |
---
Special notes for this phase:
OLLAMA:
- Endpoints are mostly pass-through proxies to Ollama's own API.
- Document which endpoints are admin-only (model management) vs user-accessible (generate/chat).
- For streaming endpoints (generate, chat), note: "Supports SSE streaming via stream=true."
- Document the model pull/push/delete management endpoints carefully.
OPENAI:
- Endpoints proxy to configured OpenAI-compatible backend.
- Document the /api/openai/models endpoint (returns merged model list).
- Note which endpoints pass through request body to upstream unchanged.
- Document admin endpoints for adding/removing OpenAI API connections.
AUDIO:
- Document: transcription (STT), TTS synthesis, and audio config endpoints.
- For file upload endpoints: specify multipart/form-data field names.
- Document supported audio formats and any size limits visible in code.
- Note: Engine types (openai, whisper, etc.) and configuration endpoints.
IMAGES:
- Document: image generation endpoints and image engine config.
- Note DALL-E vs ComfyUI vs Automatic1111 backend differences if documented in code.
- Document image config GET/POST: size, steps, model, and other parameters.
Instructions:
1. Read each file fully — they are complex proxying routers.
2. For pass-through proxy routes: still document the expected request/response shape.
3. Distinguish between admin configuration routes and user-facing generation routes.
4. Streaming endpoints must be clearly marked with "Streaming: Yes" and note the SSE event format.
Exit Criteria:
- 4 output files created.
- Every route from 00_route_index.md for these modules is covered.
- Streaming endpoints clearly annotated.
- No placeholder or TBD.
Final output format:
- List of files created.
- Count of endpoints documented per file.
- Note streaming endpoints count per module.

View File

@@ -0,0 +1,103 @@
Phase 6 Mission:
Generate detailed API reference documentation for tools, functions, pipelines, skills, and tasks endpoints.
Prerequisites:
- docs/open_webui_api/00_route_index.md must already exist (from Phase 1).
- NOTE: Output directory is api_docs/ (not docs/open_webui_api/).
Source files to read (fully):
- backend/open_webui/routers/tools.py (~868 lines)
- backend/open_webui/routers/functions.py (~605 lines)
- backend/open_webui/routers/pipelines.py (~540 lines)
- backend/open_webui/routers/skills.py (~447 lines)
- backend/open_webui/routers/tasks.py (~764 lines)
- backend/open_webui/models/tools.py
- backend/open_webui/models/functions.py
- backend/open_webui/models/skills.py
Output files to create under api_docs/:
- 06_tools.md
- 06_functions.md
- 06_pipelines.md
- 06_skills.md
- 06_tasks.md
Per-endpoint format:
---
### {HTTP_METHOD} {full_path}
**Summary:** One sentence description.
**Auth:** Admin only | Verified user | Public
**Request**
| Location | Field | Type | Required | Description |
|----------|-------|------|----------|-------------|
| Body | field_name | type | Yes/No | description |
**Response `200`**
```json
{
"example_field": "example_value"
}
```
| Field | Type | Description |
|-------|------|-------------|
| field_name | type | description |
**Error Responses**
| Status | Meaning |
|--------|---------|
| 401 | Not authenticated |
| 404 | Resource not found |
---
Special notes for this phase:
TOOLS:
- Tools are user-created Python functions exposed to LLM. Document CRUD operations.
- The tool "specs" field: document its structure (list of OpenAI function call specs).
- Document the "export" endpoint if present.
FUNCTIONS:
- Functions include filters, actions, pipes registered by admin.
- Document the `type` field values: "filter", "action", "pipe".
- Document the `meta` and `valves` fields structure.
PIPELINES:
- Pipelines connect to external pipeline servers.
- Document: add pipeline (URL + API key), list pipelines, get valves, set valves.
- Note: pipelines proxy through to an external server; document that behavior.
SKILLS:
- Skills are agent-style plugins with multi-step execution.
- Document the skills schema: name, content (Python source), meta.
- Note if there's a "call" endpoint for executing a skill.
TASKS:
- Tasks module handles background processing (title generation, tag generation, etc.).
- Document config endpoints (GET/POST for task-specific LLM settings).
- Document any direct invocation endpoints.
Instructions:
1. Read all source files fully.
2. For valves/specs/meta fields with complex structure, show the full nested schema.
3. Distinguish admin-only CRUD from user-accessible execution endpoints.
4. For endpoints that execute code (tools, functions, skills), clearly note security implications.
Exit Criteria:
- 5 output files created.
- Every route from 00_route_index.md for these modules is covered.
- Complex nested schemas (valves, specs, meta) fully documented.
- No placeholder or TBD.
Final output format:
- List of files created.
- Count of endpoints documented per file.

View File

@@ -0,0 +1,109 @@
Phase 7 Mission:
Generate detailed API reference documentation for configuration, prompts, evaluations, analytics, SCIM, and utility endpoints.
Prerequisites:
- api_docs/00_route_index.md must already exist (from Phase 1).
Source files to read (fully):
- backend/open_webui/routers/configs.py (~548 lines)
- backend/open_webui/routers/prompts.py (~759 lines)
- backend/open_webui/routers/evaluations.py (~466 lines)
- backend/open_webui/routers/analytics.py (~454 lines)
- backend/open_webui/routers/scim.py (~1030 lines)
- backend/open_webui/routers/utils.py (~123 lines)
- backend/open_webui/models/prompts.py
- backend/open_webui/config.py (for config field definitions)
Output files to create under api_docs/:
- 07_configs.md
- 07_prompts.md
- 07_evaluations.md
- 07_analytics.md
- 07_scim.md
- 07_utils.md
Per-endpoint format:
---
### {HTTP_METHOD} {full_path}
**Summary:** One sentence description.
**Auth:** Admin only | Verified user | Public
**Request**
| Location | Field | Type | Required | Description |
|----------|-------|------|----------|-------------|
| Body | field_name | type | Yes/No | description |
**Response `200`**
```json
{
"example_field": "example_value"
}
```
| Field | Type | Description |
|-------|------|-------------|
| field_name | type | description |
**Error Responses**
| Status | Meaning |
|--------|---------|
| 401 | Not authenticated |
| 404 | Resource not found |
---
Special notes for this phase:
CONFIGS:
- This is the most important module in this phase.
- The global config GET/POST endpoints control system-wide settings.
- Read backend/open_webui/config.py to enumerate ALL configurable fields.
- Document every config field with its type, default, and effect.
- Group config fields by category (auth, RAG, models, UI, etc.) in the output.
PROMPTS:
- System prompts stored by users.
- Document CRUD operations and the command field (trigger word like "/summarize").
- Note the "access_control" field structure.
EVALUATIONS:
- Feedback/rating data for model responses.
- Document the feedback object structure (rating, comment, model_id, etc.).
- Note any aggregation/analytics endpoints.
ANALYTICS:
- Usage statistics endpoints.
- Document what metrics are tracked and aggregation options.
SCIM:
- SCIM 2.0 protocol for enterprise user/group provisioning.
- Document: /Users, /Groups, /ServiceProviderConfig, /ResourceTypes endpoints.
- Note: SCIM uses different Content-Type and auth mechanism — document these.
- Follow SCIM 2.0 RFC schema format for user/group objects.
UTILS:
- Miscellaneous utility endpoints.
- Document all available utilities (markdown renderer, code executor, etc.).
Instructions:
1. Read config.py in addition to router files to get complete field lists.
2. For SCIM: follow SCIM 2.0 RFC conventions in documentation format.
3. For configs: produce a separate "All Config Fields" appendix table.
Exit Criteria:
- 6 output files created.
- configs.md includes appendix table of ALL config fields with defaults.
- scim.md follows SCIM 2.0 documentation conventions.
- No placeholder or TBD.
Final output format:
- List of files created.
- Count of endpoints documented per file.
- Count of config fields documented in configs.md appendix.

View File

@@ -0,0 +1,89 @@
Phase 8 Mission:
Consolidate all previously generated phase outputs into a polished master index and a machine-readable summary.
Prerequisites:
- ALL phase 1~7 output files must exist under api_docs/.
- Specifically, these files must exist:
- api_docs/00_route_index.md
- api_docs/02_auths.md, 02_users.md, 02_groups.md, 02_models.md
- api_docs/03_chats.md, 03_channels.md, 03_memories.md, 03_notes.md
- api_docs/04_files.md, 04_folders.md, 04_knowledge.md, 04_retrieval.md
- api_docs/05_ollama.md, 05_openai.md, 05_audio.md, 05_images.md
- api_docs/06_tools.md, 06_functions.md, 06_pipelines.md, 06_skills.md, 06_tasks.md
- api_docs/07_configs.md, 07_prompts.md, 07_evaluations.md, 07_analytics.md, 07_scim.md, 07_utils.md
Output files to create/update under api_docs/:
1. api_docs/README.md — human-readable master index
2. api_docs/openwebui_api.json — machine-readable OpenAPI-style JSON summary
Content of README.md:
- Title: "OpenWebUI Backend API Reference"
- Subtitle: "Auto-generated from source code. Do not edit manually."
- Generation date (today's date)
- Table of Contents (links to every .md file above)
- Statistics:
- Total module count
- Total route count (from 00_route_index.md)
- Admin-only route count
- Public route count
- Streaming endpoint count
- Quick Reference: a condensed table of the 20 most commonly used endpoints (chat creation, message send, file upload, model list, auth login/logout, etc.)
- Authentication Guide section:
- How to get a JWT token (reference auths.md)
- How to include it in requests (Authorization: Bearer <token>)
- Token expiry behavior
- Common Patterns section:
- Pagination (skip/limit parameters)
- Error response shape: {detail: string}
- Rate limiting (if documented in code)
Content of openwebui_api.json:
A JSON object with this structure:
{
"meta": {
"generated_date": "YYYY-MM-DD",
"source": "backend/open_webui/routers/",
"total_routes": <number>,
"modules": [<list of module names>]
},
"routes": [
{
"module": "auths",
"method": "POST",
"path": "/api/v1/auths/signin",
"handler": "signin",
"auth_required": false,
"auth_type": "public",
"summary": "Authenticate user and return JWT token.",
"request_body": {
"email": {"type": "str", "required": true},
"password": {"type": "str", "required": true}
},
"response_200": {
"token": {"type": "str"},
"token_type": {"type": "str"},
"id": {"type": "str"}
},
"streaming": false
}
]
}
- Include ALL routes from all modules.
- For streaming endpoints: "streaming": true.
Instructions:
1. Read ALL generated phase output files (00 through 07).
2. Parse or summarize endpoint data from each file to populate the JSON.
3. Write README.md with complete statistics and quick reference.
4. Validate: total_routes in README.md must match count in openwebui_api.json.
Exit Criteria:
- api_docs/README.md exists with statistics and ToC.
- api_docs/openwebui_api.json exists with all routes (valid JSON).
- Route counts in README.md and JSON are consistent.
- No placeholder or TBD.
Final output format:
- Confirmation of files created.
- Total routes count in JSON.
- Any modules with missing or incomplete data (for manual review).