API overview

Everything you can do on markdrop.in goes through a JSON API at https://api.markdrop.in. Use it to publish from your own scripts and services. For publishing files from a terminal, the CLI is usually simpler; for AI apps, use the MCP server.

Every endpoint has its own page in this section, grouped in the sidebar: what it does, the token it needs, its rate limit, parameters, request body, responses, and samples in curl, JavaScript and Python. The pages are generated from the API's own description. The machine-readable OpenAPI description is at https://api.markdrop.in/openapi.json.

Endpoints that only markdrop.in's own pages use, such as sign-in, Google Docs export and the VS Code extension's sync, are left out.

https://api.markdrop.in/api/v1

All requests and responses use JSON (Content-Type: application/json) unless an endpoint says otherwise. Times are ISO 8601 in UTC.

Publish a Markdown document. No account is needed:

curl -X POST https://api.markdrop.in/api/v1/documents \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello", "content": "# Hello\n\nPublished from curl."}'

{
  "slug": "k3x9q2m",
  "url": "https://markdrop.in/k3x9q2m",
  "title": "Hello",
  "edit_secret": "sk_••••",
  "expires_at": null,
  "views": 0,
  "kind": "markdown"
}

The response is longer than shown. Keep edit_secret: it is returned only once, and it is the only way to change or delete a document published without an account. See Edit key.

Read it back:

curl https://api.markdrop.in/api/v1/documents/k3x9q2m

Requests can be anonymous, or carry one or more of these:

Create a token at markdrop.in/settings/tokens. It starts with mdk_, is shown once, and works until you revoke it. A token acts as your whole account, so treat it like a password and make one per script or device. More in API tokens.

curl https://api.markdrop.in/api/v1/me/documents \
  -H "Authorization: Bearer $MARKDROP_TOKEN"

A revoked or mistyped API token gets 401 with "detail": "Invalid API token". It is never treated as anonymous.

The sign-in token markdrop.in uses in your browser is also accepted as a bearer token, but it expires. Use an API token for anything that runs unattended.

The MCP endpoint, https://api.markdrop.in/mcp, is the exception: it accepts only the tokens AI apps get through Markdrop's approval screen, and refuses mdk_ tokens. See Connect an AI app.

Every new document comes with an edit secret (sk_…) in the create response. Send it as X-Edit-Secret to update (PUT /documents/{slug}), delete (DELETE /documents/{slug}), or change the password and expiry (PATCH /documents/{slug}/settings) without signing in. If an edit secret leaks, the document's owner can replace it with POST /documents/{slug}/edit-secret/rotate; the old one stops working at once.

To attach an anonymous document to your account, call POST /documents/{slug}/claim with both your API token and its X-Edit-Secret.

Send the password as X-Read-Password when you read:

curl https://api.markdrop.in/api/v1/documents/q3-report \
  -H "X-Read-Password: ••••••••"

Without it, the API answers 401 with the header X-Markdrop-Gate: password. A wrong password gets 403 "Incorrect password". After repeated wrong passwords from one address, the API answers 429 for a few minutes.

Errors use HTTP status codes and a JSON body with a detail message you can show to a person:

{ "detail": "Document not found" }

A 422 looks like this:

{
  "detail": [
    { "type": "string_too_short", "loc": ["body", "custom_slug"], "msg": "String should have at least 3 characters", "input": "ab" }
  ]
}

When a document's address was renamed, reading the old slug answers 200 with {"moved": true, "slug": "<new slug>", "url": "…"} and the header X-Markdrop-Moved: <new slug>, but only to someone allowed to read the document. Follow it to the new slug.

Limits are counted per client IP address, per minute unless shown otherwise. Some of the most used:

Over the limit, the API answers 429 with a Retry-After header giving the seconds to wait, and this body:

{ "error": "Rate limit exceeded: 10 per 1 minute" }

Note that this one error uses error rather than detail. Browsers can read Retry-After from cross-origin requests.