Knowledge

The bases and sources the agents answer from, retrieval with citations, and refresh control.

Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.

List knowledge bases

GET /knowledge/bases

Scope: knowledge:read. Operation id: listKnowledgeBases.

Every base in the workspace with its refresh mode, last refresh, source counts and the agents that read it.

Example request

curl "https://api.showpilot.com/v1/knowledge/bases" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

All bases; small enough not to page.

Field	Type	Always	Meaning
`items`	array of KnowledgeBase	yes

KnowledgeBase

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string or null	yes
`shared`	boolean	yes	A shared base can be attached to many agents; a personal one belongs to one.
`status`	string	yes	`active`, `indexing` or `failed`.
`refresh`	object	yes
`lastRefresh`	object or null	yes	The last refresh receipt
`sources`	object	yes
`agentIds`	array of string (uuid)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

One base with its sources

GET /knowledge/bases/{id}

Scope: knowledge:read. Operation id: getKnowledgeBase.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)	The base's UUID.

Example request

curl "https://api.showpilot.com/v1/knowledge/bases/b0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The base and every source in it.

Every field of KnowledgeBase, plus:

Field	Type	Always	Meaning
`sources`	array of KnowledgeSource	yes

KnowledgeBase

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string or null	yes
`shared`	boolean	yes	A shared base can be attached to many agents; a personal one belongs to one.
`status`	string	yes	`active`, `indexing` or `failed`.
`refresh`	object	yes
`lastRefresh`	object or null	yes	The last refresh receipt
`sources`	object	yes
`agentIds`	array of string (uuid)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

KnowledgeSource

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`baseId`	string (uuid)	yes
`kind`	string	yes	`url`, `sitemap`, `text` or `file`.
`name`	string	yes
`url`	string or null (uri)	yes	For url and sitemap kinds.
`status`	string	yes	`pending`, `indexing`, `loaded` or `failed`.
`error`	string or null	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Set how a base keeps itself current

PATCH /knowledge/bases/{id}

Scope: knowledge:write. Operation id: setKnowledgeBaseRefresh.

auto watches the site and does a weekly full check; scheduled does a full check at the interval; off freezes the base until a refresh is requested.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)	The base's UUID.

Example request

curl "https://api.showpilot.com/v1/knowledge/bases/b0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The base after the change.

KnowledgeBase

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string or null	yes
`shared`	boolean	yes	A shared base can be attached to many agents; a personal one belongs to one.
`status`	string	yes	`active`, `indexing` or `failed`.
`refresh`	object	yes
`lastRefresh`	object or null	yes	The last refresh receipt
`sources`	object	yes
`agentIds`	array of string (uuid)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Refresh a base now

POST /knowledge/bases/{id}/refresh

Scope: knowledge:write. Operation id: refreshKnowledgeBase.

Queues a full pass, exactly as the Refresh button in Settings does. Loaded URL sources go back to pending and the worker re-reads them.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)	The base's UUID.

Example request

curl "https://api.showpilot.com/v1/knowledge/bases/b0000001-0000-4000-8000-000000000000/refresh" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 202.

Queued.

Field	Type	Always	Meaning
`queued`	boolean	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Add a URL source to a base

POST /knowledge/bases/{id}/sources

Scope: knowledge:write. Operation id: addKnowledgeSource.

The source lands pending and is ingested by the worker. Set includeSubpages to crawl the site from that page. File sources are added in the dashboard.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)	The base's UUID.

Example request

curl "https://api.showpilot.com/v1/knowledge/bases/b0000001-0000-4000-8000-000000000000/sources" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 201.

The new source, pending ingest.

KnowledgeSource

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`baseId`	string (uuid)	yes
`kind`	string	yes	`url`, `sitemap`, `text` or `file`.
`name`	string	yes
`url`	string or null (uri)	yes	For url and sitemap kinds.
`status`	string	yes	`pending`, `indexing`, `loaded` or `failed`.
`error`	string or null	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

List sources, newest first

GET /knowledge/sources

Scope: knowledge:read. Operation id: listKnowledgeSources.

Parameters

Name	In	Type	Meaning
`limit`	query	integer	Page size, 1 to 200. Default 50.
`cursor`	query	string	The `nextCursor` from the previous page. Opaque; never build one.
`baseId`	query	string (uuid)

Example request

curl "https://api.showpilot.com/v1/knowledge/sources?limit=50" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

One page of sources.

Field	Type	Always	Meaning
`items`	array of KnowledgeSource	yes
`nextCursor`	NextCursor	yes

KnowledgeSource

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`baseId`	string (uuid)	yes
`kind`	string	yes	`url`, `sitemap`, `text` or `file`.
`name`	string	yes
`url`	string or null (uri)	yes	For url and sitemap kinds.
`status`	string	yes	`pending`, `indexing`, `loaded` or `failed`.
`error`	string or null	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

NextCursor

Pass as cursor for the next page; null on the last page.

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

One source

GET /knowledge/sources/{id}

Scope: knowledge:read. Operation id: getKnowledgeSource.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)	The source's UUID.

Example request

curl "https://api.showpilot.com/v1/knowledge/sources/c0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The source with its ingest status.

KnowledgeSource

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`baseId`	string (uuid)	yes
`kind`	string	yes	`url`, `sitemap`, `text` or `file`.
`name`	string	yes
`url`	string or null (uri)	yes	For url and sitemap kinds.
`status`	string	yes	`pending`, `indexing`, `loaded` or `failed`.
`error`	string or null	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Remove a source and its vectors

DELETE /knowledge/sources/{id}

Scope: knowledge:write. Operation id: deleteKnowledgeSource.

Parameters

Name	In	Type	Meaning
`Idempotency-Key`	header	string	Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header `Idempotent-Replayed` set to true); the same key with a different request is refused. Keys are remembered for 24 hours.
`id`	path	string (uuid)	The source's UUID.

Example request

curl "https://api.showpilot.com/v1/knowledge/sources/c0000001-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 204. Gone. The agents stop answering from it at once.

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Retrieve ranked chunks for a query

POST /knowledge/retrieve

Scope: knowledge:query. Operation id: retrieveKnowledge.

The agent's own retrieval, without generation: ranked chunks with score, source and citation, for composing with your own model. Name an agentId to search exactly what that agent sees, baseIds to search those bases, or neither for every base in the workspace. Draws from the knowledge:query bucket (30 burst, one call every two seconds).

Example request

curl "https://api.showpilot.com/v1/knowledge/retrieve" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Chunks, best first.

Field	Type	Always	Meaning
`results`	array of KnowledgeChunk	yes

KnowledgeChunk

Field	Type	Always	Meaning
`text`	string	yes
`score`	number	yes	Similarity
`sourceId`	string or null (uuid)	yes
`sourceTitle`	string or null	yes
`url`	string or null (uri)	yes
`chunkIndex`	integer or null	yes

Example response

{
  "results": [
    {
      "text": "Pro costs $99 a month, billed yearly.",
      "score": 0.9123,
      "sourceId": "c0000001-0000-4000-8000-000000000000",
      "sourceTitle": "Pricing",
      "url": "https://example.com/pricing",
      "chunkIndex": 3
    }
  ]
}

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Ask a question, get an answer with citations

POST /knowledge/ask

Scope: knowledge:query. Operation id: askKnowledge.

Retrieve, then one grounded answer, with no chat session, no visitor and no analytics. Same targeting as retrieve. When the sources do not cover the question the answer says so rather than guessing. Draws from the knowledge:query bucket.

Example request

curl "https://api.showpilot.com/v1/knowledge/ask" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The answer and what it rests on.

Field	Type	Always	Meaning
`answer`	string	yes
`citations`	array of object	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page