Skip to main content
POST
Re-list a knowledge source from the start
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/knowledge/synchronized-sources/relist with { "sourceId": "<id>" } re-lists one source in the caller’s writable namespaces from the start, as Retry items does on the Console Knowledge › Health page. The source’s cursor is cleared and its mapping version raised, so its next run lists every item again, including items quarantined after failing three syncs in a row. It needs knowledge:manage and answers 200 with { sourceId, outcome }. MCP hosts call it through forge_call_operation with operationId relistSynchronizedSource. The re-list is audited as the credential. A missing id, a source outside the writable set or a source being removed answers 404 resource_missing (Knowledge source not found). An unknown field or a missing sourceId answers 400. While Forge is stopped by an operator (kill switch) it answers 403 operator_stopped. Each new Idempotency-Key re-lists again; a retry under the same key re-lists nothing. A repeat returns the recorded 200 only while the credential still holds knowledge:read and the source is still in its writable namespaces; otherwise it answers 403 for a missing knowledge:read, or 409 idempotency_result_unavailable. See Knowledge remedy replay.

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
Minimum string length: 1

Response

What the re-list did

data
object
required

A re-list's outcome. scheduled: the cursor was cleared and a run scheduled now. queued: a run holds the source; the next run re-lists. inactive: the source is paused or stopped, and nothing changed.

meta
object
required