API reference

Base URL and credentials

https://share.markedapp.com/api/v1

Published document links use markedb.in, but every API request goes to share.markedapp.com. Create credentials in Settings: Create API token issues a token on its own, while Connect Marked issues a token and a device key together. Both are shown once.

The device key is what makes conflict detection possible: it lets the server tell you which machine published the version you are about to overwrite.

Errors

Documents

A document can be addressed by its public id, its short share code, or its private id (a UUID). Marked stores the private id, since it stays valid regardless of visibility changes.

Results are paged: limit defaults to 50 and caps at 200, and page starts at 1. Unusable values fall back to the default rather than erroring. The response stays a plain array, with paging details in the headers — X-Total-Count holds the full count, and Link carries rel="next" and rel="prev" URLs when there are more pages.

curl -i "https://share.markedapp.com/api/v1/documents?limit=25" \
  --header "Authorization: Bearer $MARKED_API_TOKEN"

X-Total-Count: 138
Link: <https://share.markedapp.com/api/v1/documents?limit=25&page=2>; rel="next"

Pass q to search titles and bodies with the same fuzzy full-text ranking as the web library. Search hits omit body_markdown by default and include a short snippet instead. Add include=body when you need the Markdown in the list response. Whitespace-only q is ignored (normal list). Paging (limit, page, X-Total-Count, Link) is unchanged; Link URLs keep q (and include when set).

curl -i "https://share.markedapp.com/api/v1/documents?q=kubernetes&limit=25" \
  --header "Authorization: Bearer $MARKED_API_TOKEN"

curl https://share.markedapp.com/api/v1/documents/$DOCUMENT_ID \
  --header "Authorization: Bearer $MARKED_API_TOKEN"

{
  "id": "abc123",
  "private_id": "8f2c…",
  "url": "https://markedb.in/x7k2m",
  "content_hash": "9b1e…",
  "visibility": "unlisted",
  "reading_style": "swiss",
  "created_at": "2026-08-20T09:14:02.000Z",
  "updated_at": "2026-08-25T12:00:00.000Z",
  "title": "Shared from Marked",
  "body_markdown": "# Hello from Marked",
  "allow_remix": false
}

created_at and updated_at are ISO 8601 timestamps in UTC with millisecond precision, and both come back on every document response, including list and create.

reading_style is the typography the author published — editorial, manuscript, swiss, contrast, typewriter — or null for no published style, which readers see as Editorial. It comes back on every document response, and an unknown value is rejected with 422. See sharing for what each style looks like.

curl "https://share.markedapp.com/api/v1/documents/$PRIVATE_ID/textpack" \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --output MyDoc.textpack

Send JSON when you only have Markdown:

curl https://share.markedapp.com/api/v1/documents \
  --request POST \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "document": {
      "title": "Shared from Marked",
      "body_markdown": "# Hello from Marked",
      "visibility": "unlisted",
      "allow_remix": false
    }
  }'

Accepted fields are title, body_markdown, visibility, allow_remix, apex_mode, share_slug, and reading_style. Visibility defaults to private. A body is required and is capped at 500,000 bytes.

TextPack uploads

Send multipart/form-data with a file field to publish a document that has images. The archive is a zipped TextBundle (.textpack) or any .zip containing a Markdown file. Images are stored as document assets and the Markdown image paths are rewritten to hosted URLs. A highlights.json in Marked's format is imported as your own highlight set.

An info.json in the archive can publish the reading style, either under the com.markedapp.share namespace or as a bare readingStyle key. A document[reading_style] form field overrides it, and an unknown style is ignored. Downloaded TextPacks carry the same file, so a round trip keeps the style.

{
  "version": 2,
  "type": "net.daringfireball.markdown",
  "transient": false,
  "creatorIdentifier": "com.markedapp.share",
  "com.markedapp.share": {
    "documentId": "abc123",
    "url": "https://markedb.in/x7k2m",
    "readingStyle": "swiss"
  }
}

curl https://share.markedapp.com/api/v1/documents \
  --request POST \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --form "file=@./MyDoc.textpack" \
  --form "document[visibility]=unlisted" \
  --form "document[allow_remix]=false"

curl "https://share.markedapp.com/api/v1/documents/$PRIVATE_ID" \
  --request PATCH \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --header "If-Match: $CONTENT_HASH" \
  --form "file=@./MyDoc.textpack"

A missing or stale hash is a conflict rather than an overwrite:

{
  "error": "conflict",
  "content_hash": "current-hash",
  "updated_by_device_label": "Marked on Sisyphus"
}

Recover by fetching the document (or reading the hash out of the 409 body), deciding whether to keep the server's version, and retrying with the current hash. Each body change also records a version snapshot in the document's history.

Captures

curl https://share.markedapp.com/api/v1/captures \
  --request POST \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com/article"}'

Returns 201 with id, private_id, url, content_hash, source_url, visibility, created_at, and updated_at. A missing URL returns 422 with {"error":"url_required"}.

Highlight sets

Each set is one reader's highlights and notes on a document. See Highlights and reviews for the concepts behind them. Reading requires only that you can read the document; writing requires a token.

[
  {
    "id": "hl_abc123",
    "document_id": "abc123",
    "url": "https://markedb.in/x7k2m?hl=hl_abc123",
    "label": "Anonymous reviewer",
    "highlight_count": 12,
    "note_count": 3,
    "updated_at": "2026-08-25T12:00:00.000Z",
    "owner": false,
    "parent_set_id": null,
    "content_signature": "4c9f…"
  }
]

{
  "id": "hl_abc123",
  "payload": {
    "version": 1,
    "highlights": [
      {
        "id": "hl_9f21",
        "kind": "highlight",
        "text": "the passage that was highlighted",
        "color": "yellow",
        "note": "needs a citation",
        "signature": "ED",
        "fingerprint": "b3d1…",
        "range": { "start": {}, "end": {} }
      }
    ]
  }
}

kind is highlight or comment. note is the reader's note (also mirrored as comment for Marked's format), signature is the label the reader typed, and fingerprint identifies the passage so the same highlight can be recognised across sets. Anchoring fields (range, marked_anchor, prefix, suffix) may also be present.

curl https://share.markedapp.com/api/v1/documents/$DOCUMENT_ID/highlight_sets \
  --request POST \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "highlights": [
      { "kind": "highlight", "text": "a passage", "color": "yellow", "note": "nice" }
    ]
  }'

curl https://share.markedapp.com/api/v1/documents/$DOCUMENT_ID/highlight_sets/$REVIEW_ID/import \
  --request POST \
  --header "Authorization: Bearer $MARKED_API_TOKEN"

Downloads and change checks

Browser-friendly exports live on the document host rather than under /api/v1. Connected apps should prefer GET /api/v1/documents/:id/textpack (above) so bearer tokens unlock private documents; these URLs follow the same visibility rules but only honor a signed-in browser session, not an API token.