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.