# 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:

```http
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:

```bash
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.