API Extension: How To Add API Extension with Name, API Endpoint and API Key ?

[Guofu1149]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

API Extension: How To Add API Extension with Name, API Endpoint and API Key ?
I have already developed a server program for my Dify. Within my program, I made a function that user can create and update their own knowledge bases using Dify API Extension.
For example, I used below api to make a curl request:
Create an Empty Knowledge Base:Creates a new, empty knowledge base (dataset) with specified configurations.
curl --request POST
--url https://api.dify.ai/v1/datasets
--header 'Authorization: Bearer '
--header 'Content-Type: application/json'
--data '

But, I don't know how to set the correct api endpoint and api key?
My ip address is 53.33.44.292, and I tried in dify webUI setting the http://53.33.44.292/v1, http://53.33.44.292, http://53.33.44.292/datasets,etc for api endpoint, but none of them can be set !

So, How To Add API Extension with Name, API Endpoint and API Key in API extension?

@dosu.

2. Additional context or comments

No response

[dosubot[bot]]

To add an API Extension in Dify, you need to provide a name, the full API endpoint URL, and an API key. The API endpoint should be the exact URL where Dify will send POST requests, and the API key must be at least 5 characters. Dify sends requests with the API key in the Authorization header as Bearer {api_key} and expects your endpoint to handle a JSON payload like {"point": "ping", "params": {}} and reply with {"result": "pong"} for connection validation. If your endpoint isn’t publicly accessible or doesn’t handle this payload, Dify will report a connection error and won’t let you save the extension.

Make sure your endpoint is reachable from your Dify deployment (cloud or self-hosted), and that your API key is valid. The API key is masked in the UI for security, and only updated if you enter a new value. If you’re self-hosting, double-check your network/firewall settings and endpoint compatibility. There’s no official step-by-step guide in the docs, but the backend logic and validation requirements are clear from the code and issue discussions (source, source).

If you’re seeing connection errors, check that your endpoint URL starts with http:// or https://, is accessible, and responds correctly to the ping payload. If your API server doesn’t handle the expected request format, you may need to adjust your endpoint logic to accept and reply to Dify’s health check.

To reply, just mention @dosu.

---

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

   

[dosubot[bot]]

Yes, setting up the API extension in Dify Studio is the first step. In the Studio Web UI, you add an API extension by entering a name, the full API endpoint URL (where Dify will send POST requests), and an API key (at least 5 characters). When you save, Dify immediately tests the connection by sending a POST with a JSON payload like {"point": "ping", "params": {}} and expects your endpoint to reply with {"result": "pong"}. If the endpoint and key are valid, the extension is saved and ready to use.

This setup allows Dify to call your external API/service using the extension. Your server program must be ready to accept and respond to these requests. There’s no need to set the API key in docker-compose or backend files—everything is configured in the Studio UI and on your own server. Once the extension is validated and saved, you can use it in Dify workflows or trigger it from your server logic as designed.
Source

To reply, just mention @dosu.

---

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

   

[Guofu1149]

So, the API extension is sued by Dify to call other program? I thought that api extension is used by other program to call Dify .For example, server program use the API extension to create a new knowledge base in dify. But it seems like i was wrong?

So, let us focus on the problem :How to use the api to create a new knowledge base Tell me please!!!! @dosu.

[dosubot[bot]]

Correct—API extensions in Dify are for Dify to call external APIs, not for external programs to call Dify.

To create a new knowledge base (dataset) in Dify from your own program, you should use Dify’s REST API directly. The endpoint is:

POST /v1/datasets

You need to include a valid API token in the Authorization header (type: dataset). The request payload should be JSON with fields like name (required), description, permission, provider, indexing_technique, embedding_model, embedding_model_provider, and retrieval_model.

Here’s a working example using curl (reference):

curl -X POST http://127.0.0.1/v1/datasets \
  -H "Authorization: Bearer dataset-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "testapi",
    "description": "testapi",
    "permission": "only_me",
    "provider": "vendor",
    "indexing_technique": "high_quality",
    "embedding_model": "jina-embeddings-v3",
    "embedding_model_provider": "langgenius/xinference/xinference",
    "retrieval_model": {
      "search_method": "hybrid_search",
      "reranking_enable": true,
      "top_k": 3,
      "score_threshold_enabled": false,
      "score_threshold": 0.5,
      "reranking_model": {
        "reranking_model_name": "jina-reranker-v2",
        "reranking_provider_name": "langgenius/xinference/xinference"
      }
    }
  }'

Replace dataset-xxxx with your actual API token. You can generate or copy this token from the Dify web UI (usually under dataset/API settings).

If you get credential errors (like “Model ... credentials is not initialized”), make sure your model credentials are configured for the same tenant/context as your API token in the Dify web UI. For more details on the payload and authentication, see the API controller code.

Let me know if you need help with the payload fields or token setup!

To reply, just mention @dosu.

---

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

   

[Guofu1149]

in my server program, I have already make a correct curl, but i don't know what should be. And I can't find anywhere in dify Web Studio UI to set the dataset-xxx token! WHERE to SET???
below is what my server program can provide.
curl --request POST
--url https://api.dify.ai/v1/datasets
--header 'Authorization: Bearer '
--header 'Content-Type: application/json'
--data '
{
"name": "",
"description": "",
"indexing_technique": "high_quality",
"permission": "only_me",
"provider": "vendor",
"external_knowledge_api_id": "",
"external_knowledge_id": "",
"embedding_model": "",
"embedding_model_provider": "",
"retrieval_model": {
"search_method": "hybrid_search",
"reranking_enable": true,
"reranking_mode": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"top_k": 123,
"score_threshold_enabled": true,
"score_threshold": 123,
"weights": 123
}
}
'

[dosubot[bot]]

To create a knowledge base via Dify’s API, the <token> in your curl command must be a valid Dify dataset API key (it looks like dataset-xxxx). You do not set this token in the API extension settings—instead, you generate or copy it from the Dify Web Studio UI.

Here’s how to get your API key:

1. Go to the detail page of your knowledge base (dataset) in the Dify Web Studio UI.
2. Find the “Service API” card on the right side.
3. Click the “Secret Key” button to view or generate your API key. You need admin or editor permissions on the dataset to access this section.
4. Use this key in your curl request as Authorization: Bearer <your-dataset-api-key>.

If you don’t see the API key section, check your permissions, dataset settings, or whether your deployment needs a database migration after an upgrade. For Dify v1.9.0+, dataset API keys are managed at the tenant level and can also be created via the /datasets/api-keys endpoint if you have admin privileges and an access token (reference, reference).

Example curl:

curl --request POST \
  --url https://api.dify.ai/v1/datasets \
  --header 'Authorization: Bearer dataset-xxxx' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'

Let me know if you’re self-hosted or cloud (api.dify.ai) and still can’t find the key—there are some version-specific differences.

To reply, just mention @dosu.

---

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