List Sources
Lists the sources of a knowledge base in ascending source ID order, with each source’s sync schedule, its last completed sync or import, and its current run, or its latest sync when none is running.
A source leaves this listing as soon as its deletion is accepted.
For how to start and follow a sync, see Sync and Schedule Sources.
1 min read
get/knowledge-fs/spaces/{knowledge_base_id}/sources
Request example
curl --request GET \
--url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources"
headers = {
"Authorization": "Bearer <token>",
}
response = requests.request("GET", url, headers=headers)
print(response.text)const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources', {
method: 'GET',
headers: {
'Authorization': 'Bearer <token>'
}
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyResponse
{
"data": [
{
"connection_id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"created_at": "2026-09-01T08:00:00Z",
"credential_configured": null,
"id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"last_synced_at": "2026-09-05T10:12:00Z",
"metadata": {
"client_request_id": "source-20260907-0001",
"providerKind": "website",
"tenantId": "2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f"
},
"name": "Docs site",
"permission_scope": [],
"status": "active",
"sync_policy": {
"created_at": "2026-09-01T08:05:00Z",
"custom_interval_seconds": null,
"enabled": true,
"expected_source_version": 7,
"id": "8e7d6c5b-4a39-4f28-9e17-0d1c2b3a4f5e",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"mode": "interval",
"next_run_at": "2026-09-06T10:00:00Z",
"revision": 2,
"source_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"updated_at": "2026-09-05T10:00:00Z"
},
"sync_workflow": {
"canceled_at": null,
"checkpoint": "source-committed",
"completed_at": "2026-09-05T10:12:00Z",
"created_at": "2026-09-05T10:00:00Z",
"cursor": "ss1:eyJmaW5nZXJwcmludCI6IjgxZDk5OWY4YjI4ZDZhMGFlMTVmNjQxYzE2NjE3ZWNlMTBjYTcxMzE3OWU1MmVhMTYwODYyMzExMDcyYmQ4YmUiLCJraW5kIjoid2Vic2l0ZSIsIm9mZnNldCI6MCwicGhhc2UiOiJlb2YiLCJwcm9ncmVzc0NvbXBsZXRlZCI6NDUsInByb2dyZXNzVG90YWwiOjQ1fQ",
"execution_attempts": 1,
"failure": null,
"id": "d4c3b2a1-6f5e-4d7c-8b9a-0f1e2d3c4b5a",
"kind": "sync",
"knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
"last_error_code": null,
"max_execution_attempts": 5,
"progress_completed": 45,
"progress_failed": 0,
"progress_skipped": 0,
"progress_total": 45,
"source_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
"state": "completed",
"updated_at": "2026-09-05T10:12:00Z"
},
"type": "web",
"updated_at": "2026-09-03T09:20:00Z",
"uri": "https://docs.example.com",
"version": 7
}
],
"next_cursor": null
}{
"code": "knowledge_fs_invalid_request",
"message": "Agent Knowledge Base request is invalid.",
"status": 400,
"violations": [
{
"field": [
"limit"
],
"type": "less_than_equal"
}
]
}{
"code": "knowledge_fs_invalid_credential",
"message": "Invalid Agent Knowledge Base service credential.",
"status": 401
}{
"code": "unauthorized",
"message": "Access token is invalid",
"status": 401
}{
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
"status": 403
}{
"code": "knowledge_fs_access_denied",
"message": "Agent Knowledge Base operation is not allowed.",
"status": 403
}{
"code": "knowledge_fs_access_denied",
"failure": {
"action": "contact_admin",
"category": "authorization",
"code": "KNOWLEDGE_FS_ACCESS_DENIED",
"message": "You do not have permission to perform this Agent Knowledge Base operation.",
"retryPolicy": "never"
},
"message": "You do not have permission to perform this Agent Knowledge Base operation.",
"status": 403
}{
"code": "knowledge_fs_resource_not_found",
"failure": {
"category": "not_found",
"code": "KNOWLEDGE_FS_NOT_FOUND",
"message": "The requested Agent Knowledge Base resource was not found.",
"retryPolicy": "never"
},
"message": "The requested Agent Knowledge Base resource was not found.",
"status": 404
}{
"code": "not_found",
"message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
"status": 404
}{
"code": "knowledge_fs_upstream_unavailable",
"message": "Agent Knowledge Base is unavailable.",
"status": 502
}{
"code": "knowledge_fs_operation_unavailable",
"message": "Agent Knowledge Base operation is not available.",
"status": 503
}{
"code": "knowledge_fs_operation_unavailable",
"failure": {
"action": "retry",
"category": "dependency",
"code": "KNOWLEDGE_FS_UNAVAILABLE",
"message": "A service required by Agent Knowledge Base is temporarily unavailable.",
"retryPolicy": "manual",
"traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
},
"message": "A service required by Agent Knowledge Base is temporarily unavailable.",
"status": 503
}get/knowledge-fs/spaces/{knowledge_base_id}/sources
Authorization
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.Query parameters
Responses
application/json
One page of sources.
Sources on this page.
Show child attributesHide child attributes
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 attributesHide child attributes
Creation time, ISO 8601.
Interval in seconds for
mode: custom. null for the other modes.Whether scheduled syncs run. Always
false with mode: manual.Source
version the schedule is bound to.Sync policy ID. It stays the same across updates.
Internal ID of the knowledge base. Not the knowledge base ID in the path.
manual (no schedule), interval (every 24 hours), or custom (every custom_interval_seconds).When the next scheduled sync is due, ISO 8601.
null when nothing is scheduled.Schedule revision. Send it as
expectedRevision on Update Sync Policy. It increases on every update and every time a scheduled sync starts.Source the schedule belongs to.
Last change, ISO 8601. Also moves when a scheduled sync starts.
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 attributesHide child attributes
When the run was canceled.
null unless state is canceled.Last step the run reached:
queued, provider-read, preview-staged, selection-frozen, materialized, cleanup-staging, or source-committed. Retry Source Run starts the run over whatever its checkpoint.When the run ended (
completed, zero_results, failed, or canceled), ISO 8601. null while it runs.Creation time, ISO 8601.
Provider cursor the run resumes from.
null when the run has not paged.Times a worker has picked up the run, including after Retry Source Run, which does not reset it.
Error details when
state is failed. stage is the run's checkpoint at the failure, and traceId is the run ID. null otherwise.Show child attributesHide child attributes
Suggested next step, when there is one:
configure_model, configure_parser, configure_source, contact_admin, reupload, or retry. null when not applicable; omitted from HTTP error bodies.Kind of failure:
authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.Stable error code in upper snake case, for example
KNOWLEDGE_FS_CONFLICT or SOURCE_CREDENTIAL_TEST_FAILED.Public message for the error code or failure category. Provider error details are not exposed.
Up to 8 values that qualify the failure, with keys among
attempt, currentRowVersion, documentCount, expectedRowVersion, fileSizeBytes, limit, maxFileSizeBytes, maxItems, modelType, providerKind, retryAfterSeconds, and status. null when there are none; omitted from HTTP error bodies.Whether a retry can help:
automatic (the service retries on its own), manual (retry yourself), after_configuration (fix the knowledge base's setup in Dify first), or never (change the request).Stage the failure belongs to, for example
query_generation or credential-test. null when not applicable; omitted from HTTP error bodies.Reference to quote when contacting an administrator. May be
null in a successful response containing failure details, or omitted from an HTTP error body.What the run does:
sync: started by Sync Source, Update Source, a schedule, or Dify.crawl-preview: started by Preview Website Crawl. It keeps this kind while Import Selected Pages imports from it.crawl-import: started by Import Website Pages.online-document-import,online-drive-import: started by Import Source Items.
Dify also starts previews and imports when a source is added or edited there.
Internal ID of the knowledge base. Not the knowledge base ID in the path.
failure.code when state is failed. null otherwise.Items finished, including unchanged items a sync checked.
Always
0 for source runs: a failing item fails the whole run.Always
0 for source runs.Items the run expects to process: the pages or items an import requested, the pages a crawl preview has staged so far, or the source's items once a sync has listed them. null until known.
While an Import Website Pages run crawls its URLs, progress_completed and progress_total both count the pages crawled so far. Once every URL is crawled, they restart at 0 of the number of URLs.
Source the run belongs to.
Progress of the run.
Live states:
queued: waiting for a workercrawling: a crawl preview is fetching pagespreview_ready: a crawl preview is waiting for Import Selected Pages or Cancel Source Runimporting: importing and indexing itemssyncing: refreshing the source's documents
Terminal states:
completed: every item was imported or refreshed, indexed, and made activezero_results: a crawl preview found no pagesfailed: seefailurecanceled
After failed or canceled, Retry Source Run runs it again, and Sync Source starts a new sync.
Last change, ISO 8601.
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.Cursor for the next page, or
null on the last page. Send it back as cursor.