Sources, sync and the source-synced webhook
A knowledge source is what the knowledge engine indexes: a connector to a system such as Confluence or a database, or a bucket of uploaded files. The API lists sources with their sync state and document counts, creates them, starts a sync outside its schedule, and reports progress. A webhook closes the loop by telling your application when a sync has finished, so it can search the new content without polling.
Who can use it: listing sources needs Knowledge search or Documents, and starting a sync needs Load knowledge graph. Creating a source needs the Documents scope. Processing a file-upload source's pending documents needs the Load knowledge graph scope; see Upload files and ingest. Registering the webhook endpoint is done on the Webhooks tab of the Developer Hub by a Builder or higher.
The routes
| Method and path | What it does |
|---|---|
GET /public/v1/sources | List sources with their sync status and counts |
POST /public/v1/sources | Create a source |
POST /public/v1/sources/<source-id>/sync | Start a sync now |
POST /public/v1/sources/<source-id>/upload and /ingest | Put files into a file-upload source and index them |
Webhook event source.synced | Delivered to your endpoint when a sync completes |
List sources and read their state
GET /public/v1/sources takes enabled_only, offset and limit (default 50). Each source carries the fields below; the counts are what a search can reach today.
| Field | Meaning |
|---|---|
sync_status, last_sync_at, last_sync_stats | The state of the last or current sync, when it ran, and its figures |
sync_schedule | The schedule the source syncs on without being asked |
total_documents, total_chunks | What is indexed |
documents_discovered, documents_indexed, documents_empty | How the last sync went: found, indexed, and found but with no text to index |
embedding_status | current, or a value saying the source was embedded with a model the tenant no longer uses and needs re-embedding |
filterable_metadata_keys | The metadata keys a search may filter this source on; empty until an administrator declares them |
has_domain_graph, graph_node_count, graph_edge_count | Whether a knowledge graph was extracted and how big it is |
acl_pending | Permissions are still being resolved, so a search may withhold results for now |
enabled, quality_score, created_by, created_at, updated_at | Housekeeping |
Start a sync and follow it
- cURL
- Python
- TypeScript
curl -X POST "https://<your tenant host>/public/v1/sources/<source-id>/sync" \
-H "Authorization: Bearer kapi_..." \
-H "Content-Type: application/json" \
-d '{"full_sync": false}'
import requests
BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}
status = requests.post(f"{BASE}/sources/<source-id>/sync", headers=HEADERS,
json={"full_sync": False}).json()
print(status["status"], status["documents_processed"], "of", status["documents_total"])
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "Content-Type": "application/json" };
const r = await fetch(`${BASE}/sources/<source-id>/sync`, {
method: "POST", headers, body: JSON.stringify({ full_sync: false }),
});
const status = await r.json();
console.log(status.status, status.documents_processed, "of", status.documents_total);
The body takes two switches. full_sync re-reads every document instead of only what changed since the last run. force_inline runs the sync inside the API process instead of handing it to the workflow engine; keep it for small sources and troubleshooting, because a long inline sync holds the request open.
The response is the sync status: source_id, status, progress, documents_processed and documents_total, documents_discovered with discovery_complete (discovery runs first, so the total grows until it is), errors, started_at and estimated_completion. Re-read GET /public/v1/sources for the same figures while the sync runs; the source's sync_status and last_sync_stats update as it goes.
Hear back with a webhook
Subscribe an endpoint to the source.synced event on the Webhooks tab. When a sync completes, the platform posts one delivery per subscribed endpoint:
{"id":"evt_3f9c...","type":"source.synced","timestamp":"2026-09-13T04:12:09Z","data":{"source_id":"...","...":"..."}}
data carries exactly five keys: source_id, documents_synced and documents_processed (the same number), errors (how many documents failed) and total_chunks. There is no status, run id or duration, and there is no separate failure event: a run that ended in error, or indexed nothing, delivers the same source.synced with errors above zero. Read errors, not the event name, and re-read the source for its sync_status when it matters. Verify the X-Katonic-Signature header before acting, answer within ten seconds, and dedupe on id; Receive and verify webhooks has the code.
On the current build only a sync that runs inside the API process publishes this event; one handed to the platform's workflow engine does not. Treat the webhook as a fast path and keep a slower poll of sync_status behind it.
Create a source
POST /public/v1/sources takes the fields below and answers with the source record above.
| Field | Required | Meaning |
|---|---|---|
name | Yes | The name shown in Studio |
connector_type | Yes | One of the connector types the Knowledge reference lists, file_upload for a source you fill over the API |
auth_type | Yes | oauth, api_key or service_account |
config | No | The connector's own settings; the connector's page in the help centre says what it needs |
auth_credential_id | No | A credential saved in the platform, instead of secrets in config |
sync_schedule | No | A cron expression or an interval; the default is every_1h |
processing_config | No | Per-source overrides: parsing_mode, chunk_size, rate_limit_rps, and graph_extraction set to inherit, on or off |
curl -X POST "https://<your tenant host>/public/v1/sources" \
-H "Authorization: Bearer kapi_..." \
-H "Content-Type: application/json" \
-d '{"name": "Vendor contracts", "connector_type": "file_upload", "auth_type": "api_key",
"sync_schedule": "every_1h", "processing_config": {"graph_extraction": "inherit"}}'
The key needs the Documents scope, and the key's owner must themselves be allowed to create knowledge sources: a key never does more than its owner may. Upload files and ingest covers filling the source.
Limits and behaviour
- Connector-backed sources sync on their schedule and on demand through the sync route; the ingest route refuses them with 400. File-upload sources are filled through upload and ingest.
embedding_statusother thancurrentmeans searches over this source score against an old embedding model until an administrator re-embeds it; see Keep a knowledge source current in the help centre.- Sources are tenant-wide, but what a search returns from them is filtered by the permissions of the key's owner.
Troubleshooting
- 403 with
FORBIDDENon create: the key lacks the Documents scope, or the key's owner may not create knowledge sources. The list and sync routes each need a scope of their own, so confirm the key carries them. - 404 on sync: the source id is wrong or the source belongs to another tenant.
- A sync's
documents_totalkeeps growing: discovery is still running;discovery_completeturns true when the count is final. errorsabove zero after a sync: read the source'slast_sync_stats, and the failing documents'processing_errorthroughGET /public/v1/documents/<doc-id>.- No webhook arrives: the endpoint is paused, not subscribed to
source.synced, or unreachable; the Webhooks tab's Recent deliveries shows the attempt.
The same task elsewhere