Skip to main content

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 pathWhat it does
GET /public/v1/sourcesList sources with their sync status and counts
POST /public/v1/sourcesCreate a source
POST /public/v1/sources/<source-id>/syncStart a sync now
POST /public/v1/sources/<source-id>/upload and /ingestPut files into a file-upload source and index them
Webhook event source.syncedDelivered 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.

FieldMeaning
sync_status, last_sync_at, last_sync_statsThe state of the last or current sync, when it ran, and its figures
sync_scheduleThe schedule the source syncs on without being asked
total_documents, total_chunksWhat is indexed
documents_discovered, documents_indexed, documents_emptyHow the last sync went: found, indexed, and found but with no text to index
embedding_statuscurrent, or a value saying the source was embedded with a model the tenant no longer uses and needs re-embedding
filterable_metadata_keysThe metadata keys a search may filter this source on; empty until an administrator declares them
has_domain_graph, graph_node_count, graph_edge_countWhether a knowledge graph was extracted and how big it is
acl_pendingPermissions are still being resolved, so a search may withhold results for now
enabled, quality_score, created_by, created_at, updated_atHousekeeping

Start a sync and follow it​

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}'

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.

FieldRequiredMeaning
nameYesThe name shown in Studio
connector_typeYesOne of the connector types the Knowledge reference lists, file_upload for a source you fill over the API
auth_typeYesoauth, api_key or service_account
configNoThe connector's own settings; the connector's page in the help centre says what it needs
auth_credential_idNoA credential saved in the platform, instead of secrets in config
sync_scheduleNoA cron expression or an interval; the default is every_1h
processing_configNoPer-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_status other than current means 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 FORBIDDEN on 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_total keeps growing: discovery is still running; discovery_complete turns true when the count is final.
  • errors above zero after a sync: read the source's last_sync_stats, and the failing documents' processing_error through GET /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

Describes the platform as of .

Was this page helpful?