# Import a folder of Markdown into Cozy

> Push Markdown, text, JSON or CSV files into Cozy by browser upload or the ingest API, with curl examples and stable IDs so re-pushing updates instead of duplicating.

Updated 2026-11-08. Canonical: https://cozy.cloud/import/markdown

> 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.

```bash
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`.

```bash
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.

```bash
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.

```bash
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](/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](/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](/import/obsidian), [Notion](/import/notion), [Roam Research](/import/roam-research) and [Logseq](/import/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](/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.
