Update Sync Policy

Sets a source’s sync schedule, replacing the previous one, and returns it.

Saving does not start a sync. The first scheduled sync is due one interval after the update, and each later one an interval after the previous one was queued. To sync now, call Sync Source.

After each import into the source finishes, save the schedule again with the source’s new version. An import changes version, and a schedule still bound to the old one turns itself off at its next due time.

To pause scheduled syncs without changing the schedule, set the source’s status to disabled with Update Source. A sync that came due meanwhile runs when the source is set back to active.

For the read-then-save flow, see Sync and Schedule Sources.

1 min read

put/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy

Request example

curl --request PUT \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customIntervalSeconds": 21600,
  "enabled": true,
  "expectedRevision": 5,
  "expectedSourceVersion": 8,
  "mode": "custom"
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "customIntervalSeconds": 21600,
    "enabled": True,
    "expectedRevision": 5,
    "expectedSourceVersion": 8,
    "mode": "custom"
}

response = requests.request("PUT", 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}/sync-policy', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "customIntervalSeconds": 21600,
    "enabled": true,
    "expectedRevision": 5,
    "expectedSourceVersion": 8,
    "mode": "custom"
  })
});

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}/sync-policy',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS => '{
  "customIntervalSeconds": 21600,
  "enabled": true,
  "expectedRevision": 5,
  "expectedSourceVersion": 8,
  "mode": "custom"
}',
  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}/sync-policy"
	payload := strings.NewReader("{\n  \"customIntervalSeconds\": 21600,\n  \"enabled\": true,\n  \"expectedRevision\": 5,\n  \"expectedSourceVersion\": 8,\n  \"mode\": \"custom\"\n}")

	req, _ := http.NewRequest("PUT", 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}/sync-policy"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString("{\n  \"customIntervalSeconds\": 21600,\n  \"enabled\": true,\n  \"expectedRevision\": 5,\n  \"expectedSourceVersion\": 8,\n  \"mode\": \"custom\"\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}/sync-policy')

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

request = Net::HTTP::Put.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "customIntervalSeconds": 21600,
  "enabled": true,
  "expectedRevision": 5,
  "expectedSourceVersion": 8,
  "mode": "custom"
}'

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

Response

{
  "created_at": "2026-09-01T08:05:00Z",
  "custom_interval_seconds": 21600,
  "enabled": true,
  "expected_source_version": 8,
  "id": "8e7d6c5b-4a39-4f28-9e17-0d1c2b3a4f5e",
  "knowledge_space_id": "0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d",
  "mode": "custom",
  "next_run_at": "2026-10-21T08:30:00Z",
  "revision": 6,
  "source_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
  "updated_at": "2026-10-21T02:30:00Z"
}

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

{
  "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",
    "traceId": "7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83"
  },
  "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_resource_not_found",
  "failure": {
    "category": "not_found",
    "code": "KNOWLEDGE_FS_NOT_FOUND",
    "message": "The requested Agent Knowledge Base resource was not found.",
    "retryPolicy": "never",
    "traceId": "7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83"
  },
  "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",
    "traceId": "7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83"
  },
  "message": "The Agent Knowledge Base operation conflicts with the current resource state.",
  "status": 409
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "failure": {
    "action": "contact_admin",
    "category": "internal",
    "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
    "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
    "retryPolicy": "manual",
    "traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
  },
  "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
  "status": 502
}

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

put/knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy

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

customIntervalSecondsinteger#

Seconds between scheduled syncs, from 1 hour to 30 days. Required with mode: custom and rejected with the other modes.

Range: 3600–2592000

enabledbooleanrequired#

Whether scheduled syncs run. Must be false with mode: manual.

expectedRevisionintegerrequired#

The schedule's current revision, from Get Sync Policy. Send 0 when the source has no schedule yet. The revision also increases every time a scheduled sync starts, so read it right before updating. A stale value answers 409 and nothing changes.

Range: >= 0

expectedSourceVersionintegerrequired#

The source's current version, from Get Source or List Sources. It changes after every Update Source call and every completed import, so read it right before updating. A stale value answers 409 and nothing changes.

Range: >= 1

modeenum<string>required#

manual turns scheduled syncs off, interval syncs every 24 hours, and custom syncs every customIntervalSeconds.

Options:manualintervalcustom

Responses

application/json

The saved schedule. With mode: manual or enabled: false, next_run_at is null.

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.

Get Sync Policy Sync Source