Update Source
Updates a source’s name, status, URI, metadata, or provider parameters, and can start a sync when the configuration changed.
Send at least one of name, status, uri, metadata, or providerParameters. expectedVersion and syncAfterUpdate alone are rejected.
For how to start and follow a sync, see Sync and Schedule Sources.
curl --request PATCH \
--url https://{api_base_url}/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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}"
payload = {
"expectedVersion": 7,
"name": "Docs site (v2)",
"status": "active",
"syncAfterUpdate": True,
"uri": "https://docs.example.com/v2"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
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'
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}', 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/{source_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'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);
$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/{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))
}HttpResponse<String> response = Unirest.patch("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expectedVersion\": 7,\n \"name\": \"Docs site (v2)\",\n \"status\": \"active\",\n \"syncAfterUpdate\": true,\n \"uri\": \"https://docs.example.com/v2\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedVersion\": 7,\n \"name\": \"Docs site (v2)\",\n \"status\": \"active\",\n \"syncAfterUpdate\": true,\n \"uri\": \"https://docs.example.com/v2\"\n}"
response = http.request(request)
puts response.read_body{
"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
}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).
Body
Optional fields marked nullable treat null as omitted.
The normalized request must fit within 262,144 UTF-8 bytes. See Request Size Limits.
- Update Metadata
- Rename Source
- Update Provider Parameters
- Change Status
- Change Source URL
Supply at least one non-null metadata, name, providerParameters, status, or uri. expectedVersion and syncAfterUpdate alone do not make an update.
The source's current version from List Sources or Get Source. A stale value answers 409 and nothing changes. Omit it to let the last write win.
x >= 1Parameters defined by the selected data source. This replaces the entire stored metadata.parameters object, so include every value you need to keep. Values are booleans, finite numbers, or strings. Credential-like keys are rejected.
If Get Source does not expose the complete non-sensitive parameters and you do not already know the data source's parameter contract, configure the source in Dify instead.
When true, asks for a sync run after the write. The response carries the run as sync_workflow, or sync_workflow: null when the call started none.
A sync starts only when this call changes uri, providerParameters, or a metadata value, and the source's status is not disabled. Re-sending the current values does not start a sync. To sync without changing the source, call Sync Source.
For a website source with a saved page list, sync refreshes those pages. Change the list with Import Website Pages or Import Selected Pages.
Response
The updated 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 PATCH \
--url https://{api_base_url}/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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}"
payload = {
"expectedVersion": 7,
"name": "Docs site (v2)",
"status": "active",
"syncAfterUpdate": True,
"uri": "https://docs.example.com/v2"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
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'
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}', 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/{source_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'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);
$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/{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))
}HttpResponse<String> response = Unirest.patch("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expectedVersion\": 7,\n \"name\": \"Docs site (v2)\",\n \"status\": \"active\",\n \"syncAfterUpdate\": true,\n \"uri\": \"https://docs.example.com/v2\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedVersion\": 7,\n \"name\": \"Docs site (v2)\",\n \"status\": \"active\",\n \"syncAfterUpdate\": true,\n \"uri\": \"https://docs.example.com/v2\"\n}"
response = http.request(request)
puts response.read_body{
"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
}