Knowledge Base API

Use the Knowledge Base API when you want to search your knowledge base without going through an assistant, or when you need to inspect the actual source content behind a library.

This API is intentionally split into two scopes so the “find relevant chunks” path stays separate from the broader “read the full document” path.

Authentication and scopes

Create an API key in the dashboard and add the required scope for the operation you want to call.

kb:read — search the project knowledge base, list sources and topics, and see how each source is used.
kb:content:read — read full extracted text or the original uploaded file for a source you can access.

This is a deliberate separation:

kb:read is the narrow, retrieval-focused permission.
kb:content:read is the broader document-level read permission and is intentionally more sensitive.

For general key setup and scope management, see the API Keys guide.

Project and audience access

Scopes determine which KB operations a key may call, while retrieval audiences determine which libraries those operations may return. For every request, Ragtime:

validates the bearer key and required scope
requires {projectId} to match the project assigned to the key
considers only active public libraries
includes an audience-restricted library only when one of its labels matches an audience assigned to the key

An API key is not treated as an organization member. A key with no assigned audiences can retrieve unrestricted public libraries only.

Do not send audience labels in the query string or request body. Audiences are assigned when the key is created and are derived server-side from the authenticated credential, so a caller cannot grant itself additional access.

Search the knowledge base

Use a POST request to search chunks directly. This is the direct RAG query endpoint: the same vector-search behavior used by Ragtime retrieval, but exposed as a project-level API.

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/kb/search \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the refund policies for enterprise customers?",
    "topics": ["billing", "policies"],
    "libraryIds": ["<library-uuid>"],
    "limit": 10
  }'

Search request fields

Field	Type	Description
`query`	string	Optional semantic query. If omitted, this becomes a deterministic filter-only lookup.
`topics`	string[]	Filter by topic slugs, such as `billing` or `pricing`.
`topicsMode`	`any` / `all`	Whether a chunk must match any or all supplied topics.
`libraryIds`	string[]	Restrict results to specific libraries.
`sourceIds`	string[]	Restrict results to specific source IDs.
`kind`	`raw` / `distilled`	Override retrieval mode for the search.
`latitude`, `longitude`, `radiusMeters`	numbers	Location-aware search.
`createdFrom`, `createdTo`	date	Filter by source creation date.
`limit`, `offset`	integer	Pagination controls; maximum total offset+limit is limited.

The endpoint requires the kb:read scope.

List sources

Use this when you want a document-level inventory instead of chunk-level search results.

curl "https://your-ragtime-instance.com/api/v1/projects/{projectId}/kb/sources?limit=50&offset=0" \
  -H "Authorization: ******"

This returns source metadata only for libraries visible to the key, including topics and other document-level attributes. It does not give you full extracted content. It requires the kb:read scope.

Each source also says how often it answered visitors: uses is the number of times it was cited in the last usageDays days (90, given at the top level of the response), and lastUsedAt is when it last was, or null. Only live traffic counts.

Source usage

See what a single source is used for, as the Knowledge Base’s usage view shows it: the fragments that matched most, and what those conversations were about.

curl "https://your-ragtime-instance.com/api/v1/projects/{projectId}/kb/sources/{sourceId}/usage" \
  -H "Authorization: ******"

{
  "projectId": "proj-uuid-...",
  "sourceId": "source-uuid-...",
  "uses": 37,
  "days": 90,
  "usesWithFragments": 31,
  "fragments": [
    {
      "chunkId": "chunk-uuid-...",
      "chunkIndex": 4,
      "page": 2,
      "uses": 18,
      "excerpt": "Opening hours: Monday to Friday, 9:00 to 17:00…"
    }
  ],
  "topics": [{ "label": "opening hours", "conversations": 12 }],
  "conversationsAnalyzed": 20
}

Field	Description
`uses`	Times the source was cited in the last `days` days.
`usesWithFragments`	Uses that recorded which fragments matched; older uses only record the source.
`fragments`	Up to 10 most-used fragments, with the start of each (`excerpt`). `chunkIndex` and `page` are `null` when unknown. A fragment re-ingested since it was used drops out.
`topics`	Up to 8 topics of the conversations the source answered, from their Insights analysis. `null` when the project does not store transcripts.
`conversationsAnalyzed`	The conversations those topics come from.

Counts and labels only: never a conversation ID. It requires kb:read, and returns 404 for a source the key may not search, the same rule the content endpoint applies.

List topics

Discover the topic labels this key can filter by.

curl "https://your-ragtime-instance.com/api/v1/projects/{projectId}/kb/topics" \
  -H "Authorization: ******"

This returns the union of topics visible to the key, which may include curated library topics and source keywords. It requires the kb:read scope.

Read source content

Use the source content endpoint when you need the extracted text for a specific source. This is the broader read path and requires kb:content:read.

curl "https://your-ragtime-instance.com/api/v1/projects/{projectId}/kb/sources/{sourceId}/content?limit=50&offset=0&maxChars=100000" \
  -H "Authorization: ******"

This returns the document in ordered chunks, with pagination and a truncated flag when more content remains. It is useful when you need the full source text, not just the matching snippets returned by a search.

Read the original uploaded file

If the source came from a file upload, you can fetch a short-lived signed link to the original file.

curl "https://your-ragtime-instance.com/api/v1/projects/{projectId}/kb/sources/{sourceId}/original?expiresIn=300" \
  -H "Authorization: ******"

This requires kb:content:read. The returned URL is time-limited and should be treated as a bearer token for that file.

Endpoint summary

Endpoint	Scope	Purpose
`POST /api/v1/projects/{projectId}/kb/search`	`kb:read`	Direct semantic or filter-based RAG search
`GET /api/v1/projects/{projectId}/kb/sources`	`kb:read`	List source metadata the key can access
`GET /api/v1/projects/{projectId}/kb/topics`	`kb:read`	List visible topic labels
`GET /api/v1/projects/{projectId}/kb/sources/{sourceId}/usage`	`kb:read`	See how one source is used: top fragments and topics
`GET /api/v1/projects/{projectId}/kb/sources/{sourceId}/content`	`kb:content:read`	Read full extracted text for one source
`GET /api/v1/projects/{projectId}/kb/sources/{sourceId}/original`	`kb:content:read`	Fetch the original uploaded file via a signed URL

Error handling

If the key is missing, invalid, expired, or lacks the required scope, the API returns 401 or 403.

Status	Meaning
`401`	Missing, invalid, expired, or malformed API key
`403`	Key is valid but lacks the required scope
`404`	Source not found or not visible to the key

Best practice

Use the most restrictive scope for the job:

use kb:read for search and discovery flows
use kb:content:read only for full-document access
create separate keys for integrations that need different data access levels