The Marked Share API

Marked Share is built API-first. The same HTTP endpoints powering the Marked desktop app and the web frontend are available for your own scripts, Raycast extensions, Alfred workflows, and automated publishing pipelines.

Authentication and Endpoints

The API is located at https://share.markedapp.com/api/v1.

Requests require an API Token and write operations require an X-Device-Key header:

Authorization: Bearer <your_api_token>
X-Device-Key: <your_device_key>

Tokens and device keys can be created in your account settings.

Core Capabilities

1. Document Management

• List & Search: GET /documents?q=query&limit=25 supports full-text ranked search and pagination headers (X-Total-Count, Link).
• Create Documents: POST /documents accepts either raw JSON with body_markdown, title, visibility, and collection_slug, or multipart TextPack archives (.textpack / .zip).
• Update Documents: PATCH /documents/:id updates content safely with If-Match: <content_hash> optimistic concurrency locking.
• Export TextPacks: GET /documents/:id/textpack downloads the complete document bundle with images and metadata.

2. Highlight Sets and Reviews

• Retrieve Annotations: GET /documents/:id/highlight_sets lists all reader highlight sets on your documents.
• Import Highlights: POST /documents/:id/highlight_sets/:set_id/import merges a reviewer’s feedback into your personal highlight set.

3. Collections

• List Collections: GET /collections returns all collections, their display modes, and custom domains.
• Inspect Collection: GET /collections/:id?include=documents lists collection metadata and member posts.

4. Cross-Publishing

• Micro.blog: POST /documents/:id/microblog triggers immediate Micropub syndication with format: "full" or format: "excerpt".

Automating Your Workflow

Because Marked Share accepts standard Markdown over a clean REST API, you can easily integrate it into your existing tools:

curl -X POST https://share.markedapp.com/api/v1/documents \
  -H "Authorization: Bearer $MARKED_API_TOKEN" \
  -H "X-Device-Key: $MARKED_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "title": "My Post",
      "body_markdown": "# Hello World\nPublished via curl.",
      "visibility": "public",
      "collection_slug": "marked-share"
    }
  }'

With simple API primitives, you can publish from anywhere, script backups, and build custom workflows tailored to your writing habits.