[DOCS]: Add an External Knowledge API #272

New Issue

Closed

opened 2026-02-16 05:19:41 -05:00 by yindo · 3 comments

yindo commented 2026-02-16 05:19:41 -05:00

Owner

Copy Link

Copy Source

Originally created by @bfechoz-ade on GitHub (Nov 24, 2025).

Type of Documentation Change

Error/Typo fix

Documentation Page URL or Path

https://white-rabbit.ai.ad-education.com/datasets

Current Content

Add an External Knowledge API

I am adding my external LlamaCloud base to the plugin page with the api key and an api name who give me the endpoint that I am trying to add in the page for adding external knowledge base.

and then I found the error msg : "failed to connect to the endpoint: http://localhost/e/kbum3nr..pfiah25/retrieval"

WHEREAS I still have a functionnal endpoint working with my previous Llamacloud account with a US location but I had to change for a european one and now the linking is not working

Suggested Changes

don't know

Reason for Change

No response

Code of Conduct

• I agree to follow Dify's documentation contribution guidelines
• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report, otherwise it will be closed.
• 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
• Please do not modify this template :) and fill in all the required fields.

Originally created by @bfechoz-ade on GitHub (Nov 24, 2025). ### Type of Documentation Change Error/Typo fix ### Documentation Page URL or Path https://white-rabbit.ai.ad-education.com/datasets ### Current Content Add an External Knowledge API I am adding my external LlamaCloud base to the plugin page with the api key and an api name who give me the endpoint that I am trying to add in the page for adding external knowledge base. and then I found the error msg : "failed to connect to the endpoint: http://localhost/e/kbum3nr..pfiah25/retrieval" WHEREAS I still have a functionnal endpoint working with my previous Llamacloud account with a US location but I had to change for a european one and now the linking is not working ### Suggested Changes don't know ### Reason for Change _No response_ ### Code of Conduct - [x] I agree to follow Dify's documentation [contribution guidelines](https://github.com/langgenius/dify/blob/0277a37fcad5ad86aeb239485c27fffd5cd90043/CONTRIBUTING.md) - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [ ] 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：） - [x] Please do not modify this template :) and fill in all the required fields.

yindo added the documentationbug labels 2026-02-16 05:19:41 -05:00

yindo closed this issue 2026-02-16 05:19:41 -05:00

yindo commented 2026-02-16 05:19:42 -05:00

Author

Owner

Copy Link

Copy Source

@dosubot[bot] commented on GitHub (Nov 24, 2025):

Hi @bfechoz-ade! I'm Dosu and I’m helping the dify-docs team.

The error happens because using localhost as the endpoint means Dify (especially if running in Docker or on another server) can't reach your external knowledge API—localhost refers to the container or server itself, not your host machine or the actual service you want to connect to. To fix this, set the endpoint to something accessible from Dify's environment, like host.docker.internal (if your service runs on your host machine), the actual LAN IP, or the Docker network hostname if it's another container. Make sure the endpoint starts with http:// or https:// and is reachable from inside the Dify container. You can test this by running curl <endpoint>/retrieval inside the Dify container.

For documentation, it would help to add a warning about not using localhost for endpoints and provide a checklist: use a reachable network address, verify the port, and ensure the API responds with the required schema (a JSON object with a records array containing content, score, title, and optional metadata). If your external service doesn't require an API key but Dify enforces one, you can use a simple proxy to strip the Authorization header before forwarding requests to your service.

References:

• Why localhost fails and how to fix it
• Checklist for external knowledge API integration
• API schema and troubleshooting
• Proxy workaround for API key enforcement

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

  

@dosubot[bot] commented on GitHub (Nov 24, 2025): <!-- Greeting --> Hi @bfechoz-ade! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the dify-docs team. <!-- Answer --> The error happens because using `localhost` as the endpoint means Dify (especially if running in Docker or on another server) can't reach your external knowledge API—`localhost` refers to the container or server itself, not your host machine or the actual service you want to connect to. To fix this, set the endpoint to something accessible from Dify's environment, like `host.docker.internal` (if your service runs on your host machine), the actual LAN IP, or the Docker network hostname if it's another container. Make sure the endpoint starts with `http://` or `https://` and is reachable from inside the Dify container. You can test this by running `curl <endpoint>/retrieval` inside the Dify container. For documentation, it would help to add a warning about not using `localhost` for endpoints and provide a checklist: use a reachable network address, verify the port, and ensure the API responds with the required schema (a JSON object with a `records` array containing `content`, `score`, `title`, and optional `metadata`). If your external service doesn't require an API key but Dify enforces one, you can use a simple proxy to strip the Authorization header before forwarding requests to your service. References: - [Why localhost fails and how to fix it](https://github.com/langgenius/dify/issues/17905) - [Checklist for external knowledge API integration](https://github.com/langgenius/dify/issues/14383) - [API schema and troubleshooting](https://github.com/langgenius/dify/discussions/21088) - [Proxy workaround for API key enforcement](https://github.com/langgenius/dify/discussions/21041) <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- ^{How did I do? [Good](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/d225a715-7511-4fee-a97a-92d6ee4246c1?feedback_type=other)} [](https://cursor.com/link/prompt?text=The%20error%20happens%20because%20using%20%60localhost%60%20as%20the%20endpoint%20means%20Dify%20%28especially%20if%20running%20in%20Docker%20or%20on%20another%20server%29%20can%27t%20reach%20your%20external%20knowledge%20API%E2%80%94%60localhost%60%20refers%20to%20the%20container%20or%20server%20itself%2C%20not%20your%20host%20machine%20or%20the%20actual%20service%20you%20want%20to%20connect%20to.%20To%20fix%20this%2C%20set%20the%20endpoint%20to%20something%20accessible%20from%20Dify%27s%20environment%2C%20like%20%60host.docker.internal%60%20%28if%20your%20service%20runs%20on%20your%20host%20machine%29%2C%20the%20actual%20LAN%20IP%2C%20or%20the%20Docker%20network%20hostname%20if%20it%27s%20another%20container.%20Make%20sure%20the%20endpoint%20starts%20with%20%60http%3A//%60%20or%20%60https%3A//%60%20and%20is%20reachable%20from%20inside%20the%20Dify%20container.%20You%20can%20test%20this%20by%20running%20%60curl%20%3Cendpoint%3E/retrieval%60%20inside%20the%20Dify%20container.%20%0A%0AFor%20documentation%2C%20it%20would%20help%20to%20add%20a%20warning%20about%20not%20using%20%60localhost%60%20for%20endpoints%20and%20provide%20a%20checklist%3A%20use%20a%20reachable%20network%20address%2C%20verify%20the%20port%2C%20and%20ensure%20the%20API%20responds%20with%20the%20required%20schema%20%28a%20JSON%20object%20with%20a%20%60records%60%20array%20containing%20%60content%60%2C%20%60score%60%2C%20%60title%60%2C%20and%20optional%20%60metadata%60%29.%20If%20your%20external%20service%20doesn%27t%20require%20an%20API%20key%20but%20Dify%20enforces%20one%2C%20you%20can%20use%20a%20simple%20proxy%20to%20strip%20the%20Authorization%20header%20before%20forwarding%20requests%20to%20your%20service.%20%0A%0AReferences%3A%20%20%0A-%20%5BWhy%20localhost%20fails%20and%20how%20to%20fix%20it%5D%28https%3A//github.com/langgenius/dify/issues/17905%29%20%20%0A-%20%5BChecklist%20for%20external%20knowledge%20API%20integration%5D%28https%3A//github.com/langgenius/dify/issues/14383%29%20%20%0A-%20%5BAPI%20schema%20and%20troubleshooting%5D%28https%3A//github.com/langgenius/dify/discussions/21088%29%20%20%0A-%20%5BProxy%20workaround%20for%20API%20key%20enforcement%5D%28https%3A//github.com/langgenius/dify/discussions/21041%29)&nbsp;[](https://go.dosu.dev/discord-bot)&nbsp;[](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/535)

yindo commented 2026-02-16 05:19:42 -05:00

Author

Owner

Copy Link

Copy Source

@bfechoz-ade commented on GitHub (Nov 25, 2025):

Do you have a simple solution ?

@bfechoz-ade commented on GitHub (Nov 25, 2025): Do you have a simple solution ?

yindo commented 2026-02-16 05:19:42 -05:00

Author

Owner

Copy Link

Copy Source

@dosubot[bot] commented on GitHub (Nov 25, 2025):

Yes, here's the simplest fix: change your endpoint from localhost to something Dify can actually reach. If your LlamaCloud service runs on your host machine and Dify is in Docker, use host.docker.internal (e.g. http://host.docker.internal/e/kbum3nr..pfiah25/retrieval). If it's on another machine or in the cloud, use its LAN IP or public DNS name. Make sure the endpoint starts with http:// or https:// and the port is correct.

After updating the endpoint, test it by running:

docker exec -it <dify-container-name> curl -X POST <your-endpoint>/retrieval

If you get a response, you're good to go. If not, check your Docker network, firewall, and port settings. For more details, see this guide: Why localhost fails and how to fix it and step-by-step instructions.

If your external service doesn't need an API key but Dify requires one, you can use a simple proxy to strip the Authorization header before forwarding requests. Let me know if you need help with that!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

  

@dosubot[bot] commented on GitHub (Nov 25, 2025): <!-- Answer --> Yes, here's the simplest fix: change your endpoint from `localhost` to something Dify can actually reach. If your LlamaCloud service runs on your host machine and Dify is in Docker, use `host.docker.internal` (e.g. `http://host.docker.internal/e/kbum3nr..pfiah25/retrieval`). If it's on another machine or in the cloud, use its LAN IP or public DNS name. Make sure the endpoint starts with `http://` or `https://` and the port is correct. After updating the endpoint, test it by running: ```bash docker exec -it <dify-container-name> curl -X POST <your-endpoint>/retrieval ``` If you get a response, you're good to go. If not, check your Docker network, firewall, and port settings. For more details, see this guide: [Why localhost fails and how to fix it](https://github.com/langgenius/dify/issues/17905) and [step-by-step instructions](https://github.com/langgenius/dify-official-plugins/issues/1542). If your external service doesn't need an API key but Dify requires one, you can use a simple proxy to strip the Authorization header before forwarding requests. Let me know if you need help with that! <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- ^{How did I do? [Good](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/9cd438cc-ddb5-4123-a4c0-2f007c73eb6d?feedback_type=other)} [](https://cursor.com/link/prompt?text=Yes%2C%20here%27s%20the%20simplest%20fix%3A%20change%20your%20endpoint%20from%20%60localhost%60%20to%20something%20Dify%20can%20actually%20reach.%20If%20your%20LlamaCloud%20service%20runs%20on%20your%20host%20machine%20and%20Dify%20is%20in%20Docker%2C%20use%20%60host.docker.internal%60%20%28e.g.%20%60http%3A//host.docker.internal/e/kbum3nr..pfiah25/retrieval%60%29.%20If%20it%27s%20on%20another%20machine%20or%20in%20the%20cloud%2C%20use%20its%20LAN%20IP%20or%20public%20DNS%20name.%20Make%20sure%20the%20endpoint%20starts%20with%20%60http%3A//%60%20or%20%60https%3A//%60%20and%20the%20port%20is%20correct.%0A%0AAfter%20updating%20the%20endpoint%2C%20test%20it%20by%20running%3A%0A%60%60%60bash%0Adocker%20exec%20-it%20%3Cdify-container-name%3E%20curl%20-X%20POST%20%3Cyour-endpoint%3E/retrieval%0A%60%60%60%0AIf%20you%20get%20a%20response%2C%20you%27re%20good%20to%20go.%20If%20not%2C%20check%20your%20Docker%20network%2C%20firewall%2C%20and%20port%20settings.%20For%20more%20details%2C%20see%20this%20guide%3A%20%5BWhy%20localhost%20fails%20and%20how%20to%20fix%20it%5D%28https%3A//github.com/langgenius/dify/issues/17905%29%20and%20%5Bstep-by-step%20instructions%5D%28https%3A//github.com/langgenius/dify-official-plugins/issues/1542%29.%0A%0AIf%20your%20external%20service%20doesn%27t%20need%20an%20API%20key%20but%20Dify%20requires%20one%2C%20you%20can%20use%20a%20simple%20proxy%20to%20strip%20the%20Authorization%20header%20before%20forwarding%20requests.%20Let%20me%20know%20if%20you%20need%20help%20with%20that%21)&nbsp;[](https://go.dosu.dev/discord-bot)&nbsp;[](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/535)

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

main

release/1.15.0

release/1.16.0-rc1

release/1.16.0

fix/workflow-version-403

docs/app-runner

docs/snippets

backup-main-2026-06-25

release/1.14.2

release/1.14.1

release/1.14.0

docs/pdf-download

feat/evaluation-snippet

add/new-agent

add/llm-support-tool

add/end-user-oauth

auto-translate-works

update/clarify-app-types

revamp

refactor/knowledge

multimodal-embedding

refactor/variable

auto-translate-core

auto-translate

v1.14.2

v1.14.1

v1.14.0

v1.13.0

v1.12.1

v1.12.0

v1.11.4

v1.11.3

v1.11.2

v1.11.1

v1.11.0

Labels

Clear labels

bug

documentation

documentation

enhancement

pull-request

Mirrored from GitHub Pull Request

question

stale

No Label bug documentation

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

yindo

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: langgenius/dify-docs#272