# Sources, sync and the source-synced webhook

List the tenant's knowledge sources, create one over the API, start a sync on demand, read its progress, and let a webhook tell you when the sync has finished.

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](/developers/guides/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**

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

**Python**

```python

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"])
```

**TypeScript**

```typescript
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:

```json
{"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](/developers/guides/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` |

```bash
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](/developers/guides/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](/knowledge/knowledge-bases/keep-a-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.

## Related

- [Upload files and ingest](/developers/guides/upload-files-and-ingest)
- [Receive and verify webhooks](/developers/guides/receive-and-verify-webhooks)
- [Search retrieval options](/developers/guides/search-options)
- Knowledge

Source: https://docs.katonic.ai/developers/guides/sources-and-sync
