Documents and ingestion

Supported files

Format	Notes
Markdown (.md, .markdown)	Best. Headings help the structurer find section boundaries.
Text (.txt)	Fine.
PDF (.pdf)	Text layer only — scanned PDFs are refused (run OCR first). Up to 200 pages; password-protected files are refused.
Word (.docx)	Headings, lists and tables are converted to Markdown.

Uploads up to 20 MB are accepted; what counts against your plan is the number of characters of text in the document (50,000 on Free).

Front matter

A Markdown or text file may start with a front-matter block, like a SKILL.md does:

---
name: refund-emails
description: Use when writing a refund email to a customer.
---

• name (or title) becomes the document’s title, unless you gave one.
• description becomes its line in the table of contents, word for word, instead of one the model writes. Write it to say when to use the document.
• The block itself isn’t treated as content. Other keys are ignored.

Ingestion

Every upload, content replacement and re-ingest runs the same pipeline:

1. Parsing — the file becomes text.
2. Structuring — a language model splits the text into coherent sections (never separating a rule from its exceptions) and writes a navigational title and a short summary for each, plus a one-line summary of the whole document.
3. Embedding — sections and passages are embedded for search.

The document’s status moves pending → parsing → structuring → embedding → ready. If something goes wrong it ends failed with the reason; a failure on our side doesn’t use up your daily ingestions, and Retry runs it again.

Editing

• Rename a document at any time; it doesn’t re-ingest.
• Replace the content (edit the text in the browser, upload a new file, or PUT /documents/{id}/content) to re-ingest. Section ids change when content changes.
• Uploading content identical to an existing document in the same namespace returns that document instead of creating a duplicate.

Versions

On paid plans every upload, edit and restore keeps the previous source file: the document’s History shows the last versions your plan keeps (e.g. 5), who made each one and when. For each you can see the changes against the current content, download it, or restore it.

Restoring makes that version the current content again and re-ingests it — it uses one ingestion, section ids change, and it is itself recorded as a new version, so a restore can be undone. Older versions are deleted as new ones arrive; deleting the document deletes all of them.

From scripts: GET /documents/{id}/versions, GET /documents/{id}/versions/{n}/content and POST /documents/{id}/versions/{n}/restore — see the API reference.

Pinned documents

Agents search for their task (“refunding an overdraft fee”), not for what the task depends on: the procedure that finds the customer’s account id, the identity check, the codes a transfer to a human needs. Those are what retrieval misses. Pin them, and every agent gets them without asking: in the MCP server’s instructions, which most clients put into the system prompt, or at the top of its first get_toc or search_instructions answer (see MCP tools).

Pin what every conversation needs:

• identifier lookups (how to find an account, order or customer id),
• verification and escalation procedures, reason codes,
• the one rule that applies everywhere.

Don’t pin for coverage. Pinned documents go into every conversation, whether it needs them or not, and a long prompt is what makes agents miss rules. Everything else is what search is for.

Pinned documents are capped per namespace, at 2,000 estimated tokens unless an admin sets a different cap. The cap counts the block as agents receive it, and a pin that would pass it is refused. Pin and unpin on the namespace page, with imcp namespaces pins, or through the API (GET/PUT /pins, POST/DELETE /documents/{id}/pin, PUT /pins/cap; see the API reference).

A pin keeps its place when you replace the document’s content or re-ingest it. While it re-ingests it is left out, and it is back when it is ready. Deleting a document unpins it. A document re-uploaded after a delete is a new document, so pin it again.

What the model sees

To structure and search your documents, jitprompt sends their text to Anthropic (structuring) and Voyage AI (embeddings). Neither trains on it. See Subprocessors.