Knowledge

The agents answer from knowledge bases: sets of sources (pages, sites, text, files) that ShowPilot chunks, embeds and keeps current. The API opens that up in both directions: read and manage the sources, and run the same retrieval the agents run.

Retrieve or ask

Two calls, one difference.

• POST /v1/knowledge/retrieve returns ranked chunks with a score, the source and a citation, and nothing else. Use it when you have your own model and want ShowPilot's retrieval underneath it: a support tool, an internal assistant, a search box.
• POST /v1/knowledge/ask runs the same retrieval and returns one grounded answer with citations. No chat session is created, no visitor, no analytics. Use it when you want the finished thing.

Both take the same targeting: an agentId to search exactly what that agent sees (its own base plus every shared base attached to it), baseIds to search those bases, or neither to search every base in the workspace. When the sources do not cover a question, ask says so instead of guessing.

Both draw from a separate, smaller rate-limit bucket than the rest of the API, because a search box will call them far more often than a nightly job calls anything else.

curl "https://api.showpilot.com/v1/knowledge/retrieve" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how much is the Pro plan", "limit": 5 }'

Sources

GET /v1/knowledge/bases lists every base with its refresh mode, source counts and the agents that read it. POST /v1/knowledge/bases/{id}/sources adds a page by URL; set includeSubpages to crawl a site from that page. A new source lands as pending and the worker ingests it within a minute or two; poll GET /v1/knowledge/sources/{id} for loaded or failed. DELETE removes a source and its vectors at once, so the agents stop answering from it immediately.

File sources (PDFs) are added in the dashboard for now. Text snippets too.

Keeping a base current

Each base has a refresh mode, the same one Settings shows:

PATCH /v1/knowledge/bases/{id} sets the mode. POST /v1/knowledge/bases/{id}/refresh queues a full pass now, whatever the mode, exactly as the Refresh button does.

Scopes

knowledge:read for the lists, knowledge:write for sources and refresh, knowledge:query for retrieve and ask. A key made for a search box needs only the last one.

Every write here (add a source, remove one, refresh, change the refresh mode) takes an Idempotency-Key header; retrieve and ask are POSTs that only read and need none. See Errors.