API Keys

Authenticate external services (N8N, custom scripts, etc.) to call Ragtime API endpoints using project-scoped API keys.

Setup

Open the project, then go to Dashboard → Integrations → API keys.
Click Create API key and give it a descriptive name.
Select the scopes the key should have access to.
If the key will use the Knowledge Base API, select the retrieval audiences it may access.
Copy the key — it’s shown only once. Store it securely.

Key Format

Keys are prefixed with rt_live_ for easy identification in logs and leak detection:

rt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Only a SHA-256 hash of the key is stored server-side. The raw key cannot be recovered.

Authentication

Include the key in the Authorization header as a Bearer token:

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest \
  -H "Authorization: Bearer rt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/doc.pdf"}'

The scope each endpoint requires is listed in the OpenAPI contract at GET /api/v1/openapi.json, which needs no key.

Scopes

Each key is limited to specific operations via scopes:

Scope	Allows
`ingest`	Upload and manage knowledge base content via the ingest API.
`analytics:read`	Read analytics and usage data from the analytics API.
`insights:read`	Read conversation insights (sentiment, topics, outcomes) from the insights API.
`insights:write`	Create, update, and delete saved insight queries.
`findings:write`	Resolve, defer, decline, or reopen findings, and run the findings check.
`insights:admin`	Turn data collection on or off, purge conversations, and generate or remove test data.
`recipients:read`	List and fetch personalized recipient links and their state.
`recipients:write`	Create, update, and delete personalized recipient links via the recipients API.
`distill:read`	List and fetch distillation lenses and library distillation status.
`distill:write`	Create/manage lenses, run library or recipient distillation, set retrieval mode.
`audience:read`	Read the audience labels restricting a library.
`audience:write`	Replace a library’s audience labels.
`kb:read`	Search the project knowledge base, list its sources and topics, and see how often each source is used.
`kb:content:read`	Read full extracted text or original file content for a source you can access.
`assistant:read`	Read the assistant’s instructions and conversation stages via the Assistant Config API.
`assistant:write`	Update the assistant’s instructions and conversation stages.
`assistant:ask`	Ask the published assistant questions via the Ask API. Spends AI credits on every call.
`assistant:draft`	Ask the unpublished draft with `draft: true`, to test changes before publishing. For test keys only. Spends AI credits.
`actions:read`	Read actions and their steps.
`actions:write`	Create, change and delete actions on the draft. They reach visitors at the next publish.
`workflows:execute`	Start published workflows and read the status of those runs.
`workflows:read`	Read workflow drafts, and what keeps each from being published.
`workflows:write`	Create, change and remove workflow drafts. Publishing and enabling stay in the dashboard.
`usage:read`	Read AI credit usage for the current period: used, included and left. See the API overview.

insights:admin deletes data: a purge of all time on all channels takes the findings and their history with it. Generating test data spends your organization’s AI credits. Keep it off keys that only read insights.

audience:write is the most sensitive scope: it controls who can retrieve a library, and clearing the labels exposes that library to every visitor of the project. It is kept separate from ingest on purpose, so an ingestion connector cannot widen access even if its credential leaks. Grant it only to the job that genuinely owns group membership.

Billing a key to a channel

When creating a key you can choose a channel to bill its AI usage to. The key’s calls that spend credits, such as asking the assistant, then count as that channel’s: they draw on the channel’s package and fall back to the general pool the same way the channel’s own conversations do.

Only a Dynamic Avatar or Kiosk channel of the key’s project can be chosen. Learning and Campaign channels admit people by seat or personal link, which a key would bypass.
A key bound to a kiosk channel is refused while the kiosk is switched off or outside its package term.
A key bound to a Dynamic Avatar channel that is switched off draws on the general pool until the channel is on again.
A key without a channel draws on the organization’s general pool.
Deleting the channel moves the key back to the general pool. The key keeps working.

GET /api/v1/context and GET /api/v1/usage report which pool a key draws on. See AI credits.

Monthly credit cap

A key can have its own monthly credit cap: the most AI credits it may spend in a calendar month (UTC). It sits on top of the pool’s limits, so one runaway integration or AI agent cannot use up credits the rest of the organization relies on.

Setting it. Set it when you create the key, or later from the key’s row in Dashboard → Integrations → API keys, which also shows what the key spent this month. Leave it empty for no cap. Connected apps have the same setting.
What counts. The credits of every AI call the key’s requests make, such as asking the assistant, a semantic search or an insight query, plus the processing of documents the key adds. Another key’s spend never counts.
When it is reached. Calls that spend credits return 402 credit_cap_reached until the month turns. The error says when it resets, and calls that spend nothing, such as listing sources or reading usage, keep working.
Seeing it from the API. GET /api/v1/usage reports it as keyCap: the cap, what was spent, what is left and whether it is reached. GET /api/v1/context reports whether it is reached to any key.

Connected apps

AI apps such as Claude.ai and ChatGPT can connect to the MCP server by having a member sign in instead of using a key. Each connection works like a key: one project, the scopes the member chose and optionally a channel. Connections are listed under Dashboard → Integrations → Connected apps, where you can give them a monthly credit cap or disconnect them. The same members who may create API keys may connect apps.

Library-Scoped Keys

By default a key can act on every library linked to its project. When creating a key you can optionally restrict it to a single library — useful when a separate upstream system pushes content for one audience only, and you don’t want a leaked credential to be able to write into a sibling library.

Set Restrict to library in the create dialog. The library must already be linked to the project.

A restricted key is accepted only on endpoints that address that exact library in their path, plus a few that only describe the key or its own uploads:

Endpoint	Restricted key
`POST /api/v1/projects/{p}/libraries/{libraryId}/ingest`	Only if `{libraryId}` matches
`GET /api/v1/projects/{p}/libraries/{libraryId}`	Only if `{libraryId}` matches
`PATCH /api/v1/projects/{p}/libraries/{libraryId}`	Only if `{libraryId}` matches
`POST /api/v1/projects/{p}/libraries/{libraryId}/distill`	Only if `{libraryId}` matches
`GET /api/v1/projects/{p}/libraries/{libraryId}/audience`	Only if `{libraryId}` matches
`PUT /api/v1/projects/{p}/libraries/{libraryId}/audience`	Only if `{libraryId}` matches
`GET /api/v1/projects/{p}/sources/{sourceId}`	Only for sources in its own library (`404` otherwise)
`GET /api/v1/context` and `GET /api/v1/usage`	Accepted (see the API overview)
Every other endpoint (analytics, insights, recipients, …)	Rejected

This is deliberately fail-closed: an endpoint that does not name a target library cannot satisfy the restriction, so it returns 403 with code library_restricted rather than falling back to project-wide access. If you need a key for analytics or recipients, create an unrestricted key with just those scopes.

Deleting the library deletes the key. A restricted key has no meaning without its library, and silently widening it to project-wide access would be a privilege escalation — so the key is removed along with the library. Reissue a new key if you recreate the library.

Library scoping is orthogonal to audience labels: scoping controls what a key may write, audience labels control what a visitor may read.

Knowledge base access

The direct knowledge-base API is intentionally split into two scopes.

kb:read — search the project knowledge base and list the sources/topics the caller may access. This is the “find relevant chunks” scope.
kb:content:read — read the full extracted text or original file content for a single source. This is the broader, document-level read scope and is intentionally separate from kb:read because it exposes more of the underlying corpus.

Typical endpoints behind these scopes:

Endpoint	Requires
`POST /api/v1/projects/{projectId}/kb/search`	`kb:read`
`GET /api/v1/projects/{projectId}/kb/sources`	`kb:read`
`GET /api/v1/projects/{projectId}/kb/topics`	`kb:read`
`GET /api/v1/projects/{projectId}/kb/sources/{sourceId}/usage`	`kb:read`
`GET /api/v1/projects/{projectId}/kb/sources/{sourceId}/content`	`kb:content:read`
`GET /api/v1/projects/{projectId}/kb/sources/{sourceId}/original`	`kb:content:read`

This keeps the “smallest useful search” and the “dump the whole document” path separate, matching the way the rest of the API distinguishes read vs write access.

Retrieval audiences

Knowledge Base API keys are external callers, not organization members. When an organization admin or project owner creates a key, they can assign audience labels already used by libraries linked to that project. The key can then retrieve:

public libraries without audience restrictions
public libraries whose audience labels overlap the labels assigned to the key

With no retrieval audiences selected, the key can retrieve unrestricted public libraries only. It does not gain access to every project library.

Audiences are stored on the API key and verified by Ragtime when the key is presented. API clients cannot claim extra audiences in a query parameter or request body. To change a key’s retrieval audiences, replace the key with a newly issued credential.

Plan requirement

API access is part of your organization’s plan. If the plan does not include it, existing keys stay listed so you can revoke them, but they do not authenticate and no new keys can be created. Requests with such a key return 403 with code plan_required.

Rate limits

Every v1 endpoint is rate limited per key: 30 requests per minute by default. The limit can be raised per key on request through Ragtime support. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. See Rate limits.

Error Responses

Refusals use the standard v1 error shape, with a stable code you can branch on. A key without the scope an endpoint requires gets a 403 that names the missing scope:

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

Status	Code	Meaning
`401`	`unauthorized`	Missing or unknown API key.
`401`	`key_expired`	The key has passed its expiry date. Create a new one.
`403`	`insufficient_scope`	The key lacks the scope this endpoint requires (`details.requiredScope`).
`403`	`project_mismatch`	The key belongs to a different project than `{projectId}`.
`403`	`library_restricted`	A library-restricted key called an endpoint outside its library.
`403`	`plan_required`	The organization’s plan does not include API access.
`429`	`rate_limited`	Too many requests. Wait `retryAfter` seconds (also in `Retry-After`).

See Errors for every code.

Using with N8N

In N8N, use an HTTP Request node.
Set Authentication to Generic Credential Type → Bearer Auth.
Bearer Token: rt_live_your_key_here

For a detailed walkthrough — including the alternative Header Auth option — see the N8N Setup Guide.

Security Best Practices

Use the minimum scopes needed for each integration.
Assign only the retrieval audiences the integration needs.
Restrict a key to a single library when the integration only ever writes to one.
Create separate keys per integration so you can revoke one without affecting others.
Store keys in environment variables or a secrets manager — never commit them to version control.
Rotate keys periodically; delete unused keys promptly.