Update Source - Dify Docs

patch/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}

Request example

curl --request PATCH \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "expectedVersion": 7,
  "name": "Docs site (v2)",
  "status": "active",
  "syncAfterUpdate": true,
  "uri": "https://docs.example.com/v2"
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "expectedVersion": 7,
    "name": "Docs site (v2)",
    "status": "active",
    "syncAfterUpdate": True,
    "uri": "https://docs.example.com/v2"
}

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

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "expectedVersion": 7,
    "name": "Docs site (v2)",
    "status": "active",
    "syncAfterUpdate": true,
    "uri": "https://docs.example.com/v2"
  })
});

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/{source_id}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_POSTFIELDS => '{
  "expectedVersion": 7,
  "name": "Docs site (v2)",
  "status": "active",
  "syncAfterUpdate": true,
  "uri": "https://docs.example.com/v2"
}',
  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/{source_id}"
	payload := strings.NewReader("{\n  \"expectedVersion\": 7,\n  \"name\": \"Docs site (v2)\",\n  \"status\": \"active\",\n  \"syncAfterUpdate\": true,\n  \"uri\": \"https://docs.example.com/v2\"\n}")

	req, _ := http.NewRequest("PATCH", 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/{source_id}"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\n  \"expectedVersion\": 7,\n  \"name\": \"Docs site (v2)\",\n  \"status\": \"active\",\n  \"syncAfterUpdate\": true,\n  \"uri\": \"https://docs.example.com/v2\"\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/{source_id}')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Patch.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "expectedVersion": 7,
  "name": "Docs site (v2)",
  "status": "active",
  "syncAfterUpdate": true,
  "uri": "https://docs.example.com/v2"
}'

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

Response

{
  "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": null,
  "metadata": {
    "client_request_id": "source-20260907-0001",
    "parameters": {
      "url": "https://docs.example.com/v2"
    },
    "providerKind": "website",
    "tenantId": "2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f"
  },
  "name": "Docs site (v2)",
  "permission_scope": [],
  "status": "active",
  "sync_policy": null,
  "sync_workflow": {
    "canceled_at": null,
    "checkpoint": "queued",
    "completed_at": null,
    "created_at": "2026-09-06T02:00:00Z",
    "cursor": null,
    "execution_attempts": 0,
    "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": 0,
    "progress_failed": 0,
    "progress_skipped": 0,
    "progress_total": null,
    "source_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
    "state": "queued",
    "updated_at": "2026-09-06T02:00:00Z"
  },
  "type": "web",
  "updated_at": "2026-09-06T02:00:00Z",
  "uri": "https://docs.example.com/v2",
  "version": 8
}

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

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "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": "SOURCE_VERSION_CONFLICT",
    "message": "The Agent Knowledge Base operation conflicts with the current resource state.",
    "retryPolicy": "manual",
    "traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
  },
  "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
}

patch/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}

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.

source_idstringrequired#

Source ID. From List Sources.

Body

application/json

Any of

metadataobjectrequired#

Responses

application/json

The updated 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.

Get Source Delete Source