Distillation & Lenses

Large knowledge bases can make an assistant verbose — retrieval returns scattered, verbatim fragments. Distillation adds a step in between: an LLM summarizes your sources through a reusable Lens (an angle + a compression level) into compact, coherent content.

There are two flavors:

• Library distillation — distill a whole library into a derived, editable “distilled summary” source. You choose whether the assistant retrieves from the raw sources or the distilled summary.
• Recipient distillation — distill per-recipient materials (e.g. 5 PDFs for one customer) into a short personalized briefing that becomes that recipient’s injected instructions. The uploaded materials are deleted after distillation.

Lenses

A Lens is an org-scoped, reusable preset:

Field	Description
name	Display name (e.g. “Financial wellness”).
lensPrompt	The guiding angle the summary is written through.
level	Compression: light, balanced, or aggressive.

Reusing a Lens makes repeated imports consistent and repeatable.

Scopes

Scope	Allows
distill:read	List/fetch lenses and read library distillation status.
distill:write	Create/manage lenses, run distillation, set a library’s retrieval mode.

See API Keys to create a key with these scopes.

All endpoints are under https://your-ragtime-instance.com/api/v1/projects/{projectId} and require Authorization: Bearer rt_live_....

Manage lenses

List lenses

curl https://your-ragtime-instance.com/api/v1/projects/{projectId}/lenses \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

{
  "lenses": [
    {
      "id": "len_...",
      "name": "Financial wellness",
      "lensPrompt": "Summarize to show how we can help this customer manage money better.",
      "level": "balanced",
      "createdAt": "2026-07-14T10:00:00Z",
      "updatedAt": "2026-07-14T10:00:00Z"
    }
  ]
}

Create a lens

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/lenses \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial wellness",
    "lensPrompt": "Summarize these financials to show how we can help this customer manage their money better.",
    "level": "balanced"
  }'

Returns 201 with the created lens.

Get, update, delete a lens

# Get
curl .../lenses/{lensId} -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

# Update (same body as create)
curl -X PATCH .../lenses/{lensId} -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{ "name": "...", "lensPrompt": "...", "level": "aggressive" }'

# Delete
curl -X DELETE .../lenses/{lensId} -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

Library distillation

Read distillation status

curl https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId} \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

{
  "library": {
    "id": "lib_...",
    "name": "Product docs",
    "retrievalMode": "raw",
    "distillationStatus": "ready",
    "distillationStale": false,
    "distillationLevel": "balanced",
    "distillationLensId": "len_...",
    "lastDistilledAt": "2026-07-14T10:05:00Z"
  }
}

• distillationStatus: idle → processing → ready (or failed).
• distillationStale: true when the raw sources changed since the last distillation — re-distill to refresh.

Run a distillation

Distill the library through a saved lens, or pass an inline lensPrompt + level:

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/distill \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "lensId": "len_..." }'

{ "status": "processing" }

Distillation runs asynchronously (202 Accepted). Poll the status endpoint until distillationStatus is ready. The result is written back as a derived, editable “distilled summary” source in the same library, so a human can correct anything the summary dropped.

Choose raw or distilled

The assistant retrieves from one of them. Switch the library’s retrieval mode (the library must have a ready distillation to select distilled):

curl -X PATCH https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId} \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "retrievalMode": "distilled" }'

Note

Retrieval mode follows the normal preview vs. published rules: the change takes effect for a published assistant only after you re-publish. Preview uses the live value.

Recipient distillation

Give each recipient their own materials plus a Lens, and Ragtime produces a short personalized briefing that becomes that recipient’s injected instructions. The materials are ingested with the normal upload engine and deleted after distillation. The recipient’s link stays closed (shows a “being prepared” message) until its briefing is ready.

The flow is three steps: presign → upload → finalize → distill.

1. Request upload URLs

curl -X POST \
  https://your-ragtime-instance.com/api/v1/projects/{projectId}/recipients/{recipientId}/materials \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "lensId": "len_...",
    "files": [
      { "name": "statement.pdf", "type": "application/pdf", "size": 482912, "contentHash": "<sha256-hex>" }
    ]
  }'

contentHash is the browser/client-computed SHA-256 hex of the file (used for per-recipient dedup). Returns 201 with presigned uploads:

{
  "uploads": [
    {
      "name": "statement.pdf",
      "contentHash": "<sha256-hex>",
      "sourceId": "src_...",
      "uploadUrl": "https://cdn.example.com/...",
      "key": "...",
      "contentType": "application/pdf"
    }
  ]
}

This also sets the recipient’s distillationStatus to pending.

2. Upload the bytes

PUT each file’s bytes directly to its uploadUrl (the app never sees the file):

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf

3. Finalize (enqueue ingestion)

curl -X POST \
  https://your-ragtime-instance.com/api/v1/projects/{projectId}/recipients/{recipientId}/materials/finalize \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "sourceIds": ["src_..."] }'

{ "finalized": 1, "failed": [] }

4. Distill

Once the materials have finished ingesting, trigger the distillation:

curl -X POST \
  https://your-ragtime-instance.com/api/v1/projects/{projectId}/recipients/{recipientId}/distill \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

{ "status": "processing" }

Poll the recipient (GET .../recipients/{recipientId}) until its distillationStatus is ready. At that point the personalized briefing has been written to the recipient’s injectionInstructions, the materials have been deleted, and the link is open.

If the materials are still processing (or one failed to ingest), the distill call returns 409.

Status codes

Status	Meaning
200	Success (get, update, delete, finalize).
201	Lens created, or material upload URLs issued.
202	Distillation accepted and running asynchronously.
207	Some materials finalized, some failed (see failed).
400	Invalid request (bad field, no sources, missing files).
401	Missing or invalid API key.
403	Key doesn’t match the project or lacks the required scope.
404	Lens, library, or recipient not found in this project.
409	Distillation already running, materials not ready, or no ready distillation to select.

Dashboard

Library distillation is also available without the API in Dashboard → Knowledge Base: pick or write a Lens, choose a compression level, distill, review/edit the distilled summary, and toggle whether the assistant uses raw or distilled content. Recipient distillation status is shown per recipient in Deployment → Campaigns.