How the External Knowledge API connects Dify to a RAG system you already run
If your documents already sit in a retrieval service or a managed knowledge base, you can let Dify apps query them without re-indexing by using the External Knowledge API. Dify sends a single POST request to {endpoint}/retrieval on your service, passing a knowledge_id, a query and a retrieval_setting object that carries top_k and score_threshold, with an optional metadata_condition. Your service returns the matching chunks, and Dify uses them as context in workflows and chat apps. The integration gives Dify retrieval access only. Dify cannot modify, index, delete or otherwise manage the external content, so updates, permissions on the source and document lifecycle stay with your system.
Before you build the endpoint, settle two decisions that Dify will not let you change later. The External Knowledge API setting and the External Knowledge ID are fixed once the external knowledge base is created, so a wrong endpoint or ID means creating a new knowledge base and re-attaching it to apps. Confirm the exact request and response fields with the Dify External Knowledge API documentation against a test service first. Also decide who owns the retrieval contract, because your team will need to version the endpoint if the retrieval service changes shape.
The API key you configure is sent as a bearer token. Dify passes it along but does not validate it, so your retrieval service must check every request itself and reject calls with missing or wrong keys. Use a dedicated key scoped to retrieval, store it in your secrets manager instead of in exported app files, and plan rotation, since changing the key requires updating the connection. Treat top_k and score_threshold as settings you tune against your own evaluation questions, not as defaults you accept without testing. Confirm with your retrieval vendor how they handle the threshold, because a low value can send irrelevant passages into prompts.
What you need before you register the endpoint
Four things must be settled before Dify can call your retrieval service: a supported self-hosted Dify version on a host that meets the Docker Compose requirements, a retrieval endpoint that answers the POST contract over HTTPS, a named owner for the bearer key, and a network path from Dify's SSRF proxy to the endpoint. Each card below is a decision or check to close first.
Confirm the Dify release
Check the current Dify release on the GitHub releases page before you build, because minor releases arrive roughly monthly and the upgrade guide for each target version may add steps. Build and test against the version you will run in production, and record it in your change record. Confirm that the External Knowledge API behavior you rely on is documented for that version, not only for an older one.
Size the Docker Compose host
The Docker Compose deployment starts the api, worker, web, plugin daemon, PostgreSQL, Redis, Weaviate, Nginx, a code sandbox and an SSRF proxy on one host. Confirm the host meets the documented minimums and runs Docker Compose 2.24.0 or later. Your retrieval service is separate, so plan its capacity independently, since Dify waits on it for every knowledge query.
Build the retrieval endpoint
Your service must accept a single POST request at the path /retrieval under the endpoint you register, carrying the knowledge ID, the query, and the retrieval settings with top K and score threshold. It must answer over HTTPS with a valid certificate that Dify trusts. Test the contract with sample requests, including empty results and unknown knowledge IDs, before you connect it.
Name the bearer key owner
Dify sends the configured API key as a bearer token but does not validate it, so your service is the only place that can reject a bad key. Assign one team to issue, rotate and revoke the key, and store it in your secrets manager rather than in a shared document. Decide who can view the key inside the Dify console, since workspace members with access to the knowledge base settings can see the configuration.
Open the SSRF proxy path
Dify routes outbound requests through an SSRF proxy that blocks internal and private IP ranges, so an endpoint on a private address will fail unless you allow that path deliberately. Ask your network team to permit the proxy to reach only the retrieval host and port. Confirm the allowlisting method in the environment variable reference and test the route from the Dify containers, not from your workstation.
Map knowledge IDs to indexes
Decide which knowledge ID in Dify maps to which index or collection in your retrieval system before you create anything. Each external knowledge base is bound to one External Knowledge API and External Knowledge ID, and neither can be changed after creation. Document the mapping, define who approves new IDs, and confirm that access controls in your index match the audience of each Dify knowledge base.
How to register and test the external knowledge base
This sequence takes a retrieval service you already run and connects it to Dify as an external knowledge base, so a test app can pull chunks from it and you can confirm each request and response along the way.
Build the retrieval endpoint to the request contract
Your team exposes one POST route at a path ending in /retrieval under the base URL you will register. Dify sends knowledge_id, query and retrieval_setting (top_k and score_threshold), and may add metadata_condition. Your service looks up the knowledge_id in its own index and returns a list of chunks with content, title, score and metadata. Confirm the contract with a manual request using curl against a staging copy of the service, and check that the response parses into the fields Dify expects. Done means a saved request and response pair that matches the External Knowledge API documentation.
Enforce bearer key checks in your service
Dify sends the API key you configure as a bearer token, but it does not validate that key itself. Your endpoint must reject requests without the expected token, so the check belongs in your code or gateway. Store the key in your secrets manager rather than in notes or tickets, and set a rotation owner. Done means a request with a missing or wrong token returns an error from your service, while the correct token returns chunks.
Register the External Knowledge API entry
In the Dify console, a workspace administrator opens the knowledge base area and creates an External Knowledge API entry. Enter the endpoint base URL and the bearer key. Dify stores this connection so that external knowledge bases can reference it. Done means the entry appears in the list, and a connection or test action, where your Dify version offers one, reaches your endpoint. Confirm in your endpoint log that the request arrived with the expected headers.
Create the External Knowledge Base with its ID
Create an External Knowledge Base that points to the API entry and enters the knowledge ID your service uses to identify its index. Name the base so that builders can tell it apart from internal Dify knowledge bases. Note that the External Knowledge API and the External Knowledge ID cannot be changed after creation, so verify both values before saving. Done means the base is listed with the correct ID, and a retrieval log entry shows that knowledge_id matches your index name.
Attach the base to a test app
Open a test app in a non-production workspace, add the external knowledge base as a context source, and set top_k and score_threshold for initial testing. Keep the settings conservative at first, then adjust them only after you see what your index returns. Done means the app's knowledge configuration shows the external base as active, and the app saves without errors.
Run retrieval checks and read the logs
Send a set of representative questions through the test app, including some with no good answer in the index. For each question, compare the chunks your endpoint returned with the chunks that reached the model, and check that low-scoring results are excluded by the threshold. Confirm that the endpoint received the expected knowledge_id and query. Done means a saved log for each question showing the request, the returned chunk list and the scores, with no chunks coming from outside the index.
Record what Dify does not manage
Document the boundaries before any user relies on the base. Dify retrieves from the external service only: it cannot modify, re-index, delete or manage the content, so your team owns document updates, access rules and deletion requests in the source system. Also record who rotates the bearer key and who approves changes to the endpoint. Done means a short runbook exists, signed off by the owner of the retrieval service.
How Dify calls your retrieval service on each query
When a user asks a question in an app that uses an external knowledge base, Dify sends a retrieval request on the app builder's behalf before the model answers. The builder controls the settings that travel with that request: which external knowledge base is attached, how many results to ask for, and the minimum score a result needs to be kept. The query text comes from the user's message in the workflow or chat, so the wording the model sees and the wording the retriever sees are the same string.
- Attachment: The external knowledge base is selected inside the app's knowledge configuration, and each attached base sends its own retrieval request.
- Top K: This value tells the retrieval service how many results to return, so it sets how much context reaches the model.
- Score threshold: Results below this value are dropped by Dify, so a high threshold can return nothing for vague questions.
- Query text: Dify passes the user's question as the query field, so rephrasing or rewriting steps upstream change what your service receives.
- Testing: Run the same question with several settings and inspect the returned chunks in the app's debug view before publishing.
Before release, confirm with your retrieval team which score scale they use, because a threshold tuned on one scale will not carry over to another. Check the current External Knowledge API documentation for the exact retrieval_setting behavior.
The retrieval service owner implements a single POST endpoint at {endpoint}/retrieval. Dify sends a JSON body containing knowledge_id, query and retrieval_setting, which holds top_k and score_threshold, and may also send metadata_condition. The configured API key arrives as a bearer token in the Authorization header. Dify passes that key along but does not validate it, so your service must check it on every call and reject anything it does not recognize.
- Required fields: Read knowledge_id to select the right collection, and read query and retrieval_setting for ranking and cutoff.
- Optional filters: Treat metadata_condition as optional, and only apply it if your service supports metadata filtering.
- Authentication: Validate the bearer token yourself, because Dify will not reject requests with a wrong key.
- Ranking: Apply top_k and score_threshold on your side, so Dify receives results already within the requested limits.
- Response shape: Confirm the response field names and nesting against the current External Knowledge API docs before coding, since the response schema is not restated here.
Write contract tests that send a fixed query and check the request parsing, the bearer check and the empty-result case. Those tests catch most integration failures before a published app depends on them.
Dify makes the retrieval call from its own backend, so the network path runs from the Dify API or worker to your endpoint, not from the user's browser. In a Docker Compose deployment, outbound requests from Dify can be routed through an SSRF proxy that blocks internal and private IP ranges. Retrieval services that run on a private address therefore need an explicit route through that control, or the call fails before it reaches your service.
- Proxy path: Dify's SSRF_PROXY settings govern outbound requests, so confirm whether your endpoint is reachable through that proxy.
- Allowlisting: Where your service sits on an internal host, the proxy configuration must permit that destination, and the change should be reviewed like any other egress rule.
- TLS and certificates: Confirm that the endpoint presents a certificate chain the Dify containers trust, including any internal certificate authority.
- Egress scope: Restrict the allowed destinations to the retrieval endpoint, so the proxy does not become a general route into the network.
- Logging: Capture request timing and status at the retrieval service and at the proxy to separate network failures from ranking problems.
Confirm the exact proxy variables and their current defaults against the environment variables reference and your own network policy before opening any route.
Which Dify fields map to your retrieval service
This table maps each documented External Knowledge API request field to the value Dify sends, the team that should own it, and the check that confirms it works. Read it while building the retrieval endpoint, because most failed retrievals trace back to an ID, a score scale or a filter that the service interprets differently than Dify expects.
| Dify field | What Dify sends | Owner and check |
|---|---|---|
| knowledge_id | The External Knowledge ID you entered when creating the knowledge base, sent on every retrieval call | Your platform team owns the mapping to a collection or index. Confirm the ID resolves to exactly one collection in your service's own schema. |
| query | The user or workflow question text that Dify wants matched against your content | The application team owns the input. Test with real questions and confirm your service applies the same language and normalization as your indexing pipeline. |
| retrieval_setting.top_k | The maximum number of results Dify requests from your service | The knowledge engineer owns the value. Confirm your service caps the count and returns results in descending relevance order. |
| retrieval_setting.score_threshold | The minimum relevance score Dify uses to keep a result | The knowledge engineer owns the value. Confirm the score scale your service returns (for example, 0 to 1 or distance-based) matches what the threshold assumes. |
| metadata_condition (optional) | Filter conditions Dify passes when metadata filtering is configured | The data owner defines allowed filters. Confirm each condition field and operator exists in your service's schema, and check how unknown fields are handled. |
| Bearer API key | The key configured in Dify, sent in the Authorization header, which Dify does not validate | The security team owns the key. Confirm your endpoint rejects requests without a valid key and that the key is rotated outside Dify. |
| Response records | The content and score fields your endpoint returns for Dify to display and rank | The integration engineer owns the response shape. Confirm it matches the documented structure exactly, using the service's own schema as the reference. |
Controls for keys, egress and retrieved content
The External Knowledge API moves trust decisions out of Dify and into your retrieval service. Key checks, outbound network rules, index permissions, logging and prompt handling all need an owner before the connection goes live.
Bearer key checks sit with you
Dify sends the configured API key as a bearer token, but it passes the key through without validating it. Your retrieval endpoint must reject any request whose key is missing or wrong. Store the key in a secrets manager, not in plain text in screenshots or tickets, and plan a rotation procedure that updates both Dify and your service in the same change window. Confirm how your service handles old and new keys during that window. Dify does not check the key for you.
SSRF proxy allowlisting for private endpoints
The SSRF proxy blocks outbound requests to internal and private IP ranges, which is the default protection against Dify reaching internal hosts. If your retrieval service runs on a private address, the request will be stopped unless you add that host or range to the proxy allowlist. Keep the list as narrow as possible: one service address and port, not a whole subnet. Record each entry with its owner and reason so it can be reviewed when the service moves.
Least-privilege index access
Give the retrieval service a read-only identity for the index it serves to Dify. Dify cannot modify or manage external content, so there is no need for write access from the Dify side, and any ingestion job should use its own credentials. Scope each knowledge ID to the documents that app is allowed to see. If your index holds mixed sensitivity levels, filter by the caller's permissions inside the retrieval service, because Dify will not apply your access model to the results.
Logging retrieval calls
Log every call to the retrieval endpoint with the timestamp, knowledge ID, a hash or length of the query, the top K and score threshold values received, the number of results returned and the caller's key identifier. Decide upfront whether raw queries may be stored, since they can contain personal data. Confirm your retention period with your compliance owner. Dify's own logs will not show what your service returned, so this record is the evidence trail for retrieval.
Retrieved text is untrusted input
Text returned from the retrieval endpoint is placed into prompts and can contain instructions written by anyone who could add content to the source documents. Treat each retrieved passage as data, not as instructions. Keep system prompts separate from retrieved content, limit what tools an agent can call after reading retrieved text, and test with documents that contain injected instructions before production use. Human review steps matter most for workflows that act on the answer.
Key and secret scope in Dify
Dify's SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, so changing it after deployment logs out every user. That is a separate concern from the retrieval key, which is only stored in Dify's configuration for the knowledge base. Confirm where Dify stores the external API key in your version, who can view it in the console, and whether your backups include it, because a restored backup will carry that credential with it.
What Dify cannot manage in an external knowledge base
An external knowledge base gives Dify retrieval access and nothing more. Dify cannot modify or manage the external content, so the document lifecycle stays entirely with your retrieval service or managed knowledge base. Dify also does not run chunking, indexing or re-sync on that content. Whatever your service stores, splits and refreshes is what Dify can ever retrieve, and Dify has no visibility into whether an index is stale, partially built or failing.
Two settings are fixed once the knowledge base exists. The External Knowledge API and the External Knowledge ID cannot be changed after creation, so moving to a different endpoint, or re-pointing the knowledge base at a new external dataset, means creating a new knowledge base and reconnecting the apps that use it. Plan the naming and endpoint choice before the first workflow references the knowledge base, and record which external dataset each Dify knowledge base maps to in your change log.
Deletion, access control and change control belong to your side of the boundary. Removing a document from Dify's view does not delete it from the external system, and deleting content in your service removes it from answers only after your own index updates. Dify passes the bearer key but does not validate it, so per-user or per-document permissions must be enforced inside your retrieval service, not in Dify. The docs give AWS Bedrock as an example of a third-party knowledge service that can be connected. For LlamaCloud, the docs recommend the official LlamaCloud plugin over a custom API, so confirm that recommendation against your current Dify version before you build a custom integration.
Why retrieval fails and how to fix it
This table lists the failures teams hit most often when Dify calls an external retrieval service, with the likely cause and fix for each. Read it as a triage order: check reachability and proxy rules first, then the key and knowledge_id, then the retrieval settings. Confirm timeouts and SSRF proxy behavior against the Dify environment variable reference before changing anything.
| Failure | Likely cause | Fix |
|---|---|---|
| Endpoint unreachable | Dify cannot reach the {endpoint}/retrieval URL, or the SSRF proxy blocks an internal or private address | Confirm the endpoint resolves from the Dify api and worker containers, then review SSRF_PROXY settings and the proxy allowlist for your internal host |
| Bearer key rejected | The API key configured in Dify does not match what your service expects, or the service rejects the header format | Dify sends the key as a bearer token but does not validate it, so check the key against your service logs and re-enter it in the external API settings |
| Wrong knowledge_id | The External Knowledge ID in Dify does not match an ID your service recognizes | Copy the ID from your service exactly, then recreate the connection, since the ID cannot be changed after creation |
| Empty results from a high score_threshold | The score_threshold is set above the similarity scores your service returns for real queries | Lower the threshold in steps and test with known queries, comparing returned scores before changing the index |
| Too few chunks from a low top_k | top_k limits how many chunks are returned, so relevant passages are cut before reaching the model | Raise top_k within what your service and prompt budget can handle, and check whether the right passage appears in the returned set |
| Retrieved text does not match the query | Query preprocessing, embedding mismatch or wrong knowledge base mapping in your service | Test the retrieval endpoint directly with the same query and knowledge_id, and fix ranking or mapping on your side because Dify cannot manage external content |
Questions teams ask before connecting an external RAG system
How much effort does connecting Dify to an external RAG system take?
The effort depends mainly on three things: how much your retrieval service already matches the External Knowledge API contract, how much retrieval quality tuning is needed, and how many network approvals the work requires. If your service already accepts a POST to {endpoint}/retrieval and returns records in the shape Dify expects, the Dify side is mostly configuration and testing. If you must write an adapter, map metadata, or tune top K and score thresholds against real questions, the work grows. Network approvals for the endpoint, the SSRF proxy allowlist and the bearer key often take longer than the code itself. Ask for the effort split by these three areas in any written quote.
Can an internal team connect Dify to its own retrieval service alone?
Yes, a team with an engineer who can build a small HTTP service and a platform engineer who can edit the Dify deployment can do it. The Dify docs describe the endpoint contract and the connection steps in enough detail to start. The parts teams most often underestimate are the evaluation of retrieval quality, the outbound network rules for a service on an internal host, and the operational ownership of the endpoint after go-live. Your team should decide early whether it has the time to test these areas properly, because a connection that returns results is not the same as one that returns the right passages.
What does DeployOpen need from our team to start?
DeployOpen needs network access to the retrieval endpoint from the Dify deployment, a named owner for the bearer key and for the retrieval service, and a set of test documents and questions that reflect real use. Access to the Dify instance itself, including the ability to change .env values for the SSRF proxy allowlist if the endpoint sits on an internal host, is also needed. Ask your security team to confirm who approves outbound rules and who can rotate the key. The exact list is set out in the written scope before work starts, so these items become deliverables and dependencies rather than assumptions.
How long does the integration take?
Duration depends on scope and must be agreed in writing before work starts. The main drivers are whether the retrieval service already meets the contract, how many approvals the endpoint and proxy changes need, the number of knowledge bases and test cases, and how much tuning the retrieval results need. Most engagements are fixed-scope, so the timeline is tied to the deliverables and the client dependencies listed in that scope. Ask for the timeline with its assumptions stated, including who must act before each step and how long your approvals are expected to take.
Can Dify update or manage the documents in an external knowledge base?
No. An external knowledge base gives Dify retrieval access only. Dify cannot modify or manage the external content, so adding, removing or correcting documents happens in your retrieval service or managed knowledge base. The External Knowledge API and External Knowledge ID also cannot be changed after the knowledge base is created, so the choice of endpoint must be right from the start. Plan a separate process for content ownership, updates and deletions, and confirm how stale or deleted records will be handled by your own service.
Does using a managed service such as AWS Bedrock or LlamaCloud change the work?
It changes the adapter work, not the principle. The Dify docs give AWS Bedrock as an example of a third-party knowledge service that can be connected, and they recommend the official LlamaCloud plugin instead of a custom API for LlamaCloud. Where an official plugin or supported connection exists, your effort shifts toward credentials, access scoping and retrieval tuning. Where it does not, you will need an endpoint that follows the External Knowledge API contract. Confirm with your provider which data leaves your boundary, where credentials are stored, and what the managed service charges, since those costs sit outside Dify.
What should we check on the endpoint so it does not block or leak data?
Check that the endpoint accepts only the configured bearer key, because Dify passes the key but does not validate it, which means your service must do the validation. Confirm that top K and score thresholds are enforced on your side, that metadata conditions are handled safely, and that error responses do not reveal internal details. Make sure the Dify SSRF proxy allows only the hosts you approve, and that the service is reachable only from the Dify network path you intend. Ask your security team to review logs for failed authentication attempts.
How to test retrieval quality and keep the integration running
Start by building a test set of known questions with expected sources before you tune anything. For each question, record the knowledge_id of the external knowledge base, the document or passage that should come back, and the answer a reviewer would accept. Keep the set small enough that a domain expert can review it, and include questions that should return nothing, so you can see whether the retrieval service invents matches. Run the same set against your retrieval service directly, then through Dify, so that a gap can be assigned to either side. Confirm with your retrieval team which fields the endpoint returns in each result, because the scoring you apply depends on them.
Tune top_k and score_threshold against that set, one variable at a time. A higher top_k raises the chance that the right passage is present but also adds more text for the model to read, so measure both recall and the length of the context that reaches the prompt. A score_threshold that is too strict will silently drop good passages, and one that is too loose will pass noise. Record the scores your service actually returns for correct and incorrect hits before picking a value, since score scales differ between retrieval engines. Also confirm whether the External Knowledge API setting in your Dify version exposes these values per app or per knowledge base, because that decides where the tuning has to live.
Treat every Dify upgrade as a change that needs a regression run. The releases page shows minor versions arriving roughly monthly, so schedule the test set to run against a staging instance before each production upgrade, following the upgrade guide for the target version and taking a backup first. Keep your retrieval service version pinned during that run so that a drop in results can be traced. For operations, monitor retrieval latency and error rates at the boundary between Dify and your endpoint, and set alerts on timeouts and non-success responses. Confirm with your platform team where those logs live, who owns the endpoint, and how an outage in the retrieval service is reported back to Dify users.
How DeployOpen scopes and delivers this integration
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including the Dify retrieval endpoint that connects your existing RAG service to Dify. The work starts with a written scope that names the systems, the retrieval contract and the network paths before any configuration changes.
How we scope
- Inventory the knowledge bases, document owners and retrieval services that Dify will query through the External Knowledge API
- Define the retrieval endpoint contract, including request fields, top K and score threshold behavior, and optional metadata conditions
- Agree in writing which SSRF proxy allowlist entries, bearer key handling and access boundaries are in scope before work starts
How we build
- Implement the POST retrieval endpoint in your environment or configure the agreed connection to your managed knowledge base
- Set the external knowledge API key and External Knowledge ID per workspace, and verify the proxy path from the Dify api and worker services
- Test retrieval results against agreed queries, score thresholds and top K values, and record the outcomes for review
How we hand over
- Deliver the endpoint specification, configuration records, allowlist changes and a test script your team can rerun
- Document what Dify cannot manage, including changes to external content, and which settings are fixed after creation
- Walk your operators through key rotation, endpoint ownership and the steps to follow when retrieval results change
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the initial delivery
- Review the Dify release notes and upgrade guide when versions change, and confirm the retrieval contract still matches
- Confirm with your own security and platform teams how endpoint logs, key storage and retention are handled in your environment
