Dify Knowledge Pipeline API
Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. 4 operation(s) from the Dify Service API.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/dify-knowledge-pipeline-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.0.1
info:
title: Dify Knowledge Pipeline API
description: REST API for Dify applications and knowledge bases. Application endpoints authenticate
with an app API key; knowledge endpoints authenticate with a dataset API key.
version: 1.0.0
servers:
- url: https://{api_base_url}
description: Base URL of the Dify Service API. For self-hosted deployments, replace it with your own
API base URL.
variables:
api_base_url:
default: api.dify.ai/v1
description: Host and path of the API base URL, without the `https://` prefix.
security:
- ApiKeyAuth: []
tags:
- name: Knowledge Pipeline
description: Operations for managing and running knowledge pipelines, including datasource plugins and
pipeline execution.
paths:
/datasets/pipeline/file-upload:
post:
tags:
- Knowledge Pipeline
summary: Upload Pipeline File
description: Uploads a file for use in a knowledge pipeline. Use the returned `id` as the `reference`
of a `local_file` item in [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline).
operationId: uploadPipelineFile
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: 'The file to upload, as one `multipart/form-data` part. Document files
are capped at 15 MB by default.
Self-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment
variable](/en/self-host/deploy/configuration/environments).
On Dify Cloud, Professional and Team plans raise the document cap to 50 MB. Images,
audio, and video follow their own limits: 10 MB, 50 MB, and 100 MB by default.'
responses:
'201':
description: File uploaded successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique identifier of the uploaded file.
name:
type: string
description: Original file name.
size:
type: integer
description: File size in bytes.
extension:
type: string
description: File extension.
mime_type:
type: string
nullable: true
description: MIME type of the file. May be `null` if the upload did not include one.
created_by:
type: string
description: ID of the user who uploaded the file.
created_at:
type: string
nullable: true
description: Upload timestamp in ISO 8601 format. May be `null` while the record is
being created.
examples:
success:
summary: Response Example
value:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: report.pdf
size: 524288
extension: pdf
mime_type: application/pdf
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: '2025-03-06T12:00:00'
'400':
description: '- `no_file_uploaded` : No file was provided in the request.
- `filename_not_exists_error` : The uploaded file has no filename.
- `too_many_files` : Only one file is allowed per request.'
content:
application/json:
examples:
no_file_uploaded:
summary: no_file_uploaded
value:
status: 400
code: no_file_uploaded
message: Please upload your file.
filename_not_exists_error:
summary: filename_not_exists_error
value:
status: 400
code: filename_not_exists_error
message: The specified filename does not exist.
too_many_files:
summary: too_many_files
value:
status: 400
code: too_many_files
message: Only one file is allowed.
'413':
description: '`file_too_large` : The file exceeds the upload size limit.'
content:
application/json:
examples:
file_too_large:
summary: file_too_large
value:
status: 413
code: file_too_large
message: File size exceeded.
'415':
description: '`unsupported_file_type` : The file type is not supported.'
content:
application/json:
examples:
unsupported_file_type:
summary: unsupported_file_type
value:
status: 415
code: unsupported_file_type
message: File type not allowed.
x-mint:
href: /en/api-reference/knowledge-pipeline/upload-pipeline-file
metadata:
title: Upload Pipeline File
sidebarTitle: Upload Pipeline File
/datasets/{dataset_id}/pipeline/datasource-plugins:
get:
tags:
- Knowledge Pipeline
summary: List Datasource Plugins
description: Returns the datasource nodes configured in the knowledge pipeline, each with the plugin
it uses and the metadata needed to run it.
operationId: listDatasourcePlugins
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: is_published
in: query
schema:
type: boolean
default: true
description: Whether to read nodes from the published pipeline version rather than the draft.
responses:
'200':
description: List of datasource nodes configured in the pipeline.
content:
application/json:
schema:
type: array
items:
type: object
properties:
node_id:
type: string
description: ID of the datasource node in the pipeline workflow. Pass this as `node_id`
to [Run Datasource Node](/en/api-reference/knowledge-pipeline/run-datasource-node),
or as `start_node_id` to [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline).
plugin_id:
type: string
description: ID of the datasource plugin providing this node.
provider_name:
type: string
description: Provider name registered by the datasource plugin.
datasource_type:
type: string
description: Type of datasource. One of `local_file`, `online_document`, `online_drive`,
`website_crawl`.
title:
type: string
description: Display title configured for the node.
user_input_variables:
type: array
description: Pipeline input variables the caller must supply for this datasource,
derived from `{{#...#}}` references in the node's datasource parameters. Each
item follows the pipeline variable schema used by the workflow.
items:
type: object
additionalProperties: true
credentials:
type: array
description: Credentials available for authenticating with this datasource.
items:
type: object
properties:
id:
type: string
description: Credential ID. Pass this as `credential_id` to [Run Datasource
Node](/en/api-reference/knowledge-pipeline/run-datasource-node) or in per-item
`credential_id` fields of [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline).
name:
type: string
description: Display name of the credential.
type:
type: string
description: Credential type defined by the datasource plugin.
is_default:
type: boolean
description: Whether this credential is the default for the provider.
examples:
success:
summary: Response Example
value:
- node_id: '1719288585006'
plugin_id: langgenius/notion_datasource
provider_name: notion
datasource_type: online_document
title: Notion Documents
user_input_variables: []
credentials:
- id: c1d2e3f4-a5b6-7890-abcd-ef1234567890
name: Production Notion
type: api-key
is_default: true
'400':
description: '`invalid_param` : The knowledge base has no processing pipeline configured.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: Pipeline not found
'403':
description: '`forbidden` : API access is not enabled for this knowledge base.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '`not_found` : No knowledge base matches `dataset_id`.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/knowledge-pipeline/list-datasource-plugins
metadata:
title: List Datasource Plugins
sidebarTitle: List Datasource Plugins
/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run:
post:
tags:
- Knowledge Pipeline
summary: Run Datasource Node
description: Runs a single datasource node in the knowledge pipeline and streams its execution events.
operationId: runDatasourceNode
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: node_id
in: path
required: true
schema:
type: string
description: ID of the datasource node to run, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- inputs
- datasource_type
- is_published
properties:
inputs:
type: object
additionalProperties: true
description: Input variables for the datasource node.
datasource_type:
type: string
enum:
- online_document
- local_file
- website_crawl
- online_drive
description: Type of the datasource.
credential_id:
type: string
nullable: true
description: ID of the credential to authenticate with the datasource, from the `credentials`
array of [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins).
is_published:
type: boolean
description: Whether to run the published version of the node instead of the draft.
responses:
'200':
description: Streaming response with node execution events.
content:
text/event-stream:
schema:
type: string
description: Server-Sent Events stream of node execution progress and results. See [SSE
Streaming](/en/api-reference/guides/streaming) for parsing.
'400':
description: '`invalid_param` : The knowledge base has no processing pipeline configured, or
the request body failed validation.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: Pipeline not found
'403':
description: '`forbidden` : API access is not enabled for this knowledge base.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '`not_found` : No knowledge base matches `dataset_id`.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/knowledge-pipeline/run-datasource-node
metadata:
title: Run Datasource Node
sidebarTitle: Run Datasource Node
/datasets/{dataset_id}/pipeline/run:
post:
tags:
- Knowledge Pipeline
summary: Run Pipeline
description: Runs the full knowledge pipeline over one or more datasources. `response_mode` selects
a streaming or blocking response.
operationId: runPipeline
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- inputs
- datasource_type
- datasource_info_list
- start_node_id
- is_published
- response_mode
properties:
inputs:
type: object
additionalProperties: true
description: Key-value pairs for pipeline input variables defined in the workflow. Pass
`{}` if the pipeline has no input variables.
datasource_type:
type: string
enum:
- local_file
- online_document
- website_crawl
- online_drive
description: Type of the datasource. Determines which fields are expected in `datasource_info_list`
items.
datasource_info_list:
type: array
description: List of datasource objects to process. The expected item structure depends
on `datasource_type`.
items:
oneOf:
- title: Local File
type: object
required:
- reference
properties:
reference:
type: string
description: Use the `id` returned by the [Upload Pipeline File](/en/api-reference/knowledge-pipeline/upload-pipeline-file)
endpoint. `related_id` is accepted as an alias.
name:
type: string
description: Document title. Defaults to `"untitled"`.
- title: Online Document
type: object
required:
- workspace_id
- page
properties:
workspace_id:
type: string
description: ID of the workspace or database in the external platform (e.g.,
a Notion workspace ID).
page:
type: object
description: Page details.
required:
- page_id
- type
properties:
page_id:
type: string
description: Page identifier.
type:
type: string
description: Page type defined by the datasource plugin (e.g., `"page"`,
`"database"`).
page_name:
type: string
description: Display name. Defaults to `"untitled"`.
credential_id:
type: string
description: Credential for authenticating with the external platform. Managed
via the Dify console. If omitted, the provider's default credential is used.
- title: Website Crawl
type: object
required:
- url
properties:
url:
type: string
description: URL to crawl.
title:
type: string
description: Used as the document name. Defaults to `"untitled"`.
- title: Online Drive
type: object
required:
- id
- type
properties:
id:
type: string
description: File or folder ID.
type:
type: string
enum:
- file
- folder
description: Whether this entry is a single file or a folder to expand.
bucket:
type: string
description: Storage bucket name. Required by some drive providers (e.g., S3-compatible
stores); omit if the provider does not use buckets.
name:
type: string
description: File name. Defaults to `"untitled"`.
start_node_id:
type: string
description: ID of the node to start execution from, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins).
is_published:
type: boolean
description: Whether to run the published version of the pipeline instead of the current
draft. Run the draft to test unpublished changes.
response_mode:
type: string
enum:
- streaming
- blocking
description: Response mode for the pipeline execution. `streaming` returns a Server-Sent
Events stream, `blocking` waits and returns the complete result.
examples:
local_file:
summary: Request Example - Local file
value:
inputs: {}
datasource_type: local_file
datasource_info_list:
- reference: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: quarterly-report.pdf
start_node_id: '1719288585006'
is_published: true
response_mode: blocking
online_document:
summary: Request Example - Online document
value:
inputs: {}
datasource_type: online_document
datasource_info_list:
- workspace_id: ws-abc123
page:
page_id: pg-def456
type: page
page_name: Product Roadmap
credential_id: cred-789xyz
start_node_id: '1719288585006'
is_published: true
response_mode: streaming
website_crawl:
summary: Request Example - Website crawl
value:
inputs: {}
datasource_type: website_crawl
datasource_info_list:
- url: https://example.com/docs/getting-started
title: Getting Started Guide
start_node_id: '1719288585006'
is_published: true
response_mode: blocking
online_drive:
summary: Request Example - Online drive
value:
inputs: {}
datasource_type: online_drive
datasource_info_list:
- id: file-abc123
type: file
bucket: my-bucket
name: meeting-notes.docx
start_node_id: '1719288585006'
is_published: true
response_mode: blocking
responses:
'200':
description: 'Pipeline execution result. Format depends on `response_mode`: streaming returns
a `text/event-stream`, blocking returns a JSON object.'
content:
text/event-stream:
schema:
type: string
description: 'Server-Sent Events stream. Returned when `response_mode` is `streaming`;
see [SSE Streaming](/en/api-reference/guides/streaming) for the wire format.
Key events:
- `workflow_started`: execution began
- `node_started` / `node_finished`: per-node progress with `node_id`, `node_type`, `status`,
`inputs`, `outputs`
- `workflow_finished`: final result with `status`, `outputs`, `total_tokens`, `elapsed_time`
- `ping`: keepalive'
application/json:
schema:
type: object
description: Complete pipeline execution result. Returned when `response_mode` is `blocking`.
additionalProperties: true
examples:
success:
summary: Blocking Response Example
value:
task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
workflow_run_id: f1e2d3c4-b5a6-7890-abcd-ef0987654321
data:
id: f1e2d3c4-b5a6-7890-abcd-ef0987654321
status: succeeded
outputs: {}
created_at: 1741267200
finished_at: 1741267210
'400':
description: '`invalid_param` : The knowledge base has no processing pipeline configured, or
the request body failed validation.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: Pipeline not found
'403':
description: '`forbidden` : API access is not enabled for this knowledge base.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '`not_found` : No knowledge base matches `dataset_id`.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
'500':
description: '`pipeline_run_error` : Pipeline execution failed.'
content:
application/json:
examples:
pipeline_run_error:
summary: pipeline_run_error
value:
status: 500
code: pipeline_run_error
message: 'Pipeline execution failed: connection timeout'
x-mint:
href: /en/api-reference/knowledge-pipeline/run-pipeline
metadata:
title: Run Pipeline
sidebarTitle: Run Pipeline
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: API_KEY
description: 'Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App
endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key
fail with HTTP `401` (`unauthorized`).'
x-provenance:
generated: '2026-09-06'
method: derived
source: openapi/_original/dify-service-api-openapi.json
note: Per-tag split of the first-party Dify Service API OpenAPI harvested from https://docs.dify.ai/en/api-reference/openapi_service.json
(advertised in https://docs.dify.ai/llms.txt). Paths, schemas and operationIds are verbatim from that
spec.