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.

1 min read

post/knowledge-fs/spaces/{knowledge_base_id}/sources

Request example

curl --request POST \
  --url https://api.dify.ai/v1/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.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
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"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources', {
  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"
  })
});

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 => 'POST',
  CURLOPT_POSTFIELDS => '{
  "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);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/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))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\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}"))
    .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::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "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"
}'

response = http.request(request)
puts response.read_body

Response

{
  "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
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "name"
      ],
      "type": "missing"
    }
  ]
}

{
  "code": "knowledge_fs_invalid_request",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never"
  },
  "message": "The Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "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_conflict",
  "failure": {
    "action": "retry",
    "category": "conflict",
    "code": "KNOWLEDGE_FS_CONFLICT",
    "message": "The Agent Knowledge Base operation conflicts with the current resource state.",
    "retryPolicy": "manual"
  },
  "message": "The Agent Knowledge Base operation conflicts with the current resource state.",
  "status": 409
}

{
  "code": "knowledge_fs_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

{
  "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
}

post/knowledge-fs/spaces/{knowledge_base_id}/sources

Authorization

Authorizationstringheaderrequired#

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_idstringrequired#

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

application/json

connectionIdstring#

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.

metadataobject#

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.

namestringrequired#

Display name.

Length: 1–200

permissionScopestring[]#

Leave empty or omit. Only an empty list is accepted.

Items: max 0

statusenum<string>#

disabled pauses scheduled syncs.

Default: "active"

Options:activedisablednull

typeenum<string>required#

Send 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.

Options:connectorobject-storageuploadweb

uristringrequired#

Crawl root URL for web. connector://<connectionId> for connector, matching what Dify writes.

Length: 1–4096

Responses

application/json

The created source.

connection_idstring#

Connection the source uses for credentials. Pass it as connectionId when binding another source to the same connection. null when unbound.

created_atstring#

Creation time, ISO 8601.

credential_configuredboolean#

true when the source holds a credential reference of its own. null when it holds none, as with sources bound to a connection.

idstring#

Source ID.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

last_synced_atstring#

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.

metadataobject#

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.

namestring#

Display name.

permission_scopestring[]#

Content scopes required to read this source. An empty list adds no content restriction within the knowledge base. Knowledge base authorization still applies.

statusstring#

active, syncing, error, or disabled. Most operations return the stored value. List Sources derives it from the latest sync run:

failed or canceled run: error
completed or zero_results run: active
Any live run: syncing

disabled is never overridden.

sync_policyobject#

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

created_atstring#

Creation time, ISO 8601.

custom_interval_secondsinteger#

Interval in seconds for mode: custom. null for the other modes.

enabledboolean#

Whether scheduled syncs run. Always false with mode: manual.

expected_source_versioninteger#

Source version the schedule is bound to.

idstring#

Sync policy ID. It stays the same across updates.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

modestring#

manual (no schedule), interval (every 24 hours), or custom (every custom_interval_seconds).

next_run_atstring#

When the next scheduled sync is due, ISO 8601. null when nothing is scheduled.

revisioninteger#

Schedule revision. Send it as expectedRevision on Update Sync Policy. It increases on every update and every time a scheduled sync starts.

source_idstring#

Source the schedule belongs to.

updated_atstring#

Last change, ISO 8601. Also moves when a scheduled sync starts.

sync_workflowobject#

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

canceled_atstring#

When the run was canceled. null unless state is canceled.

checkpointstring#

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.

completed_atstring#

When the run ended (completed, zero_results, failed, or canceled), ISO 8601. null while it runs.

created_atstring#

Creation time, ISO 8601.

cursorstring#

Provider cursor the run resumes from. null when the run has not paged.

execution_attemptsinteger#

Times a worker has picked up the run, including after Retry Source Run, which does not reset it.

failureobject#

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 attributes

actionstring#

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.

categorystring#

Kind of failure: authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.

codestring#

Stable error code in upper snake case, for example KNOWLEDGE_FS_CONFLICT or SOURCE_CREDENTIAL_TEST_FAILED.

messagestring#

Public message for the error code or failure category. Provider error details are not exposed.

parametersobject#

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.

retryPolicystring#

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).

stagestring#

Stage the failure belongs to, for example query_generation or credential-test. null when not applicable; omitted from HTTP error bodies.

traceIdstring#

Reference to quote when contacting an administrator. May be null in a successful response containing failure details, or omitted from an HTTP error body.

idstring#

Run ID. Pass it to Get Source Run, Cancel Source Run, or Retry Source Run.

kindstring#

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.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

last_error_codestring#

failure.code when state is failed. null otherwise.

max_execution_attemptsinteger#

Limit on execution_attempts. Once it is reached, Retry Source Run answers 409.

progress_completedinteger#

Items finished, including unchanged items a sync checked.

progress_failedinteger#

Always 0 for source runs: a failing item fails the whole run.

progress_skippedinteger#

Always 0 for source runs.

progress_totalinteger#

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_idstring#

Source the run belongs to.

statestring#

Progress of the run.

Live states:

queued: waiting for a worker
crawling: a crawl preview is fetching pages
preview_ready: a crawl preview is waiting for Import Selected Pages or Cancel Source Run
importing: importing and indexing items
syncing: refreshing the source's documents

Terminal states:

completed: every item was imported or refreshed, indexed, and made active
zero_results: a crawl preview found no pages
failed: see failure
canceled

After failed or canceled, Retry Source Run runs it again, and Sync Source starts a new sync.

updated_atstring#

Last change, ISO 8601.

typestring#

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.

updated_atstring#

Last change, ISO 8601.

uristring#

Crawl root URL for web sources. connector://<connection_id> for Dify-created connector sources.

versioninteger#

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.

List Source Connections List Sources