> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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](/en/api-reference/source-syncs-and-imports/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](/en/api-reference/sources/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](/en/api-reference/guides/knowledge-base#sync-and-schedule-sources). ## OpenAPI ````yaml /en/api-reference/openapi_service.json put /knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy: put: tags: - Sources summary: Update Sync Policy description: >- 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](/en/api-reference/source-syncs-and-imports/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](/en/api-reference/sources/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](/en/api-reference/guides/knowledge-base#sync-and-schedule-sources). operationId: updateSourceSyncPolicy parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- Source ID. From [List Sources](/en/api-reference/sources/list-sources). in: path name: source_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: custom: summary: Request Example - Custom interval value: customIntervalSeconds: 21600 enabled: true expectedRevision: 5 expectedSourceVersion: 8 mode: custom interval: summary: Request Example - Every 24 hours value: enabled: true expectedRevision: 0 expectedSourceVersion: 3 mode: interval manual: summary: Request Example - No schedule value: enabled: false expectedRevision: 6 expectedSourceVersion: 8 mode: manual schema: additionalProperties: false properties: customIntervalSeconds: description: >- Seconds between scheduled syncs, from 1 hour to 30 days. Required with `mode: custom` and rejected with the other modes. maximum: 2592000 minimum: 3600 type: integer enabled: description: >- Whether scheduled syncs run. Must be `false` with `mode: manual`. type: boolean expectedRevision: description: >- The schedule's current `revision`, from [Get Sync Policy](/en/api-reference/sources/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. minimum: 0 type: integer expectedSourceVersion: description: >- The source's current `version`, from [Get Source](/en/api-reference/sources/get-source) or [List Sources](/en/api-reference/sources/list-sources). It changes after every [Update Source](/en/api-reference/sources/update-source) call and every completed import, so read it right before updating. A stale value answers `409` and nothing changes. minimum: 1 type: integer mode: description: >- `manual` turns scheduled syncs off, `interval` syncs every 24 hours, and `custom` syncs every `customIntervalSeconds`. enum: - manual - interval - custom type: string required: - enabled - expectedRevision - expectedSourceVersion - mode type: object required: true responses: '200': content: application/json: examples: success: summary: Response Example value: 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' schema: $ref: '#/components/schemas/KnowledgeBaseSyncPolicy' description: >- The saved schedule. With `mode: manual` or `enabled: false`, `next_run_at` is `null`. '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - customIntervalSeconds type: greater_than_equal knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) value: 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 description: >- - `knowledge_fs_invalid_request`: the request failed validation. `violations` names each failing field. Causes: - A field is missing or of the wrong type, or the body carries an unknown key. - `mode` is not one of the listed values. - `customIntervalSeconds` is out of range, missing with `mode: custom`, or sent with another mode. - `knowledge_fs_invalid_request`: `mode: manual` was sent with `enabled: true`, or `source_id` is not a UUID. - `knowledge_fs_invalid_request`: `source_id` is malformed. '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: 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 not_found: summary: not_found (feature off) value: 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 description: >- - `knowledge_fs_resource_not_found`: no source with this ID exists in the knowledge base, the key cannot read it, or its deletion has been accepted. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict value: 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 description: >- - `knowledge_fs_conflict`: `expectedRevision` is not the schedule's current `revision`, or `expectedSourceVersion` is not the source's current `version`. The body does not say which, so read both again with [Get Sync Policy](/en/api-reference/sources/get-sync-policy) and [Get Source](/en/api-reference/sources/get-source), then resend. '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: 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 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. The schedule may have been saved. Read it with [Get Sync Policy](/en/api-reference/sources/get-sync-policy) before sending another update. A resend with the old `expectedRevision` answers `409` if the first call landed. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: 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 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. components: schemas: KnowledgeBaseSyncPolicy: properties: created_at: description: Creation time, ISO 8601. type: string custom_interval_seconds: description: 'Interval in seconds for `mode: custom`. `null` for the other modes.' nullable: true type: integer enabled: description: 'Whether scheduled syncs run. Always `false` with `mode: manual`.' type: boolean expected_source_version: description: Source `version` the schedule is bound to. type: integer id: description: Sync policy ID. It stays the same across updates. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string mode: description: >- `manual` (no schedule), `interval` (every 24 hours), or `custom` (every `custom_interval_seconds`). type: string next_run_at: description: >- When the next scheduled sync is due, ISO 8601. `null` when nothing is scheduled. nullable: true type: string revision: description: >- Schedule revision. Send it as `expectedRevision` on [Update Sync Policy](/en/api-reference/sources/update-sync-policy). It increases on every update and every time a scheduled sync starts. type: integer source_id: description: Source the schedule belongs to. type: string updated_at: description: Last change, ISO 8601. Also moves when a scheduled sync starts. type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 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](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.