Overview Quickstart Collections Ingestion Multimodal Retrieval Citations Limits MCP

Private beta

Toller API

Three calls. Create a collection, ingest documents, retrieve cited results. Toller handles parsing, chunking, embeddings, indexing, and reranking.

Core loop

Create collection

Scope retrieval to one product, team, or feature.

Ingest documents

Push one document at a time, keyed by a stable ID.

Retrieve with citations

Ranked spans returned with source, snippet, and citation string.

01Quickstart

Drop this into a TypeScript or Python project with TOLLER_API_KEY set. The snippet creates a collection, ingests two docs, and retrieves with citations.

End-to-end example

const collection = await toller.collections.create({
  slug: "support-knowledge",
});

await toller.ingest({
  collection: collection.slug,
  externalId: "billing/refunds.md",
  content: refundPolicyMarkdown,
});

await toller.ingest({
  collection: collection.slug,
  externalId: "support/cancel-plan.md",
  content: cancelPlanMarkdown,
});

const { results } = await toller.retrieve({
  collection: collection.slug,
  query: "Can annual customers get a refund after renewal?",
  limit: 5,
});

console.log(results[0]?.citation);

02Collections

A collection is the searchable corpus for one product, team, or feature. Create separate collections when source material should not mix. Toller handles parsing, chunking, embedding, indexing, and reranking inside each one.

const collection = await toller.collections.create({
  slug: "support-knowledge",
});

console.log(collection.slug);

03Ingestion

Ingest one document per call with a stable externalId and content. Toller detects the content type from the bytes.

await toller.ingest({
  collection: "support-knowledge",
  externalId: "billing/refunds.md",
  content: refundPolicyMarkdown,
});

Replace a document

Reuse the same externalId to overwrite an indexed document. The latest ingest wins.

await toller.ingest({
  collection: "support-knowledge",
  externalId: "billing/refunds.md",
  content: updatedRefundPolicyMarkdown,
});

04Multimodal

Ingest text, PDFs, images, and audio into the same collection. Toller embeds each modality into a shared vector space, so one query retrieves across all of them.

Binary content goes in as a base64-encoded string. Toller detects the format from the bytes.

Documents

text/markdown, text/plain, application/pdf

Images

image/png, image/jpeg

Audio

audio/mpeg, audio/wav

Ingest a PDF

import { readFile } from "node:fs/promises";

const pdfBuffer = await readFile("billing/refunds.pdf");

await toller.ingest({
  collection: "support-knowledge",
  externalId: "billing/refunds.pdf",
  content: pdfBuffer.toString("base64"),
});

05Retrieval

Query with natural language. Results are ranked spans returned with source, citation, snippet, and text.

const { results } = await toller.retrieve({
  collection: "support-knowledge",
  query: "What should support tell a customer asking for an annual refund?",
  limit: 8,
});

for (const result of results) {
  console.log(result.externalId);
  console.log(result.citation);
  console.log(result.snippet);
}

Result previewcited

sourcebilling/refunds.md

externalIdbilling/refunds.md

citationbilling/refunds.md#section-1

snippet

Annual plans are refundable within 30 days of renewal.

06Citations

Every result is cited. Use the citation string alongside source, snippet, and text to show where a result came from.

Citation anatomyfields

source

Human-readable origin shown to end users.

externalId

Your stable document ID. Use it to fetch or replace the document.

citation

Deep-link string pointing at the cited region inside the document.

snippet

Short excerpt of the matched span, safe to render inline.

text

Full text of the retrieved span for grounding or quoting.

type TollerResult = {
  id: string;
  externalId: string;
  source: string;
  citation: string;
  snippet: string;
  text: string;
};

07Limits

Private-beta limits below. Talk to us for production rate limits or higher per-document ceilings.

Document size

Up to 100 MB per ingest call. Split larger sources before sending.

Content types

Markdown, plain text, PDF, PNG, JPEG, MP3, WAV. See Multimodal.

Rate limits

No published per-tenant rate limit during beta. If you see 429s, email us and we'll raise it. Production limits are set per agreement.

08MCP

Connect Toller's hosted MCP endpoint to Codex or Claude Code and your agent can call retrieve directly, no SDK. Set TOLLER_API_KEY in the shell that launches your client. The CLI forwards it as a bearer token and writes it into the client's MCP config.

export TOLLER_API_KEY="toller_..."

codex mcp add toller \
  --url https://api.usetoller.com/mcp \
  --bearer-token-env-var TOLLER_API_KEY

codex mcp list

Tools exposed

Toller's MCP server advertises a small surface focused on read access. The agent sees these tools in its tool list once the server is connected.

retrieve

Query a collection. Takes collection and query; returns ranked, cited results.

collections

List collections the API key can read.

get_document

Fetch a document's full text by externalId for follow-up grounding.

Ready to use Toller?

Toller is in private beta. Request access to get an API key.

Request access Back to top