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 an app 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.

Connecting an app

Open the connect page with a custom-scheme return_to so credentials return to the app instead of being copied by hand. The URL needs a host (myapp://auth/callback, not myapp:login). http, https, and the Marked 2 x-marked: scheme are rejected. Marked still uses x-marked-3://login.

https://share.markedapp.com/auth/marked?return_to=myapp://auth/callback&label=Read%20Later

After the user confirms, the page launches that callback with api_token, device_key, api_base, and label in the query. The same values stay on the page with an Open app button if the OS prompt is dismissed.

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"

Pass folder to list documents in that library folder and its subfolders (the same scope as the web library). The value is a folder path such as Work or Work/Client A. A missing folder returns 404. A known empty folder returns an empty array and X-Total-Count: 0. q still searches inside that scope. Link URLs keep folder when it is set. Omit folder (or send a blank value) to list the whole library.

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

{
  "documents": [
    {
      "id": "abc123",
      "library_path": "Work/Note",
      "content_hash": "…",
      "updated_at": "2026-09-23T12:00:00.000Z"
    }
  ],
  "tombstones": [
    {
      "id": "old456",
      "library_path": "Work/Gone",
      "deleted_at": "2026-09-22T09:00:00.000Z"
    }
  ]
}

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, reading_style, published_at, library_path, and the collection fields collection_id, collection_slug, or collection_ids. Visibility defaults to private. A body is required and is capped at 500,000 bytes.

library_path files the document in your library. Work/Notes means folder Work; the leaf is always taken from the title, and a taken name gets a number. A value with no slash counts as a folder only if that folder already exists; otherwise the document goes to the root. Omit it to file at the root.

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/import \
  --request POST \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "documents": [
      { "title": "Meeting notes", "body_markdown": "# Meeting notes", "library_path": "Work" },
      { "title": "Spec", "body_markdown": "# Spec", "library_path": "Work/Client A" }
    ]
  }'

Each item takes the same fields as a JSON create. Here library_path is always a folder: missing folders are created, a blank value files the document at the root, and the leaf comes from the title (duplicate titles are numbered). Items are created in order, each on its own, so one bad item does not stop the rest. The response lists what was created, by the item's position in your array, plus any per-item errors:

{
  "created": [
    { "index": 0, "id": "abc123", "private_id": "8f2c…", "content_hash": "9b1e…", "library_path": "Work/Meeting notes", … }
  ],
  "errors": [
    { "index": 1, "error": "Body markdown can't be blank" }
  ]
}

The status is 200 when at least one item was created and 422 when every item failed. A missing or empty documents array is 422 documents_required; more than 200 documents is 422 import_too_large. Created rows carry the same fields as a single create, so store each private_id and content_hash against the local file. Imported documents render their HTML in the background; the Markdown, hash, and sync index are available immediately.

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.

curl "https://share.markedapp.com/api/v1/documents/$DOCUMENT_ID" \
  --request DELETE \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --header "If-Match: $CONTENT_HASH"

Folders

Library folders are path strings (Work, Work/Client A). Root is not a folder row. Empty folders are included. Compatible apps use this list as a sync picker, then create a path if it does not exist yet.

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

[
  { "path": "Inbox", "locked": false },
  { "path": "Journal", "locked": true },
  { "path": "Work", "locked": false },
  { "path": "Work/Client A", "locked": false }
]

locked is true when the folder or any parent folder is locked from the web library. Documents in a locked folder are always private: creating, updating, or importing one with visibility set to public or unlisted succeeds but stores it as private, so read visibility from the response. Locking and unlocking are only available on the web.

curl https://share.markedapp.com/api/v1/folders \
  --header "Authorization: Bearer $MARKED_API_TOKEN" \
  --header "X-Device-Key: $MARKED_DEVICE_KEY" \
  --header "Content-Type: application/json" \
  --data '{"folder":{"path":"Work/Client A"}}'

Folder sync

Compatible apps can keep a local folder paired with a Share prefix. Seed the files the server does not have yet with POST /documents/import, up to 200 documents per request, and record each returned id and content_hash. After that, GET /documents?view=index&folder=Work is the snapshot: apply tombstones first, then pull or skip each live row by id and content_hash. An id you know that is in neither documents nor tombstones was moved outside the folder, not deleted; GET /documents/:id returns its new library_path. Push with POST/PATCH as today (library_path is the folder only). Local deletes use DELETE with If-Match. A 409 means the server moved on — pull, do not overwrite or delete. If you still want the rejected local body, publish it as a new document (for example a title ending in (conflicted)). Share does not create that copy.

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.