Add a knowledge base & verify coverage

Knowledge is what your agent answers from. You add sources — a help-center URL, an uploaded document, plain text, or structured FAQs — and the platform indexes them so the agent retrieves the right passage at answer time instead of guessing. This guide adds a source, confirms it indexed, previews retrieval, and reviews the questions callers ask that you don’t yet cover.

Authenticate with Authorization: Bearer flowyte_sk_…. All paths below are relative to https://builder.flowyte.com/api/v1.

What you’ll use

Action	Endpoint	Scope
Add a source	`POST /agents/{agentId}/knowledge/sources`	`knowledge:write`
Poll ingest status	`GET /agents/{agentId}/knowledge/sources/{id}`	`knowledge:read`
Preview retrieval	`POST /agents/{agentId}/knowledge/preview`	`knowledge:read`
Review gaps	`GET /agents/{agentId}/knowledge-gaps`	`analytics:read`
Curate a gap	`PATCH /agents/{agentId}/knowledge-gaps/{gapId}`	`analytics:write`

Add a source

A source has a kind (url, file, text, or faq) and a label. Use url to crawl a page, text to paste content inline, or file with a file_id from an upload.

curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/knowledge/sources \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "url", "label": "Help center", "url": "https://acme.com/help" }'

The source is created with status: "pending". Capture data.id as SOURCE_ID.

Poll until indexed

Ingestion is asynchronous — the source moves pending → indexed. Poll the source every few seconds until data.status is indexed. Don’t rely on it before then.

curl https://builder.flowyte.com/api/v1/agents/$AGENT_ID/knowledge/sources/$SOURCE_ID \
  -H "Authorization: Bearer $FLOWYTE_API_KEY"
# { "data": { "id": "...", "status": "indexed", ... } }

Preview retrieval

Before you trust it, ask what the agent would retrieve for a real question. preview returns the matching chunks and a topScore — a low score or empty chunks means the answer isn’t covered yet.

curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/knowledge/preview \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Do you offer same-day appointments?" }'

Pass sourceIds to scope the preview to specific sources. Use this to confirm a newly added source actually answers the question you added it for.

Review knowledge gaps

Once callers start talking to the agent, the questions it couldn’t answer surface as knowledge gaps — deduped and, above a small volume floor, ranked by how often and how recently they hit. This is the loop that makes the agent better over time.

curl "https://builder.flowyte.com/api/v1/agents/$AGENT_ID/knowledge-gaps?status=open" \
  -H "Authorization: Bearer $FLOWYTE_API_KEY"

The response’s dataState is collecting until enough calls land, then ready. When ranked is true, each gap carries a gapId, rankScore, and classification.

Close or curate a gap

Fix a real gap by adding a source that covers it (back to step 1), then mark the gap handled. You can set a ranked gap to in_progress, dismissed, or back to open — covered is set automatically once the live knowledge base answers it.

curl -X PATCH https://builder.flowyte.com/api/v1/agents/$AGENT_ID/knowledge-gaps/$GAP_ID \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "in_progress" }'

Learn how retrieval fits the rest of the agent in Knowledge.

​What you’ll use

What you’ll use