MDShare API - Markdown Sharing Service

Overview

MDShare is a simple API for uploading, sharing, and viewing Markdown documents. Each document gets a unique 8-character ID and a shareable URL. Documents support revision history and embedded images.

For LLMs: Use this API to share Markdown outputs with users via short, shareable links. Simply POST your Markdown content and receive a URL you can provide to the user.

For LLM agents: /llms.txt

An LLM publishes, a human reviews and comments on the exact passage, the LLM reads those comments through the API and acts on them. The link stays the same through the whole loop.

POST /api/upload — publish, keep the id
Send /view/{id} to the reviewer (with a password if external)
The reviewer selects a passage in the browser and comments
GET /api/{id}/comments?status=open — read what is pending
PUT /api/update — fix the markdown, same link, new revision
PATCH /api/{id}/comments/{commentId} — mark it resolved

Full agent reference, including the anchor format: /llms.txt

API Endpoints

POST /api/upload

Upload a new Markdown document. Returns a unique ID and shareable URL.

Request Formats

1. Multipart Form Data (with images):

curl -X POST \
  -F "[email protected]" \
  -F "images[][email protected]" \
  -F "images[][email protected]" \
  https://mdshare.pages.dev/api/upload

2. JSON (markdown only):

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello World\n\nThis is my document."}' \
  https://mdshare.pages.dev/api/upload

3. JSON (with base64 images):

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello\n\n![Image](image.png)",
    "images": [
      {"name": "image.png", "data": "data:image/png;base64,iVBORw0KG..."}
    ]
  }' \
  https://mdshare.pages.dev/api/upload

4. Plain Text:

curl -X POST \
  -H "Content-Type: text/markdown" \
  -d '# Hello World' \
  https://mdshare.pages.dev/api/upload

Response:

{
  "success": true,
  "id": "8f14e45f",
  "url": "https://mdshare.pages.dev/view/8f14e45f",
  "revision": 1
}

PUT /api/update

Update an existing Markdown document. Creates a new revision.

JSON Request:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "id": "8f14e45f",
    "markdown": "# Updated Content\n\nThis is the new version."
  }' \
  https://mdshare.pages.dev/api/update

Multipart Form Data (with new images):

curl -X PUT \
  -F "id=8f14e45f" \
  -F "[email protected]" \
  -F "images[][email protected]" \
  https://mdshare.pages.dev/api/update

Response:

{
  "success": true,
  "id": "8f14e45f",
  "url": "https://mdshare.pages.dev/view/8f14e45f",
  "revision": 2
}

GET /api/{id}

Get the raw Markdown content and metadata for a document.

curl https://mdshare.pages.dev/api/8f14e45f

Query Parameters:

Parameter	Description
`revision`	Get a specific revision (e.g., `?revision=1`)
`format`	Set to `raw` to get plain Markdown text

Response (JSON):

{
  "success": true,
  "id": "8f14e45f",
  "created": "2025-01-30T12:00:00.000Z",
  "updated": "2025-01-30T14:30:00.000Z",
  "revision": 2,
  "totalRevisions": 2,
  "images": ["diagram.png", "screenshot.jpg"],
  "content": "# Hello World\n\nThis is my document."
}

GET /view/{id}

View the rendered Markdown document in a web browser.

https://mdshare.pages.dev/view/8f14e45f

Query Parameters:

Parameter	Description
`revision`	View a specific revision (e.g., `?revision=1`)

The viewer includes:

Syntax highlighting for code blocks
Light/dark theme toggle (saved in localStorage)
Revision selector dropdown
Rendered images
GitHub-flavored Markdown support

GET /api/{id}/comments

List the comments of a document. Each comment can be anchored to a passage of the text.

curl https://mdshare-a2m.pages.dev/api/8f14e45f/comments \
  -H "Authorization: Bearer $TOKEN"

Authorization: readers of a password-protected document need a token from POST /api/auth. Public documents are readable by anyone.

Response (JSON):

{
  "success": true,
  "docId": "8f14e45f",
  "revision": 3,
  "total": 1,
  "comments": [
    {
      "id": "3f9a1c2b7d4e5061",
      "parentId": null,
      "revision": 2,
      "author": "Eng. Marina",
      "body": "Was this already fixed in 2025?",
      "anchor": {
        "quote": "infiltração na face sul",
        "prefix": "O telhado apresenta ",
        "suffix": ", com manchas visíveis",
        "start": 61,
        "end": 84
      },
      "status": "open",
      "created": "2026-08-12T12:00:00.000Z"
    }
  ]
}

POST /api/{id}/comments

Create a comment. Whoever has the document password can comment; documents without a password only accept comments from whitelisted IPs.

curl -X POST https://mdshare-a2m.pages.dev/api/8f14e45f/comments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "Eng. Marina",
    "body": "Was this already fixed in 2025?",
    "anchor": {
      "quote": "infiltração na face sul",
      "prefix": "O telhado apresenta ",
      "suffix": ", com manchas visíveis",
      "start": 61,
      "end": 84
    }
  }'

The anchor keeps the comment attached to the passage across revisions: the offsets are tried first, then the surrounding context, then a whitespace-insensitive match. A comment whose passage disappeared is reported as orphaned.

Omit anchor for a document-level comment, or pass parentId to reply to another comment.

PATCH /api/{id}/comments/{commentId}

Resolve, reopen or edit a comment.

curl -X PATCH https://mdshare-a2m.pages.dev/api/8f14e45f/comments/3f9a1c2b7d4e5061 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

DELETE /api/{id}/comments/{commentId}

Delete a comment and its replies. Soft delete by default; add ?hard=true (whitelisted IPs only) to remove the row for good.

curl -X DELETE https://mdshare-a2m.pages.dev/api/8f14e45f/comments/3f9a1c2b7d4e5061 \
  -H "Authorization: Bearer $TOKEN"

DELETE /api/{id}

Delete the document: metadata, every revision, the images and the comments. Irreversible, whitelisted IPs only. Repeat the id in confirm.

curl -X DELETE "https://mdshare-a2m.pages.dev/api/8f14e45f?confirm=8f14e45f"

Use ?revision={n} instead to drop a single revision from the history. The current revision and the last remaining one cannot be deleted.

curl -X DELETE "https://mdshare-a2m.pages.dev/api/8f14e45f?revision=2"

Images

When you upload images with your Markdown, reference them using relative paths in your Markdown:

![Diagram](diagram.png)
![Screenshot](screenshot.jpg)

Images are served from /img/{id}/{filename} and are automatically resolved when viewing the document.

Revisions

Every update creates a new revision. You can:

View any revision using ?revision=N
Use the revision dropdown in the viewer
Get revision history via the API

LLM Integration Examples

Python (requests)

import requests

# Upload Markdown
response = requests.post(
    "https://mdshare.pages.dev/api/upload",
    json={"markdown": "# Report\n\nYour analysis results..."}
)
result = response.json()
print(f"View at: {result['url']}")

# Update existing
requests.put(
    "https://mdshare.pages.dev/api/update",
    json={"id": result['id'], "markdown": "# Updated Report\n\n..."}
)

JavaScript (fetch)

// Upload
const response = await fetch('https://mdshare.pages.dev/api/upload', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ markdown: '# Hello\n\nWorld' })
});
const { id, url } = await response.json();

// Update
await fetch('https://mdshare.pages.dev/api/update', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id, markdown: '# Updated' })
});

cURL One-liner

# Upload from stdin
echo "# Quick Note" | curl -X POST -d @- https://mdshare.pages.dev/api/upload

ID Format

Document IDs are 8-character hexadecimal strings (e.g., 8f14e45f). They are randomly generated using cryptographic randomness and are case-insensitive.

Rate Limits & Storage

Note: This service is restricted to whitelisted IPs only. Documents do not expire and are stored indefinitely.