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
Body
Optional fields marked nullable treat null as omitted.
The normalized request must fit within 262,144 UTF-8 bytes. See Request Size Limits.
Connection 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.
Response
The created source.
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.
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
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
}