Dify API catalog (1.17)
Use this to pick the right prefix and skill. Do not invent HTTP. Re-scan api/controllers in your Dify checkout if the tree moved.
Login / CSRF: Dify console API. Workspace Skills / Agent roster / RAG pipeline / MCP / members: Dify workspace extras.
Prefixes and auth
| ns |
Prefix (nginx) |
Auth |
Call from |
| console |
/console/api |
Cookie + X-CSRF-Token |
You as admin |
| service |
/v1 |
Authorization: Bearer app or dataset key |
Published callers |
| web |
/api |
WebApp passport / site token |
Share site, not console |
| openapi |
/openapi/v1 |
OAuth bearer (difyctl); needs OPENAPI_ENABLED + ENABLE_OAUTH_BEARER |
CLI / OAuth clients |
| files |
/files |
Signed URL or session |
Previews, plugin uploads |
| mcp |
/mcp or /server/{code}/mcp |
MCP server_code |
MCP clients |
| inner |
plugin_daemon ↔ api only |
Internal key |
Never call from the host as a product API |
| blueprints |
/webhook/{id}, /webhook-debug/{id}, /plugin/{endpoint_id}, /oauth/device/*, /knowledge-fs/* |
Each its own |
Triggers / plugin HTTP / SSO |
Community: /workspaces/current/rbac/* and /billing/* 403 or empty. That is not a license unlock.
? in the dump means the scanner missed the def (often POST/PUT next to GET). Confirm in the controller before claiming a method.
Console groups → skill
All paths below are under /console/api.
| Prefix |
Skill |
/login, /logout, /refresh-token, /account/*, /setup, /files/upload |
Dify console API |
/apps, /apps/{id}/workflows/*, /apps/imports, /apps/{id}/triggers |
Dify apps and workflows |
/datasets, /datasets/{id}/documents, /datasets/{id}/hit-testing |
Dify knowledge bases |
/rag/pipelines, /rag/pipeline/*, /auth/plugin/datasource |
Dify workspace extras (RAG pipeline) + knowledge bases |
/workspaces/current/model-providers, /default-model |
Dify model providers |
/workspaces/current/tool-providers, /workspaces/current/triggers |
Dify agents and tools |
/workspaces/current/plugin/* |
Dify plugin install |
/agent, /agent/{id}/*, /apps/{id}/server, /workspaces/current/skills |
Dify workspace extras + agents and tools |
/workspaces/current/customized-snippets, /snippets/{id}/workflows |
Dify workspace extras |
/apps/{id}/chat-conversations, /workflow-app-logs, /workflow-runs, /statistics/*, /workflow/statistics/*, /annotations |
Dify workspace extras |
/apps/{id}/triggers, /apps/{id}/trigger-enable, /apps/{id}/workflows/triggers/webhook |
Dify apps and workflows |
/v1/* after publish |
Dify service API |
/v1 service API (complete)
Bearer app key: /v1/chat-messages, /v1/completion-messages, /v1/workflows/run (+ /{id} and /{workflow_id}/run), stop, /v1/workflows/logs, /v1/workflow/{task_id}/events, /v1/conversations (+ name, variables), /v1/messages (+ feedbacks, suggested), /v1/files/upload, /v1/files/{id}/preview, /v1/audio-to-text, /v1/text-to-audio, /v1/parameters, /v1/info, /v1/meta, /v1/site, /v1/form/human_input/{form_token}, /v1/apps/annotations*.
Bearer dataset key: /v1/datasets, documents (create-by-text / create-by-file and snake_case aliases), segments + child_chunks, retrieve / hit-testing, metadata, tags.
WebApp /api
Same shapes as chat/workflow, but site token. Also /api/passport, /api/login, /api/webapp/access-mode, saved-messages, pin/unpin, more-like-this.
OpenAPI /openapi/v1
GET /_health, /_version, workspaces, apps, :run / :stop, DSL import (:confirm, dependencies:check), human-input-forms, device OAuth. Off unless both env flags are on.
MCP
Enable on an app: GET/POST/PUT /console/api/apps/{id}/server, rotate POST .../server/refresh. Clients hit POST /mcp/server/{server_code}/mcp.
Inner API
/invoke/llm, /invoke/tool, /agent-config/*, /skills/{id}/pull, /enterprise/*. plugin_daemon only. A 401 here is expected from the host.
How to look up
- Match the prefix table.
- Open the matching skill. Do not copy a console path onto
/v1.
- If still missing,
rg '@console_ns.route' api/controllers in the Dify source tree. Re-scan beats guessing methods.
1---2name: dify-api-catalog3description: Use this when looking up Dify 1.17 HTTP prefixes, auth, or which skill owns a route (console, /v1, WebApp, OpenAPI, MCP, inner API).4---5# Dify API catalog (1.17)67Use this to pick the right prefix and skill. Do not invent HTTP. Re-scan `api/controllers` in your Dify checkout if the tree moved.89Login / CSRF: [Dify console API](sand-workflow:dify-console-api). Workspace Skills / Agent roster / RAG pipeline / MCP / members: [Dify workspace extras](sand-workflow:dify-workspace-extras).1011## Prefixes and auth1213| ns | Prefix (nginx) | Auth | Call from |14|---|---|---|---|15| console | `/console/api` | Cookie + `X-CSRF-Token` | You as admin |16| service | `/v1` | `Authorization: Bearer` app or dataset key | Published callers |17| web | `/api` | WebApp passport / site token | Share site, not console |18| openapi | `/openapi/v1` | OAuth bearer (`difyctl`); needs `OPENAPI_ENABLED` + `ENABLE_OAUTH_BEARER` | CLI / OAuth clients |19| files | `/files` | Signed URL or session | Previews, plugin uploads |20| mcp | `/mcp` or `/server/{code}/mcp` | MCP `server_code` | MCP clients |21| inner | plugin_daemon ↔ api only | Internal key | **Never call from the host as a product API** |22| blueprints | `/webhook/{id}`, `/webhook-debug/{id}`, `/plugin/{endpoint_id}`, `/oauth/device/*`, `/knowledge-fs/*` | Each its own | Triggers / plugin HTTP / SSO |2324Community: `/workspaces/current/rbac/*` and `/billing/*` 403 or empty. That is not a license unlock.2526`?` in the dump means the scanner missed the `def` (often POST/PUT next to GET). Confirm in the controller before claiming a method.2728## Console groups → skill2930All paths below are under `/console/api`.3132| Prefix | Skill |33|---|---|34| `/login`, `/logout`, `/refresh-token`, `/account/*`, `/setup`, `/files/upload` | Dify console API |35| `/apps`, `/apps/{id}/workflows/*`, `/apps/imports`, `/apps/{id}/triggers` | Dify apps and workflows |36| `/datasets`, `/datasets/{id}/documents`, `/datasets/{id}/hit-testing` | Dify knowledge bases |37| `/rag/pipelines`, `/rag/pipeline/*`, `/auth/plugin/datasource` | Dify workspace extras (RAG pipeline) + knowledge bases |38| `/workspaces/current/model-providers`, `/default-model` | Dify model providers |39| `/workspaces/current/tool-providers`, `/workspaces/current/triggers` | Dify agents and tools |40| `/workspaces/current/plugin/*` | Dify plugin install |41| `/agent`, `/agent/{id}/*`, `/apps/{id}/server`, `/workspaces/current/skills` | Dify workspace extras + agents and tools |42| `/workspaces/current/customized-snippets`, `/snippets/{id}/workflows` | Dify workspace extras |43| `/apps/{id}/chat-conversations`, `/workflow-app-logs`, `/workflow-runs`, `/statistics/*`, `/workflow/statistics/*`, `/annotations` | Dify workspace extras |44| `/apps/{id}/triggers`, `/apps/{id}/trigger-enable`, `/apps/{id}/workflows/triggers/webhook` | Dify apps and workflows |45| `/v1/*` after publish | Dify service API |4647## `/v1` service API (complete)4849Bearer app key: `/v1/chat-messages`, `/v1/completion-messages`, `/v1/workflows/run` (+ `/{id}` and `/{workflow_id}/run`), stop, `/v1/workflows/logs`, `/v1/workflow/{task_id}/events`, `/v1/conversations` (+ name, variables), `/v1/messages` (+ feedbacks, suggested), `/v1/files/upload`, `/v1/files/{id}/preview`, `/v1/audio-to-text`, `/v1/text-to-audio`, `/v1/parameters`, `/v1/info`, `/v1/meta`, `/v1/site`, `/v1/form/human_input/{form_token}`, `/v1/apps/annotations*`.5051Bearer dataset key: `/v1/datasets`, documents (`create-by-text` / `create-by-file` and snake_case aliases), segments + child_chunks, retrieve / hit-testing, metadata, tags.5253## WebApp `/api`5455Same shapes as chat/workflow, but site token. Also `/api/passport`, `/api/login`, `/api/webapp/access-mode`, saved-messages, pin/unpin, more-like-this.5657## OpenAPI `/openapi/v1`5859`GET /_health`, `/_version`, workspaces, apps, `:run` / `:stop`, DSL import (`:confirm`, `dependencies:check`), human-input-forms, device OAuth. Off unless both env flags are on.6061## MCP6263Enable on an app: `GET/POST/PUT /console/api/apps/{id}/server`, rotate `POST .../server/refresh`. Clients hit `POST /mcp/server/{server_code}/mcp`.6465## Inner API6667`/invoke/llm`, `/invoke/tool`, `/agent-config/*`, `/skills/{id}/pull`, `/enterprise/*`. plugin_daemon only. A 401 here is expected from the host.6869## How to look up70711. Match the prefix table.722. Open the matching skill. Do not copy a console path onto `/v1`.733. If still missing, `rg '@console_ns.route' api/controllers` in the Dify source tree. Re-scan beats guessing methods.
kabishou11