POST/api/v1/documents

Publish a document

Creates a Markdown document and returns its link. Works without an account: send a token to own it. Keep the edit_secret from a call without a token: it is the only way to change or delete that document later.

Token optional10 per minute per IPMCP: publish_document

Guide: Publish your first document

Code samples and Try it

Request body

application/json, required

titlestring
Shown on the page and in link previews. Up to 200 characters.
contentstringRequired
The document's Markdown. 1–500,000 characters.
custom_slugstring
Your own address: markdrop.in/<custom_slug>. Letters, digits, - and _. Taken or reserved addresses answer 409. 3–50 characters. Matches ^[a-zA-Z0-9_-]+$.
expires_in"never" | "1d" | "7d" | "30d" | "custom"
When the document is deleted. custom needs custom_expires_at. Default "never".
custom_expires_atstring (date-time)
The deletion time, when expires_in is custom. Must be in the future. ISO 8601, for example 2026-11-30T12:00:00Z.
read_passwordstring
Readers must enter this password before they see the content. 1–100 characters.
encryptedboolean
Set by clients that encrypt in the browser: content and title are already ciphertext. The server never sees the key. Default false.
access_level"private" | "link" | "workspace"
Who can open it: link (anyone with the link), private (only you and the people you share it with) or workspace (members of its workspace). Default "link".
workspacestring
File it in this workspace: the workspace's id. 1–64 characters.
folderstring
An existing folder of workspace: its id or its path, like guides/setup. 1–400 characters.

Responses

201Created. Returns the document with its slug, url and edit_secret.
409The custom address is taken, or reserved.
422The request didn't validate. detail lists each problem, with where it is (loc) and why (msg).
429Too many requests from your IP address. Wait the seconds in Retry-After.

201 response: 37 fields (DocumentCreateResponse)

slugstring
urlstring
folder_patharray of string
titlestring | null
Shown on the page and in link previews.
contentstring
The document's Markdown.
created_atstring (date-time)
ISO 8601, for example 2026-11-30T12:00:00Z.
updated_atstring (date-time)
ISO 8601, for example 2026-11-30T12:00:00Z.
expires_atstring (date-time) | null
ISO 8601, for example 2026-11-30T12:00:00Z.
viewsinteger
Default 0.
is_password_protectedboolean
Default false.
is_ownedboolean
Default false.
is_ownerboolean
Default false.
idstring | null
refstring | null
google_doc_urlstring | null
google_doc_staleboolean
Default false.
vscode_syncedboolean
Default false.
encryptedboolean
Set by clients that encrypt in the browser: content and title are already ciphertext. The server never sees the key. Default false.
kindstring
Default "markdown".
mimestring | null
rendererstring | null
type_labelstring | null
size_bytesinteger | null
original_filenamestring | null
artifact_urlstring | null
download_urlstring | null
poster_urlstring | null
mediaobject | null
file_versioninteger | null
workspace_urlstring | null
access_levelstring
Who can open it: link (anyone with the link), private (only you and the people you share it with) or workspace (members of its workspace). Default "link".
workspace_idstring | null
canobject | null
read_ticketstring | null
access_epochinteger
Default 0.
edit_secretstring
Returned once. Send it as X-Edit-Secret to change or delete a document published without a token.
workspace_errorstring | null