Sync Knowledge Base Now

Immediately triggers an incremental sync of the sourced knowledge in a knowledge base. Currently only the Google Drive source is supported.

Note:

The endpoint returns immediately after completing validation and planning, so what it returns is "accepted", not "updated".

Rate limit: at most 1 request per minute per Agent / Workflow.

Request Method

POST

Request URL

Choose the corresponding path based on the resource type that the API Key belongs to. The request parameters, response structure, and rate-limiting rules of the two endpoints are exactly the same.

• Agent:

https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync

• Workflow:

https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync

The request / response descriptions below apply to both paths; the examples are written using the Agent path.

Request Authentication

For details, see the authentication description in the API Overview.

Request

Request Example

• Sync specified knowledge bases:

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive",
    "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'

                    

• Sync all knowledge bases under this Agent:

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive"
}'

                    

Request Headers

Request Parameters

Response

Response Example

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "accepted": true,
        "source": "google-drive",
        "matched_knowledge_base_count": 2,
        "matched_doc_count": 37,
        "matched_folder_count": 3,
        "skipped": [
            {
                "reason": "DRIVE_NOT_AUTHORIZED",
                "message": "The document owner has not authorized Google Drive, or the authorization has expired.",
                "knowledge_base_id": "6a44c3512ceb43775567391e",
                "doc_count": 8
            },
            {
                "reason": "KNOWLEDGE_BASE_NOT_FOUND",
                "message": "Knowledge base does not exist or does not belong to this agent.",
                "knowledge_base_id": "deadbeefdeadbeefdeadbeef"
            }
        ],
        "scheduled_round_running": false
    }
}

                    

Success Response

skipped[].reason Values

Failure Response

Common error codes:

Response example when source is invalid:

                      
                      {
    "code": 40000,
    "message": "Unsupported source: sharepoint. Supported: google-drive"
}

                    

Usage Notes

It returns "accepted", not "completed"

The endpoint returns immediately after completing validation and planning; the actual fetching, parsing, and vectorization run asynchronously in the background. Therefore matched_doc_count is "how many documents will be checked this time", not "how many documents were updated". To confirm the final result, poll the Get Doc List endpoint to check document status; when a document's status becomes AVAILABLE, it means the document has finished syncing.

It only does incremental sync and does not consume quota repeatedly

For each document, the system first compares the last modified time on Google Drive:

• Source document unchanged: skipped; it is not re-downloaded, re-parsed, and does not consume quota.
• Source document changed: re-fetched, re-parsed, and re-vectorized.
• New files in a bound folder: automatically added as knowledge documents.

Therefore calling this endpoint repeatedly is safe; unchanged content does not incur extra charges.

This endpoint cannot retry documents that failed to parse

The incremental judgment only looks at whether the source document on Google Drive has changed, not what status the document is currently in.

Therefore, a document that previously failed to parse (with status FAIL) will not be reprocessed by this endpoint as long as its source file on Google Drive has not been modified — it will be treated as "source document unchanged" and skipped directly, its status stays unchanged, and it will not appear in skipped.

To retry documents that failed to parse, use the Re-embed Failed Docs endpoint. Or make a modification to the source file on Google Drive so that its last modified time is updated, and this endpoint will re-fetch it.

Syncing deletes knowledge documents

This endpoint does not only add and update; it also deletes knowledge documents according to the current state of Google Drive.

When a bound Google Drive folder becomes empty, all knowledge documents already imported from that folder are deleted. The trigger condition is that the folder is still accessible on Google Drive but no files can be enumerated in it. The system first validates the folder's accessibility; when it cannot obtain the folder metadata (the folder was moved, permissions changed, temporarily unreachable, etc.), it skips the deletion to avoid accidental removal.

The deletion scope is limited to "this folder + this knowledge base". When the same Google Drive folder is referenced by multiple knowledge bases, the knowledge bases do not affect each other.

This behavior is consistent with the system's scheduled sync; this endpoint simply makes it happen earlier. However, because this endpoint also covers documents that had no scheduled sync plan configured at import time (which would not otherwise be deleted by any automatic process), confirm before calling that the folder content on the Google Drive side is as expected.

Coverage

The sync scope covers all documents from Google Drive in the knowledge base, including the portion that had no scheduled sync plan configured at import time — this portion is not processed by the system's scheduled rounds and can only be updated through this endpoint.

Rate Limiting

• At most 1 request per minute per Agent / Workflow. The two paths share the same counter, so switching paths does not bypass the rate limit.
• It is also subject to the requests-per-minute (RPM) limit for knowledge-base APIs of the organization plan, sharing that quota with other knowledge-base endpoints.
• When the previous sync of the same Agent / Workflow has not finished, calling again returns accepted=false and reason=SYNC_IN_PROGRESS.

Relationship with Scheduled Sync

This endpoint and the system's scheduled sync are independent of each other and do not block each other. When scheduled_round_running is true, this request is still accepted and will not be rejected because a scheduled round is running.

When both process the same document at the same time, they do not produce duplicate content: the system makes an incremental judgment based on the source document's last modified time, and already imported files are not created again.

Scheduled sync runs automatically at the frequency configured for each knowledge base, while this endpoint ignores that frequency and triggers immediately. The two complement each other: scheduled sync handles routine updates, and this endpoint handles the "sync right now" scenario.