Import
Import a folder of Markdown into Cozy
To import a folder of Markdown into Cozy, either upload files in the browser (up to 25 files per selection, 1 MB each) or POST them to the ingest API with a bearer token. Give each document a stable id, so pushing the same file again updates the existing source instead of creating a duplicate. New documents land in the built-in Inbox.
What Cozy accepts
Cozy takes Markdown, plain text, JSON and CSV files. Imported material is stored as sources, which means evidence with a stable ID, a URL where one exists, and timestamps. Sources live under sources/, and agents treat them as untrusted data to read and cite, not as instructions.
| Path | Limit |
|---|---|
| Browser upload | 1 MB per file, 25 files per selection |
| Ingest API, JSON body | 25 documents per request, 1.5 MB each |
| Imported sources | Up to 1,500,000 bytes each |
| Curated wiki pages | Up to 90,000 bytes each |
The gap between the two file limits is deliberate. A long export can be a source, but a page you want your agent to read and maintain should stay small. If a file is larger than 90,000 bytes, import it as a source and let your agent write a shorter curated page that cites it.
Option 1: upload in the browser
Open your wiki in the web app, choose the upload action, and select your files. You can pick up to 25 at a time and each file can be up to 1 MB. Repeat the selection for bigger folders. This is the quickest route for a one-off batch of notes, exported documents or a CSV you want your agent to reason about.
Browser upload suits small sets. If you have hundreds of files, or you want to re-run the import after editing the originals, use the API.
Option 2: the ingest API
The ingest endpoint takes a workspace ID and a token. Create a bearer credential in Agents with the source-write scope. Cozy shows the token once, so copy it somewhere safe. Credentials expire within 90 days and you can revoke them at any time.
export COZY_WORKSPACE="WORKSPACE_UUID"
export COZY_TOKEN="your-bearer-token"
Push several documents as JSON
Send up to 25 documents per request. Each document needs an id and its content.
curl -X POST "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest" \
-H "Authorization: Bearer $COZY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"documents":[
{"id":"notes/2026-01-standup.md","content":"# Standup\n\nShipped the importer."},
{"id":"notes/2026-02-standup.md","content":"# Standup\n\nFixed retries."}
]}'
Push one file as raw Markdown
For a single file, send the raw body and put the id in the query string.
curl -X POST "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest?id=notes/2026-01-standup.md" \
-H "Authorization: Bearer $COZY_TOKEN" \
-H "Content-Type: text/markdown" \
--data-binary @notes/2026-01-standup.md
Loop over a folder
A shell loop is enough to push a whole directory. Using the relative path as the id keeps IDs predictable.
find notes -name '*.md' | while read -r f; do
curl -s -X POST "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest?id=$f" \
-H "Authorization: Bearer $COZY_TOKEN" \
-H "Content-Type: text/markdown" \
--data-binary @"$f"
done
If a path contains spaces or characters that need escaping in a URL, use the JSON form instead, where the id is just a string field.
Stable IDs
The id is how Cozy recognizes a document. Push the same id again and Cozy updates the same source rather than adding a second copy. That makes your import safe to re-run: edit your local files, run the loop, and the sources follow.
Choose IDs you can reproduce. A relative file path works well for folders. For exports from another tool, use the tool's own record ID. Avoid IDs built from timestamps or random values, because every run would create new sources.
One rule matters if you clean up later. If you delete a source in Cozy, it is never re-imported, even if your script pushes that id again. That protects your deletions from a script that keeps running, so remove files at the origin too.
After the import
Documents go to the built-in Inbox by default. From there your own agent can read them through the hosted MCP server, write curated pages in wiki/ that link back to the sources, and keep citations intact. Links into sources/ become cites relations in the graph, and Health flags sources that nothing cites yet. See source citations for how that works.
Cozy runs no model itself, so organizing the Inbox is work your agent does. Searching is lexical, with no embeddings.
Coming from a specific tool
If your Markdown comes from a notes app, the dedicated guides cover the quirks of each export: Obsidian, Notion, Roam Research and Logseq. For live sync instead of one-time files, Cozy also has connectors, including Notion and Google Drive.
Frequently asked questions
Which file types can I import into Cozy?
Markdown, plain text, JSON and CSV. Browser upload accepts up to 1 MB per file and 25 files per selection, and the ingest API accepts up to 1.5 MB per document.
How do I avoid duplicate sources when I re-run an import?
Give every document a stable id, such as its relative file path. Pushing the same id again updates the same source instead of creating a new one.
What happens if I delete an imported source and push it again?
Cozy never re-imports a deleted source, so your script cannot bring it back. Remove the file from your own folder as well to keep both sides in step.
What token scope does the ingest API need?
Create a bearer credential in Agents with the source-write scope. It is shown once, expires within 90 days and can be revoked. See MCP server for how credentials work.
Where do imported documents appear?
In the built-in Inbox by default, stored as sources under sources/. Your agent can then read them and write curated pages that cite them.
Give your agents a memory worth keeping
Cozy gives every account a private wiki that Claude, Codex, ChatGPT and other MCP clients can read and maintain.
Start your wiki