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:

1. validates the bearer key and required scope
2. requires {projectId} to match the project assigned to the key
3. considers only active public libraries
4. 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: Bearer rt_live_YOUR_KEY_HERE" \
  -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 (max 1,000 characters). If omitted, this becomes a deterministic filter-only lookup.
topics	string[]	Filter by topic slugs, such as billing or pricing. Up to 20.
topicsMode	any / all	Whether a chunk must match any or all supplied topics. Default any.
libraryIds	string[]	Restrict results to specific libraries. Up to 50 UUIDs.
sourceIds	string[]	Restrict results to specific source IDs. Up to 50 UUIDs.
kind	raw / distilled	Override retrieval mode for the search.
latitude, longitude, radiusMeters	numbers	Location-aware search. Send latitude and longitude together; radiusMeters (1 to 200,000) is required with them.
distanceWeight	number	0 to 1. Blends proximity into the ranking. Only valid with a location filter.
createdFrom, createdTo	date	Filter by source creation date (YYYY-MM-DD).
snapshot	live / published	live (default) reads the current library links. published reads the frozen snapshot a live assistant serves from, including its audience settings as they were at publish.
sort	relevance / distance / createdAt	Defaults to relevance with a query and createdAt without one. relevance requires a query; distance requires a location filter.
order	asc / desc	Default desc.
limit, offset	integer	Pagination. limit is 1 to 200 (default 50), offset defaults to 0, and offset + limit must not exceed 10,000.

At least one narrowing filter is required: query, topics, libraryIds, sourceIds, a location with radiusMeters, or a createdFrom/createdTo range of 366 days or fewer. A request without one returns 400.

A semantic search (with query) embeds the query on your organization’s AI credits and also counts against the organization-wide rate limit. A filter-only search (no query) spends no credits. When the credits for the period are used up, a semantic search returns 402 with code credits_exhausted.

Each result carries the sourceId and sourceName of the document it comes from, so you can cite it without listing sources first.

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: Bearer rt_live_YOUR_KEY_HERE"

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.

Unlike search, listing sources does not require a narrowing filter. All query parameters are optional:

Parameter	Description
topics	Comma-separated topic labels, for example topics=billing,pricing. Up to 20. Repeating the parameter does not work: only the last value is kept.
topicsMode	any (default) or all.
libraryIds	Comma-separated library UUIDs. Up to 50.
kind	raw or distilled.
status	pending, processing, completed, partial or failed.
createdFrom, createdTo	Creation date range, YYYY-MM-DD.
snapshot	live (default) or published.
sort	createdAt (default), updatedAt or name.
order	desc (default) or asc.
limit, offset	limit is 1 to 200 (default 50); offset is 0 to 10,000 (default 0).

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: Bearer rt_live_YOUR_KEY_HERE"

{
  "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: Bearer rt_live_YOUR_KEY_HERE"

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.

Parameter	Description
snapshot	live (default) or published.
latitude, longitude	Limit to topics near a location. Send both together.
radiusMeters	1 to 200,000. Required with latitude and longitude, and only valid with them.

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: Bearer rt_live_YOUR_KEY_HERE"

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.

limit is 1 to 200 chunks (default 50), maxChars is 1 to 500,000 (default 100,000), and snapshot is live (default) or published. Because this is the bulk-read path, it also counts against the organization-wide rate limit.

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: Bearer rt_live_YOUR_KEY_HERE"

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

Parameter	Description
expiresIn	Link lifetime in seconds, 30 to 3600. Default 300.
snapshot	live (default) or published.

A source without a stored original file, or an organization without CDN storage, returns 409.

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

Errors use the standard v1 shape with a stable code. Authentication, scope, plan and rate-limit refusals are the same on every endpoint; see Errors and Rate limits.

{
  "code": "insufficient_scope",
  "error": "This API key lacks the `kb:content:read` scope.",
  "retryable": false,
  "hint": "Use a key with the `kb:content:read` scope. Manage API keys in the dashboard under Integrations → API keys.",
  "details": { "requiredScope": "kb:content:read", "grantedScopes": ["kb:read"] }
}

Statuses specific to the Knowledge Base API:

Status	Code	Meaning
400	invalid_request	Invalid body or query parameter, or a search without a narrowing filter. error names the field.
402	credits_exhausted	A semantic search when the organization’s AI credits are used up.
404	not_found	Source not found or not visible to the key.
409	conflict	A semantic search with no embedding provider configured, or an original file that is not stored.

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