Create Source
Adds a source that reads through an existing connection, found with List Source Connections. Nothing is crawled or imported.
Repeating a successful creation creates another source. Add a unique metadata.client_request_id and keep it until you receive the source ID.
To fill the source, call Preview Website Crawl or Import Website Pages for a web source, or Import Source Items for a connector source. For the steps, see Add a Source.
curl --request POST \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"connectionId": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website"
},
"name": "Docs site",
"permissionScope": [],
"status": "disabled",
"type": "web",
"uri": "https://docs.example.com"
}
'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources"
payload = {
"connectionId": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website"
},
"name": "Docs site",
"permissionScope": [],
"status": "disabled",
"type": "web",
"uri": "https://docs.example.com"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connectionId: 'c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f',
metadata: {client_request_id: 'source-20260907-0001', providerKind: 'website'},
name: 'Docs site',
permissionScope: [],
status: 'disabled',
type: 'web',
uri: 'https://docs.example.com'
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'connectionId' => 'c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f',
'metadata' => [
'client_request_id' => 'source-20260907-0001',
'providerKind' => 'website'
],
'name' => 'Docs site',
'permissionScope' => [
],
'status' => 'disabled',
'type' => 'web',
'uri' => 'https://docs.example.com'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources"
payload := strings.NewReader("{\n \"connectionId\": \"c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f\",\n \"metadata\": {\n \"client_request_id\": \"source-20260907-0001\",\n \"providerKind\": \"website\"\n },\n \"name\": \"Docs site\",\n \"permissionScope\": [],\n \"status\": \"disabled\",\n \"type\": \"web\",\n \"uri\": \"https://docs.example.com\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"connectionId\": \"c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f\",\n \"metadata\": {\n \"client_request_id\": \"source-20260907-0001\",\n \"providerKind\": \"website\"\n },\n \"name\": \"Docs site\",\n \"permissionScope\": [],\n \"status\": \"disabled\",\n \"type\": \"web\",\n \"uri\": \"https://docs.example.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"connectionId\": \"c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f\",\n \"metadata\": {\n \"client_request_id\": \"source-20260907-0001\",\n \"providerKind\": \"website\"\n },\n \"name\": \"Docs site\",\n \"permissionScope\": [],\n \"status\": \"disabled\",\n \"type\": \"web\",\n \"uri\": \"https://docs.example.com\"\n}"
response = http.request(request)
puts response.read_body{
"connection_id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"created_at": "2026-09-06T01:30:00Z",
"credential_configured": null,
"id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"last_synced_at": null,
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website",
"tenantId": "2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f"
},
"name": "Docs site",
"permission_scope": [],
"status": "disabled",
"sync_policy": null,
"sync_workflow": null,
"type": "web",
"updated_at": "2026-09-06T01:30:00Z",
"uri": "https://docs.example.com",
"version": 1
}Authorizations
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).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path Parameters
Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.
Body
Optional fields marked nullable treat null as omitted.
The normalized request must fit within 262,144 UTF-8 bytes. See Request Size Limits.
Display name.
1 - 200Send web for a website crawl, or connector for an online document or online drive provider (set metadata.providerKind). upload and object-storage are for sources Dify fills.
connector, object-storage, upload, web Crawl root URL for web. connector://<connectionId> for connector, matching what Dify writes.
1 - 4096Connection that supplies the credentials the source reads with. It must belong to this knowledge base and be active. From id of List Source Connections.
Provider settings and your own non-sensitive metadata. Add a unique client_request_id to recognize this source if the creation response is lost. It is returned with the source, but the API does not enforce uniqueness or deduplicate requests.
Set providerKind to the connection's configuration.providerKind, and pick the source type that fits it. Settings that come from the connection may be absent from the source response.
If you build metadata from an existing source's response, leave out fields starting with __knowledgeFs, credentials, and the parameters object. credentialId, when present, refers to a credential Dify holds.
Leave empty or omit. Only an empty list is accepted.
disabled pauses scheduled syncs.
active, disabled, null Response
The created source.
Connection the source uses for credentials. Pass it as connectionId when binding another source to the same connection. null when unbound.
Creation time, ISO 8601.
true when the source holds a credential reference of its own. null when it holds none, as with sources bound to a connection.
Source ID.
Internal ID of the knowledge base. Not the knowledge base ID in the path.
Completion time of the latest completed sync (completed or zero_results) or completed import. Set by List Sources only. null elsewhere and when the source has never synced.
Provider settings and server-managed sync or page-selection data. May include provider identifiers and parameters; connection-managed settings need not appear here. Credential-like keys are removed. Do not copy the entire object when creating another source.
Display name.
Content scopes required to read this source. An empty list adds no content restriction within the knowledge base. Knowledge base authorization still applies.
active, syncing, error, or disabled. Most operations return the stored value. List Sources derives it from the latest sync run:
failedorcanceledrun:errorcompletedorzero_resultsrun:active- Any live run:
syncing
disabled is never overridden.
The source's sync schedule. Set by List Sources only. null elsewhere and when no schedule exists. Read it on its own with Get Sync Policy and change it with Update Sync Policy.
Show child attributes
Show child attributes
The source's active sync or import run (crawl-import, online-document-import, or online-drive-import), or else its latest sync run. List Sources sets it when a run is active or newer than the source. Update Source sets it when the call started a sync. null otherwise. Crawl previews and imports from them never appear here.
To follow one run, call Get Source Run with its id.
Show child attributes
Show child attributes
web (website crawl), connector (online document or online drive), upload, or object-storage.
For a connector source, metadata.providerKind is online-document or online-drive. For a web source it is website.
Dify fills upload and object-storage sources.
Last change, ISO 8601.
Crawl root URL for web sources. connector://<connection_id> for Dify-created connector sources.
Source version, increased on every write. Send it as expectedVersion on Update Source, as expectedRevision on Delete Source, and as expectedSourceVersion on Update Sync Policy.
Was this page helpful?
curl --request POST \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"connectionId": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website"
},
"name": "Docs site",
"permissionScope": [],
"status": "disabled",
"type": "web",
"uri": "https://docs.example.com"
}
'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources"
payload = {
"connectionId": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website"
},
"name": "Docs site",
"permissionScope": [],
"status": "disabled",
"type": "web",
"uri": "https://docs.example.com"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connectionId: 'c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f',
metadata: {client_request_id: 'source-20260907-0001', providerKind: 'website'},
name: 'Docs site',
permissionScope: [],
status: 'disabled',
type: 'web',
uri: 'https://docs.example.com'
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'connectionId' => 'c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f',
'metadata' => [
'client_request_id' => 'source-20260907-0001',
'providerKind' => 'website'
],
'name' => 'Docs site',
'permissionScope' => [
],
'status' => 'disabled',
'type' => 'web',
'uri' => 'https://docs.example.com'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources"
payload := strings.NewReader("{\n \"connectionId\": \"c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f\",\n \"metadata\": {\n \"client_request_id\": \"source-20260907-0001\",\n \"providerKind\": \"website\"\n },\n \"name\": \"Docs site\",\n \"permissionScope\": [],\n \"status\": \"disabled\",\n \"type\": \"web\",\n \"uri\": \"https://docs.example.com\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"connectionId\": \"c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f\",\n \"metadata\": {\n \"client_request_id\": \"source-20260907-0001\",\n \"providerKind\": \"website\"\n },\n \"name\": \"Docs site\",\n \"permissionScope\": [],\n \"status\": \"disabled\",\n \"type\": \"web\",\n \"uri\": \"https://docs.example.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"connectionId\": \"c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f\",\n \"metadata\": {\n \"client_request_id\": \"source-20260907-0001\",\n \"providerKind\": \"website\"\n },\n \"name\": \"Docs site\",\n \"permissionScope\": [],\n \"status\": \"disabled\",\n \"type\": \"web\",\n \"uri\": \"https://docs.example.com\"\n}"
response = http.request(request)
puts response.read_body{
"connection_id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"created_at": "2026-09-06T01:30:00Z",
"credential_configured": null,
"id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"last_synced_at": null,
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website",
"tenantId": "2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f"
},
"name": "Docs site",
"permission_scope": [],
"status": "disabled",
"sync_policy": null,
"sync_workflow": null,
"type": "web",
"updated_at": "2026-09-06T01:30:00Z",
"uri": "https://docs.example.com",
"version": 1
}