Is the Markdown API free?
Yes. It is included with a free account and there is no paid tier. Fair-use rate limits apply: 120 reads and 40 writes per minute per token, and 10 URL imports per minute.
Markdown document API
Keep Markdown in the cloud and read it back over plain HTTP — from a script, a CI job, or an agent. Raw .md URLs, content negotiation, and conditional writes so two writers cannot silently overwrite each other.
Authentication
Send a token as a bearer credential. Tokens begin mdt_, carry the scopes you chose when creating them, and can be revoked at any time from your settings.
List your documents
curl https://www.markdowntools.io/api/v1/documents \
-H "Authorization: Bearer $MDT_TOKEN"Every response includes RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 carries Retry-After.
Endpoints
| Method | Path | Does | Scope |
|---|---|---|---|
| GET | /api/v1/documents | List your documents, newest first. | documents:read |
| POST | /api/v1/documents | Create a document from JSON or raw Markdown. | documents:write |
| GET | /api/v1/documents/{id} | Read one document as JSON or Markdown. | documents:read |
| PUT | /api/v1/documents/{id} | Replace the content. Requires If-Match. | documents:write |
| PATCH | /api/v1/documents/{id} | Change title, star or trash state. | documents:write |
| DELETE | /api/v1/documents/{id} | Delete a document permanently. | documents:write |
| POST | /api/v1/documents/{id}/share | Publish a read-only link. | documents:write |
| DELETE | /api/v1/documents/{id}/share | Withdraw the link. | documents:write |
| POST | /api/v1/import-url | Import Markdown from a public URL. | documents:write |
| GET | /api/v1/account | Export every document you hold. | documents:read |
Creating and reading
Both JSON and raw Markdown bodies are accepted, so a shell pipeline does not have to wrap a document in an object just to send a document.
Create from a file
# Straight from a file — the body is the document
curl -X POST https://www.markdowntools.io/api/v1/documents \
-H "Authorization: Bearer $MDT_TOKEN" \
-H "Content-Type: text/markdown" \
-H "X-Document-Title: Release notes" \
--data-binary @NOTES.mdRead as JSON or as Markdown
# JSON, with metadata
curl https://www.markdowntools.io/api/v1/documents/$ID \
-H "Authorization: Bearer $MDT_TOKEN"
# The same document as raw Markdown
curl https://www.markdowntools.io/api/v1/documents/$ID \
-H "Authorization: Bearer $MDT_TOKEN" \
-H "Accept: text/markdown"Conditional writes, so nothing is lost
The ETag is the document revision. A PUT must state the revision it is replacing, and the write fails rather than clobbering an edit made in the meantime.
Read, then write conditionally
# Read, and keep the ETag
ETAG=$(curl -sI https://www.markdowntools.io/api/v1/documents/$ID \
-H "Authorization: Bearer $MDT_TOKEN" | grep -i '^etag:' | cut -d' ' -f2 | tr -d '\r')
# Write only if nobody else has since
curl -X PUT https://www.markdowntools.io/api/v1/documents/$ID \
-H "Authorization: Bearer $MDT_TOKEN" \
-H "Content-Type: text/markdown" \
-H "If-Match: $ETAG" \
--data-binary @NOTES.md
# 412 Precondition Failed means it changed; re-read and merge.Sharing and raw URLs
A published document is readable with no credential — by .md suffix, or by asking for Markdown at the page URL. Responses carry Vary: Accept, so caches keep the two representations apart.
Publish and fetch
# Publish, then read it back with no credential at all
curl -X POST https://www.markdowntools.io/api/v1/documents/$ID/share \
-H "Authorization: Bearer $MDT_TOKEN"
curl https://www.markdowntools.io/d/$SHARE_ID.md
curl https://www.markdowntools.io/d/$SHARE_ID -H "Accept: text/markdown"Errors
Every failure is a JSON object with a stable error.code.
| 401 | unauthorized | Missing, malformed or revoked credential. |
| 403 | forbidden | The token lacks the scope this call needs. |
| 404 | not_found | No such document, or not yours. |
| 409 / 410 | gone | The share link was revoked. |
| 412 | precondition_failed | If-Match did not match; re-read and retry. |
| 413 | payload_too_large | Over the per-document size limit. |
| 428 | precondition_required | PUT without If-Match. |
| 429 | rate_limited | Slow down; see Retry-After. |
Frequently Asked Questions
How do I get an API token?
Create an account, open Settings and API access from your workspace, and create a token with the scopes you need. The token is shown once and stored only as a SHA-256 hash, so it cannot be recovered later — create a new one and revoke the old one if you lose it.
How do I avoid overwriting a document an agent is also editing?
Every response carries an ETag, which is the document revision. Send it back as If-Match on a PUT and the write is rejected with 412 Precondition Failed if the document changed in the meantime. PUT requires If-Match for exactly this reason; send If-Match: * only when you genuinely mean to overwrite whatever is there.
Can an agent read a document without a token?
Only if the owner published a share link. A shared document is readable at /d/{shareId}.md, or at /d/{shareId} with an Accept: text/markdown header, with no credential. Everything else needs a bearer token, and documents are private by default.
What are the size limits?
A single document may hold up to 256 KB of Markdown, and an account may hold up to 1,000 documents.
Does it support MCP?
Not yet. The REST API is the layer an MCP server would wrap, and it was shipped first deliberately so that an MCP integration can be a thin adapter rather than a second implementation. Any agent that can make an HTTP request can use the API today.