Sync & Embedding#
Writing a product, FAQ or location stores it — but the chatbot cannot answer from it yet. Retrieval works on embeddings, and a new or changed row has none until a sync runs. This is the single most common surprise when integrating, so it is worth reading before you build.
Creates and updates need a sync. Deletes do not.
A delete purges the row's embedding immediately, so it stops appearing in answers straight away. A create or update becomes answerable only after the next sync completes.
Endpoints#
| Method | Path |
|---|---|
| POST | /knowledge-bases/{kbId}/sync |
| GET | /knowledge-bases/{kbId}/sync-status |
Trigger a sync#
Call this once after a batch of writes, not once per row. Rows that have not changed are skipped.
curl -X POST https://api.gydr.ai/knowledge-bases/{kbId}/sync \
-H "X-API-Key: api_your_api_key"Poll until it finishes#
The sync runs in the background, so the trigger returning 200 means “started”, not “done”. Poll sync-status until syncStatus leaves syncing.
curl https://api.gydr.ai/knowledge-bases/{kbId}/sync-status \
-H "X-API-Key: api_your_api_key"neverEmbedded counts rows that have never been embedded at all. A row that was embedded earlier and has since changed is not counted — determining that exactly would mean re-deriving every row's embedding text on each poll.
Limits and conflicts#
- A knowledge base holds at most 10,000 items. Writes past the ceiling are refused, because a larger knowledge base could never be embedded.
- Only one sync runs at a time per knowledge base. Starting a second returns
409— including when a colleague started one from the Console. - A sync is metered per item embedded. If the account balance is short, the trigger returns
402and nothing starts.