mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-25 05:25:40 -04:00
Riskey
32e1b169da
* docs: correct HITL API integration flow and sync translations
- Fix the claim that the resume endpoint differs per app type (same
endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
(chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
returns 404); add include_state_snapshot and continue_on_pause
guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page
* fix: correct API references against verified backend behavior
Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.
- Add curl samples for GET endpoints with required query params
(Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
string; DELETE /conversations requires a JSON body; audio-to-text
accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
created_by_account filters by email; triggered_from values are
app-run/webhook/schedule/plugin; stop endpoints' user semantics
differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
403, file preview endpoint in the workflow spec, invented
score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
values, no response-field enums)
* fix: complete API reference audit for knowledge and completion specs
* feat: add API spec consolidation pipeline
Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.
* feat: consolidate API reference into one spec per language
Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.
* fix: remove dead conversation_completed error from chat specs
ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.
* feat: add membership matrix and restructure nav config
* feat: rename resource tags and update all references
* feat: stamp per-operation availability lines
* feat: wire three-group API navigation
* feat: add app-type page coverage lint
* docs: rewrite chatflow overview as app-type API guide
* docs: polish chatflow overview zh and ja wording
* docs: rewrite workflow overview as app-type API guide
* docs: align workflow overview details across languages
* docs: expand new agent overview into app-type API guide
* docs: use task-oriented heading on new agent overview
* docs: rewrite chatbot and agent overview as app-type API guide
* docs: rewrite text generator overview as app-type API guide
* docs: match end user link text to merged spec summary
* docs: rewrite knowledge overview as app-type API guide
* docs: move knowledge api guide into api reference
* docs: localize ui labels on knowledge overview
* docs: refresh pipeline readme for restructure modes
* docs: name app-type pages in the guides sidebar
* feat: rename zh completion messages tag to match resource framing
* docs: prototype endpoints-first layout on chatflow overview
* docs: correct detail accuracy on chatflow overview
* docs: move human input flow guide into api reference
Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.
* fix: update spec links to the moved human input guide
* fix: let spec lint accept mdx guide pages under api-reference
* docs: align chatflow zh and ja overviews to endpoints-first layout
* docs: polish chatflow zh and ja mode terms and hitl wording
* docs: align workflow overviews to endpoints-first layout
* docs: document form expiry path in human input flow guide
* docs: align new agent overviews to endpoints-first layout
* docs: align chatbot and agent overviews to endpoints-first layout
* docs: align text generator overviews to endpoints-first layout
* docs: align knowledge overviews to endpoints-first layout
* docs: correct built-in metadata examples and agent heading
* docs: flatten app-type pages directly under guides
* docs: make guide pages self-contained and trim reference detail
* docs: add get started guide and retire developing-with-apis
* docs: update new agent api behavior for latest main
New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.
* docs: audit fixes for get started and human input flow guides
* docs: fix em dash spacing and ja sentence length in get started
* docs: move message_end note to the send endpoint line
* docs: update writing guides and API skill for app-type naming
- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.
* feat: add operation sidebar titles and simplify API redirects
- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).
* docs: correct app-type naming and translations across API specs
- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.
* docs: add streaming, errors, and end-user identity API guides
- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.
* docs: reconcile API guides and apply app-type naming
- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.
* feat: wire API nav and redirects for consolidated guides
- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.
* fix: normalize zh model-provider term to 模型供应商
Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.
* docs: use Info callouts for guide forward-link notes
Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.
* refactor: remove one-time analyze mode and verification compose
- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.
* fix: correct Chatflow naming and reasoning wording in SSE overrides
- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".
* docs: refine API guide wording and simplify the human-input example
* docs: standardize Workflow and Chatflow app-type capitalization
Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.
* fix: use 供应商 for model provider in the zh Knowledge spec
* fix: rename the Knowledge API nav group to "Knowledge APIs"
* fix: un-deprecate Update Document by Text in the Knowledge spec
* translate: un-deprecate Update Document by Text in zh/ja specs
Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
118 lines
9.6 KiB
Plaintext
118 lines
9.6 KiB
Plaintext
---
|
|
title: Knowledge API
|
|
sidebarTitle: Knowledge
|
|
description: API for managing knowledge bases, documents, chunks, metadata, tags, and knowledge pipelines
|
|
---
|
|
|
|
Build and maintain [knowledge bases](/en/cloud/use-dify/knowledge/readme) from your own code, without going through the Dify console: create a knowledge base, load documents and chunks into it, organize them with metadata and tags, and query it directly for search or RAG.
|
|
|
|
<Note>
|
|
A single Knowledge Base API key has access to every knowledge base visible to the account that created the key. Handle your keys carefully to avoid unintended data exposure.
|
|
</Note>
|
|
|
|
## Get Your API Endpoint and Key
|
|
|
|
In **Knowledge**, click **Service API** in the top-right corner to open the API configuration panel. From here:
|
|
|
|
- Copy the Service API endpoint, the base URL for every Knowledge API request.
|
|
- Click **API Key** to create and manage keys.
|
|
|
|
<Warning>
|
|
Store your API key securely on the server side. Never expose it in client-side code or public repositories.
|
|
</Warning>
|
|
|
|
## Manage API Access for a Knowledge Base
|
|
|
|
Every knowledge base is reachable through the API by default. To restrict a specific knowledge base, open it, click **API Access** in the bottom-left corner, and turn the toggle off.
|
|
|
|
## Create and Manage Knowledge Bases
|
|
|
|
- **[Create an Empty Knowledge Base](/en/api-reference/knowledge-bases/create-an-empty-knowledge-base)**: create a knowledge base with no documents yet.
|
|
- **[List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)**: a paginated list, filterable by keyword or tag.
|
|
- **[Get Knowledge Base](/en/api-reference/knowledge-bases/get-knowledge-base)**: one knowledge base's embedding model, retrieval configuration, and document statistics.
|
|
- **[Update Knowledge Base](/en/api-reference/knowledge-bases/update-knowledge-base)**: change the name, permissions, embedding model, or retrieval settings; only the fields you provide are updated.
|
|
- **[Delete Knowledge Base](/en/api-reference/knowledge-bases/delete-knowledge-base)**: permanently remove a knowledge base and every document inside it.
|
|
- **[Retrieve Chunks from a Knowledge Base / Test Retrieval](/en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval)**: search a knowledge base and return the most relevant chunks—the same endpoint serves production retrieval and retrieval testing.
|
|
|
|
## Add and Update Documents
|
|
|
|
Document creation is asynchronous. Create the document, then poll until indexing finishes:
|
|
|
|
<Steps>
|
|
<Step title="Create a knowledge base">
|
|
Call [Create an Empty Knowledge Base](/en/api-reference/knowledge-bases/create-an-empty-knowledge-base), or use an existing knowledge base.
|
|
</Step>
|
|
<Step title="Add a document">
|
|
Call [Create Document by Text](/en/api-reference/documents/create-document-by-text) or [Create Document by File](/en/api-reference/documents/create-document-by-file); both return a `batch` ID.
|
|
|
|
If you didn't set `indexing_technique` (how content is indexed for search) when creating the knowledge base, set it on this first document; later documents inherit it automatically.
|
|
</Step>
|
|
<Step title="Poll the indexing status">
|
|
Poll [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status) with the `batch` ID until `indexing_status` reaches `completed` or `error`; it progresses through `waiting`, `parsing`, `cleaning`, `splitting`, and `indexing` along the way.
|
|
</Step>
|
|
</Steps>
|
|
|
|
- **[List Documents](/en/api-reference/documents/list-documents)**: a paginated list, filterable by keyword or indexing status.
|
|
- **[Get Document](/en/api-reference/documents/get-document)**: one document's indexing status, metadata, and processing statistics; the `metadata` query parameter includes, omits, or returns only the metadata fields.
|
|
- **[Download Document](/en/api-reference/documents/download-document)**: a signed URL for the document's original uploaded file.
|
|
- **[Download Documents as ZIP](/en/api-reference/documents/download-documents-as-zip)**: bundle up to 100 uploaded-file documents into a single archive.
|
|
- **[Update Document](/en/api-reference/documents/update-document)**: replace a document's content by uploading a new file, re-triggering indexing; the canonical way to update a file-based document.
|
|
- **[Update Document by Text](/en/api-reference/documents/update-document-by-text)**: update a document's text content, name, or processing configuration inline; re-triggers indexing when the content changes.
|
|
- **[Update Document by File](/en/api-reference/documents/update-document-by-file)**: deprecated alias for uploading a replacement file; use Update Document instead.
|
|
- **[Update Document Status in Batch](/en/api-reference/documents/update-document-status-in-batch)**: enable, disable, archive, or unarchive multiple documents at once.
|
|
- **[Delete Document](/en/api-reference/documents/delete-document)**: permanently remove a document and every chunk inside it.
|
|
|
|
## Manage Chunks and Child Chunks
|
|
|
|
- **[Create Chunks](/en/api-reference/chunks/create-chunks)**: add chunks to a document by hand—indexing already chunks uploaded content automatically. Each chunk requires `content`; documents in Q&A mode also require `answer`.
|
|
- **[List Chunks](/en/api-reference/chunks/list-chunks)**: a paginated list, filterable by keyword or status.
|
|
- **[Get Chunk](/en/api-reference/chunks/get-chunk)**: one chunk's content, keywords, and indexing status.
|
|
- **[Update Chunk](/en/api-reference/chunks/update-chunk)**: change a chunk's content, keywords, or answer; re-triggers indexing for that chunk.
|
|
- **[Delete Chunk](/en/api-reference/chunks/delete-chunk)**: permanently remove a chunk.
|
|
|
|
For documents in Parent-child mode (`hierarchical_model`), child chunks nest under a parent chunk. Child chunks you create or update through the API are always typed `customized`, unlike the `automatic` ones the indexing pipeline generates.
|
|
|
|
- **[Create Child Chunk](/en/api-reference/chunks/create-child-chunk)**: add a child chunk under a parent chunk.
|
|
- **[List Child Chunks](/en/api-reference/chunks/list-child-chunks)**: a paginated list of one parent chunk's child chunks.
|
|
- **[Update Child Chunk](/en/api-reference/chunks/update-child-chunk)**: change a child chunk's content.
|
|
- **[Delete Child Chunk](/en/api-reference/chunks/delete-child-chunk)**: permanently remove a child chunk.
|
|
|
|
## Manage Metadata Fields
|
|
|
|
Metadata fields annotate documents with structured information that retrieval can filter on:
|
|
|
|
- **[Create Metadata Field](/en/api-reference/metadata/create-metadata-field)**: add a custom field to the knowledge base, typed `string`, `number`, or `time`.
|
|
- **[List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)**: every field, custom and built-in, with a count of documents using each.
|
|
- **[Update Metadata Field](/en/api-reference/metadata/update-metadata-field)**: rename a custom field.
|
|
- **[Delete Metadata Field](/en/api-reference/metadata/delete-metadata-field)**: remove a custom field; documents lose their values for it.
|
|
- **[Get Built-in Metadata Fields](/en/api-reference/metadata/get-built-in-metadata-fields)**: the system-provided fields, such as `document_name`, `uploader`, and `upload_date`.
|
|
- **[Update Built-in Metadata Field](/en/api-reference/metadata/update-built-in-metadata-field)**: enable or disable built-in fields for the knowledge base.
|
|
- **[Update Document Metadata in Batch](/en/api-reference/metadata/update-document-metadata-in-batch)**: set metadata key-value pairs across multiple documents in a single call.
|
|
|
|
Metadata also works as a stable external key: store your source system's ID on each document, then filter on it in later sync runs to find and update the same documents.
|
|
|
|
## Organize Knowledge Bases with Tags
|
|
|
|
Tags live at the workspace level, independent of any single knowledge base:
|
|
|
|
- **[Create Knowledge Tag](/en/api-reference/tags/create-knowledge-tag)**: create a tag for organizing knowledge bases.
|
|
- **[List Knowledge Tags](/en/api-reference/tags/list-knowledge-tags)**: every tag in the workspace.
|
|
- **[Update Knowledge Tag](/en/api-reference/tags/update-knowledge-tag)**: rename a tag.
|
|
- **[Delete Knowledge Tag](/en/api-reference/tags/delete-knowledge-tag)**: remove a tag from every knowledge base it was bound to, without deleting those knowledge bases.
|
|
- **[Create Tag Binding](/en/api-reference/tags/create-tag-binding)**: bind one or more tags to a knowledge base; a knowledge base can carry multiple tags.
|
|
- **[Delete Tag Binding](/en/api-reference/tags/delete-tag-binding)**: remove tags from a knowledge base.
|
|
- **[Get Knowledge Base Tags](/en/api-reference/tags/get-knowledge-base-tags)**: the tags currently bound to one knowledge base.
|
|
|
|
## Look Up Available Models
|
|
|
|
- **[Get Available Models](/en/api-reference/models/get-available-models)**: the models available for a given `model_type`; query `text-embedding` for embedding models or `rerank` for reranking models when configuring a knowledge base.
|
|
|
|
## Run the Knowledge Pipeline
|
|
|
|
A knowledge pipeline is a workflow that ingests data from a datasource and turns it into documents:
|
|
|
|
- **[Upload Pipeline File](/en/api-reference/knowledge-pipeline/upload-pipeline-file)**: upload a file for the pipeline to process.
|
|
- **[List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)**: the datasource nodes configured in the pipeline—published by default, or the draft version with `is_published=false`.
|
|
- **[Run Datasource Node](/en/api-reference/knowledge-pipeline/run-datasource-node)**: execute a single datasource node and stream its results, useful for testing one step in isolation.
|
|
- **[Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline)**: execute the full pipeline in `streaming` or `blocking` response mode; `is_published` picks the published version or the current draft.
|