Skip to main content
POST
Start a knowledge re-embed
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/reembed/start with the empty body {} schedules a re-embed, as Start re-embed does on the Console Knowledge › Settings page. It needs knowledge:manage and answers 200 with { runId }. MCP hosts call it through forge_call_operation with operationId startKnowledgeReembed. Knowledge search finds only entries embedded by the active embeddings model, so after a model change a namespace embedded by the previous one returns nothing until it is re-embedded. The re-embed moves every such stale namespace onto the active model, one namespace at a time, and the app vector tables alongside. It is deployment-wide and started by the credential. runId is the re-embed run already running, or null: a plan is scheduled, and it starts a run only when a namespace is stale. Only one run goes at a time. Read its progress with Read the latest knowledge re-embed run.
While a namespace is re-embedding, search for that namespace returns nothing until it is promoted.
Send an Idempotency-Key to retry safely: a repeat schedules nothing again, and returns the recorded response while the credential still holds knowledge:manage. See Knowledge settings and re-embed 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

Body

application/json

No fields: send {}.

Response

The re-embed was scheduled

data
object
required

The re-embed already running (runId), or null: a plan is scheduled and starts a run only when a namespace is stale. Read the run with reembed/getLatestRun.

meta
object
required