retrievr — protocol reference Every call below is authenticated the same way: the key written by https://retrievr.io/connect, read from disk. Never print it. authorization: Bearer $(cat ~/.config/retrievr/credentials) base = https://retrievr.io/api/v1 MCP speaks these for you — retrievr_search, retrievr_documents, retrievr_delete_document, retrievr_upload, retrievr_upload_status. What follows is what each one does on your behalf, for a harness that does not. 1. Search: submit, then poll. Retrieval is asynchronous, so it is two calls: submit, then poll until the answer exists. POST https://retrievr.io/api/v1/retrieve content-type: application/json {"query": "all men are created equal", "k": 10} 202 {"job_id":"","status":"pending","interval":2} submitted 401 {"error":"invalid_api_key"} the key is unknown or revoked 402 {"error":"insufficient_credit"} the balance is spent; top up first 400 {"error":"invalid_request"} bad JSON, or an empty query 400 {"error":"invalid_scope"} a scope that cannot be honoured A query costs $0.01 and is charged when it is accepted, so a job that is submitted has already been paid for. At a zero balance the call is refused. Poll the job. Wait at least "interval" seconds between polls. GET https://retrievr.io/api/v1/retrieve-job/ 200 {"status":"pending"} still embedding 200 {"status":"complete", "results":[{"chunk_id":"...","text":"...","title":"...", "author":"...","section_path":"...","doc_id":"...", "chunk_index":0,"char_start":0,"char_end":0, "parent_start":0,"parent_end":0,"licence":"...","score":0.0328}], "retrieval_ms": 1208} 200 {"status":"failed","error":"..."} the embedding job failed 404 {"error":"not_found"} no such job, or not yours 410 {"error":"expired_token"} the job outlived its window A job outlives its window after fifteen minutes. k is clamped to 1-50; the default is 10 here. Every result carries its own citation, so no second lookup is needed to render it. "text" is the parent passage, not the embedded chunk: char_start/char_end address the chunk and parent_start/parent_end the passage, so you can quote either. 2. Scope: where to look. The default — the scope you get by saying nothing — is the person's own documents. {"query": "what does it propose?", "scope": {"type": "private"}} {"query": "the notice period", "scope": {"type": "documents", "ids": ["lib:22a615eb-e7ae-4ef4-9d9a-baecbf720dae"]}} "private" | "documents". "all" was the old name for a search that included the public corpus; it is still accepted and means "private". "public" is refused with 400 invalid_scope, because the corpus is gone and answering it from the caller's own library would look exactly like a corpus search. A scope that cannot be honoured is refused rather than widened, so a typo fails loudly instead of quietly searching more than the caller asked for. An empty library is answered inline, with 200 and no job — nothing was embedded and nothing was charged: 200 {"status":"complete","results":[],"retrieval_ms":0,"library_empty":true} Through the MCP tool the same choice is an argument rather than an object: {"query": "what does it propose?", "scope": "private"}, or {"query": "the notice period", "documents": ["the lease"]}. documents takes a title, a filename or an id, and wins over scope; naming a document that does not exist is an error, never a wider search. The MCP tool asks for 3 passages by default; /retrieve asks for 10. 3. Documents: names to ids. A scope takes ids, and a person has titles, so ids come from this call — which lists the person's own documents when it is given no q, and matches a name against them when it is: GET https://retrievr.io/api/v1/documents GET https://retrievr.io/api/v1/documents?q=project-proposal 200 {"query": null, "documents": [{"id": "lib:22a615eb-...", "title": "project-proposal.pdf", "filename": "project-proposal.pdf", "source": "library", "passages": 12}]} "source" is "library" — there was a "public" and there is not. "passages" is a chunk count; 0 means it is not retrievable yet. An empty list is a 200, not a 404 — "nothing of mine is called that" is a fact about a search. Delete one with its id, never with a name: DELETE https://retrievr.io/api/v1/documents/ 200 {"id":"lib:22a615eb-...","storage_removed":true} gone, with its chunks and vectors 404 {"error":"not_found"} nothing of the caller's has that id Deleting is permanent and has no trash, so read the exact title back to the person and get a yes first. 4. Upload: three calls for one drop. Each file's bytes go straight from the caller's machine to storage and never through a model's context. Ask for somewhere to put them, PUT the bytes, then commit: POST https://retrievr.io/api/v1/library-upload content-type: application/json {"files":[{"filename":"lease.pdf","byte_size":482913}]} 202 {"upload_id":"...", "uploads":[{"filename":"lease.pdf","path":"...","url":"https://...", "content_type":"application/pdf"}]} PUT content-type: x-upsert: false POST https://retrievr.io/api/v1/library-upload/ content-type: application/json {"files":[{"filename":"lease.pdf","path":"..."}]} 202 embedding has started An upload id names the drop, not a file. Ask what became of it with: GET https://retrievr.io/api/v1/library-upload GET https://retrievr.io/api/v1/library-upload?upload_id= 200 {"jobs":[{"upload_id":"...","filename":"lease.pdf","status":"ready"}, {"upload_id":"...","filename":"scan.pdf","status":"failed", "error":"no extractable text"}]} With no upload_id it answers for the account's most recent jobs, newest first. PDF, EPUB, plain text and Markdown, up to 50 MB each, twenty files per call. Uploading is free: the first five documents need no payment, and after that a $5 top-up unlocks the rest and pays for queries. A failed file was not added and holds no place, so it can be sent again. 5. What the account keeps. Query text is kept for fifteen minutes; uploads are kept until they are deleted. https://retrievr.io/privacy is the full account.