MD Vessel API: Programmatic Access to Your Markdown Notes

The MD Vessel API is a small HTTP interface that lets you read, create, and update markdown notes without opening the app. Every file in your dump — notes, docs, blog posts, briefs — is reachable through simple GET, POST, PATCH, and DELETE requests, which makes it the easiest way to build tools on top of your own knowledge base.

Why does that matter? Because your notes shouldn't live in a walled garden. With an API, your markdown dump becomes a first-class data source: script it, sync it, feed it to an AI agent, or wire it into a publishing pipeline — all with a few lines of code.

What Is the MD Vessel API?

The MD Vessel API exposes the same folders and files you see in the app as JSON endpoints. Each request is authenticated with a simple bearer token, and every response is plain JSON — no SDK required, works from any language that can send an HTTP request.

The API is deliberately small. There are no complex query languages or webhooks to learn — just five groups of endpoints:

Authentication

Every request must include your API key as a bearer token:

curl -H "Authorization: Bearer <your_api_key>" \
  https://md-vessel.vercel.app/api/v1/tree

• The key is issued per project and should be kept secret — treat it like a password.
• Write requests also send Content-Type: application/json.
• A missing or invalid key returns 401. A valid key with a bad body returns 400. Unknown IDs return 404.

Reading Your Dump

The two endpoints you'll use most are tree and files.

Get the full tree

curl -H "Authorization: Bearer <key>" https://md-vessel.vercel.app/api/v1/tree

Returns the complete folder/file hierarchy:

{
  "folders": [{ "id": "cmw…", "name": "seo", "parentId": null }],
  "files": [{ "id": "cmw…", "name": "note.md", "folderId": "cmw…" }]
}

Read a file's content

List responses don't include content. Open a file by ID to get its markdown:

curl -H "Authorization: Bearer <key>" \
  https://md-vessel.vercel.app/api/v1/files/{id}

{
  "file": {
    "id": "cmw…",
    "name": "note.md",
    "content": "# My note\n\nMarkdown goes here.",
    "folderId": "cmw…",
    "createdAt": "2026-11-03T19:31:33.791Z",
    "updatedAt": "2026-11-03T19:31:33.791Z"
  }
}

List files in a folder

curl -H "Authorization: Bearer <key>" \
  "https://md-vessel.vercel.app/api/v1/files?folderId={id}"

Omit folderId to list everything; use folderId= or folderId=null for root-level files only.

Writing Content

Create a file

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "note.md", "content": "# Hello", "folderId": null}' \
  https://md-vessel.vercel.app/api/v1/files

Returns 201 with the created file. name is required; content and folderId are optional.

Update a file

curl -X PATCH -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Updated title\n\nNew body."}' \
  https://md-vessel.vercel.app/api/v1/files/{id}

PATCH replaces the full document content — send the entire markdown, not a diff. You can also update name and move the file between folders by passing folderId in the same call.

Delete a file

curl -X DELETE -H "Authorization: Bearer <key>" \
  https://md-vessel.vercel.app/api/v1/files/{id}

Returns { "ok": true }. Folders cannot be deleted or renamed through the API — keep that in mind before removing a folder in the app UI, because deleting a folder removes every file inside it.

Organizing with Folders

# List folders
curl -H "Authorization: Bearer <key>" https://md-vessel.vercel.app/api/v1/folders

# Create a folder
curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "docs", "parentId": null}' \
  https://md-vessel.vercel.app/api/v1/folders

Set parentId to nest a folder; parentId: null puts it at the root. Use the IDs returned by the API — never invent them.

Quickstart: Sync a Note from Your Machine

Here's a complete flow — create a folder, create a note inside it, read it back, and update it:

KEY="<your_api_key>"
BASE="https://md-vessel.vercel.app/api/v1"

# 1. Create a folder
FOLDER=$(curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "projects"}' "$BASE/folders" | jq -r '.folder.id')

# 2. Create a note inside it
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"name\": \"ideas.md\", \"content\": \"# Ideas\\n\\n- Write more\", \"folderId\": \"$FOLDER\"}" \
  "$BASE/files"

# 3. Find it and read the content
FILE_ID=$(curl -s -H "Authorization: Bearer $KEY" "$BASE/files?folderId=$FOLDER" | jq -r '.files[0].id')
curl -s -H "Authorization: Bearer $KEY" "$BASE/files/$FILE_ID" | jq '.file.content'

That's the whole integration surface — a few hundred bytes of JSON over HTTP.

What Can You Build With It?

• AI agents — the API was designed for agents: read the instructions endpoint first, then explore tree, open files, and save changes exactly like the MD Vessel agent does.
• Publishing pipelines — push markdown from a repo or CI job straight into the dump.
• Note migrations — script the import of hundreds of .md files in a loop, one POST each.
• Backups — dump the whole tree to disk periodically with a cron job.

Because content is plain markdown under the hood, everything you write stays portable: if you ever move platforms, your notes come with you.

Frequently Asked Questions

Do I need an SDK? No. The API is plain HTTPS + JSON, so it works with curl, Python's requests, JavaScript fetch, or any HTTP client.

How do I get an API key? Keys are issued per project from the MD Vessel app. If you're an AI agent, the key is handed to you as part of your setup — never store it in a file, .env, or committed code.

Why don't folder listings include content? To keep list responses fast and lightweight. Open a file by ID when you need its full markdown.

Can the API rename or delete folders? No — folders support create and list only. File management is the API's job; structural changes happen in the app.

What's the difference between a 400 and a 404? 400 means your JSON body was malformed or a field was invalid; 404 means the file or folder ID doesn't exist in your account.

Related

• Markdown Viewer — render and read .md files without an editor
• Online Markdown Editor — write markdown in the browser
• Markdown Live Preview — see formatting as you type
• Markdown File Format — what's inside an .md file
• What Is an MD File? — the plain-text format that powers the web