Skip to main content
POST
Request a knowledge source sync
Takes { "sourceId": "<id>" } from the sources.items of knowledge health and answers { sourceId, outcome }: scheduled (a run was scheduled and audited), running (a run already holds the source; nothing scheduled) or inactive (a paused or stopped source; nothing scheduled). The source must be in the caller’s writable namespaces; a missing id, a source outside the writable set and a source being removed answer 404. See Remedies.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (Idempotency-Replayed: true) only when the route's current authorization policy permits disclosure; otherwise 409 idempotency_result_unavailable. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

synchronizedSourceId
string
required

The source's id (sources.items[].id in knowledge health).

Response

What the request did

data
object
required

A sync request's outcome. scheduled: a sync run was scheduled and audited. running: a run already holds the source, so nothing was scheduled. inactive: the source is paused or stopped, so nothing was scheduled.

meta
object
required