Quickstart

Send text, then let your LLM or agent pull what it needs from all of it. One key, a few calls.

1. Get access and a key

Sign in with Google at console.lochless.io. Your workspace opens right away. Then create an API key in the console. Every workspace starts with $5 of free credit. No card needed.

Every request uses the same key as a bearer token. All requests and responses are JSON.

export LOCHLESS_KEY="paste-your-key-here"

Keys live only in the console. You can create, rotate and revoke them there. We never send keys by email.

2. Send text

POST /v1/ingest takes one document, or {"documents": [...]} with 1 to 100. Indexing costs $0.005 per page of 3,000 characters, at least one page per document, charged when the document is indexed. Sending unchanged text again is free; changed text is charged again in full.

curl https://api.lochless.io/v1/ingest \
  -H "Authorization: Bearer $LOCHLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "ticket-4411",
        "text": "Customer was charged twice for the October invoice and wants a refund.",
        "timestamp": "2026-10-01T09:30:00Z",
        "metadata": {"channel": "email", "plan": "pro"}
      }
    ]
  }'
// 202 Accepted
{"documents": [{"id": "ticket-4411", "status": "queued"}]}
FieldRequiredWhat it is
idYesYour id for the document, up to 512 characters. Sending the same id again replaces it. Each id once per request.
textYesThe document's text, up to 1 million characters.
timestampYesWhen the document happened, in ISO 8601 with a timezone, like 2026-10-01T09:30:00Z.
metadataNoAny JSON value, stored with the document.

The call returns right away. Documents are queued and become searchable in the background. Check progress with GET /v1/docs/{id}. A request body can be up to 25 MB.

3. Check or delete a document

# status: queued, indexing, ready or failed
curl https://api.lochless.io/v1/docs/ticket-4411 \
  -H "Authorization: Bearer $LOCHLESS_KEY"

# remove it from your index
curl -X DELETE https://api.lochless.io/v1/docs/ticket-4411 \
  -H "Authorization: Bearer $LOCHLESS_KEY"
// GET
{"id": "ticket-4411", "status": "ready", "timestamp": "2026-10-01T09:30:00.000Z",
 "queued_at": "2026-10-08T12:00:00.000Z", "updated_at": "2026-10-08T12:04:10.000Z"}

// DELETE
{"id": "ticket-4411", "status": "deleted"}

A document shows up in queries once its status is ready. A deleted document stops showing up in results. Percent-encode ids that contain /.

4. Get context

/v1/context searches all dates unless you pass from/to.

POST /v1/context reads the documents in scope for a natural-language query, up to your read limit, and returns the ones it judges relevant. A result is a quote from one of your documents, with its source. Drop them into your prompt or return them from a tool call.

curl https://api.lochless.io/v1/context \
  -H "Authorization: Bearer $LOCHLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "customers asking for a refund", "limit": 50}'
// response (abridged)
{
  "results": [
    {
      "document_id": "ticket-4411",
      "title": "ticket-4411",
      "url": "",
      "date": "2026-10-01T09:30:00Z",
      "content": "Customer was charged twice for the October invoice and wants a refund.",
      "metadata": {"channel": "email", "plan": "pro"}
    }
  ],
  "total_results": 212,
  "coverage": {"documents_read": 1840, "documents_total": 1840, "complete": true},
  "next_cursor": "lx1.eyJjIjoi...",
  "tokens_scanned": 182340,
  "request_id": "..."
}

Pages

Filters

Filters choose which documents a query reads. Documents outside the filter are never read, scanned or billed.

{"query": "renewal terms",
 "from": "2026-01-01T00:00:00Z", "to": "2026-04-01T00:00:00Z",
 "metadata": {"client": "acme", "type": ["contract", "nda"]}}

Dry run

Add "dry_run": true to see what a query would cost before you run it. It is free, reads none of your text, and counts against the same rate limit as a query.

{"dry_run": true, "documents_matched": 1840, "documents_ready": 1840, "tokens_to_scan": 182340,
 "price_usd": 0.018234, "read_limit_usd": 1, "complete": true, "tokens_scanned": 0, "request_id": "..."}

tokens_to_scan is exactly what the real call would be billed. It counts documents that are ready. A document still indexing is not read yet, so documents_ready can be lower than documents_matched right after ingest.

A dry run takes the same query and filters as the real call. It works on /v1/context, /v1/ask and the MCP tools search_documents and ask_documents.

Read limit

Each query reads up to your read limit (default $1). If it would cost more, we read the best-matching documents first and tell you how many we skipped. No call costs more than its limit. For /ask, the $0.05 answer fee counts inside it.

{"query": "every contract that auto-renews", "read_limit_usd": 5}

Each response shows how much it covered:

"coverage": {"documents_read": 120400, "documents_total": 412000, "complete": false},
"continue_cursor": "lx2.eyJyIjoi..."

Two cursors

5. Ask

POST /v1/ask searches like /v1/context, then writes a short answer that cites its evidence inline as [1], [2]. Answers usually take 7 to 13 seconds.

curl https://api.lochless.io/v1/ask \
  -H "Authorization: Bearer $LOCHLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Why are refunds up this month?"}'
// response (abridged)
{
  "answer": "Most refund requests this month are double charges on the October invoice [1].",
  "evidence": [
    {"n": 1, "document_id": "ticket-4411", "date": "2026-10-01T09:30:00Z",
     "metadata": {"channel": "email", "plan": "pro"},
     "text": "Customer was charged twice for the October invoice and wants a refund.",
     "score": 0.97}
  ],
  "tokens_scanned": 240115,
  "coverage": {"documents_read": 2210, "documents_total": 2210, "complete": true},
  "request_id": "..."
}

/v1/ask takes the same filters and dry_run. Like /context, it searches all dates unless you pass from/to, and it uses the same read_limit_usd and coverage.

6. Use it from an agent (MCP)

The MCP server at https://api.lochless.io/mcp gives agents four read-only tools: search_documents, browse_documents (list documents by date), read_document (open one whole document) and ask_documents. Sign in with OAuth, or send your API key. Searches and answers are billed and capped the same way. Browsing and reading a document are free. search_documents takes the same limit, cursor, filters, dry_run, read_limit_usd and continue_cursor, and returns the same fields as /v1/context. ask_documents takes the same filters, dry_run and read_limit_usd.

Add to CursorAdd to VS CodeLochless on Smithery

# Claude Code: add it, then run /mcp to sign in
claude mcp add --transport http lochless https://api.lochless.io/mcp

# or with an API key
claude mcp add --transport http lochless https://api.lochless.io/mcp \
  --header "Authorization: Bearer $LOCHLESS_KEY"

Any client that supports remote MCP over HTTP works. Point it at the URL and sign in when it asks, or send the key in the Authorization header.

Try it without an account. https://api.lochless.io/demo/mcp runs the same tools on a public sample: 20 US founding documents (the Constitution, Bill of Rights, later amendments and the Declaration of Independence). No sign-in, no key, no cost. Ask it "Who gained the right to vote through amendments?"

# Claude Code: the free demo, no sign-in
claude mcp add --transport http lochless-demo https://api.lochless.io/demo/mcp

Billing

Your data

Limits

WhatLimit
/context and /ask60 calls a minute per key, 3 at a time
/ingest1,000 calls a minute per key, 100 documents per call
Ingest queue1 million documents waiting to be indexed, per workspace

Need more? Use "Request a limit increase" in the console settings. The same form raises the monthly spend cap.

Errors

Errors use standard HTTP status codes and one JSON shape:

{"error": {"code": "rate_limited", "message": "Too many requests. Retry after 12 seconds.", "request_id": "..."}}
StatusCodeWhat to do
400invalid_requestFix the request. The message says what is wrong.
401unauthorizedThe key is missing, revoked or wrong. Check it in the console.
402add_creditYour balance is zero. New documents are refused and queued ones wait. Top up in the console to continue.
402spend_cap_reachedYou hit this month's spend cap. Queries resume next month, or raise the cap with "Request a limit increase" in the console.
404not_foundNo document with that id.
409conflictA document changed during the read, a continue_cursor is stale, or ingest is paused for this workspace. The message says which. Run the query again, or email support@lochless.io if ingest is paused.
413payload_too_largeRequest body over 25 MB. Send fewer documents per call.
429rate_limitedToo many calls. Wait for the seconds in the Retry-After header, then retry.
429queue_fullYour ingest queue is full. Wait for Retry-After and send again as it drains.
5xxserver_errorSomething failed on our side. Retry with backoff.

Support

Email support@lochless.io. Include the request_id from the error if you have one. Support is best effort, as section 16 of the Terms describes.