Docs

REST API Reference

mkdshare.DEV exposes a JSON REST API for creating, reading, updating, and annotating documents. Use it directly or through the MCP server.

Base URL

https://mkdshare.dev/api

Authentication

All requests require an Authorization header with your API token. Get your token at mkdshare.dev/api-access after signing in.

Authorization: Bearer <your-token>

Endpoints

GET /api/documents List your documents

GET /api/documents/:slug Get a document (includes content)

POST /api/documents Create a document

PATCH /api/documents/:slug Update a document

GET /api/documents/:slug/annotations List annotations

POST /api/documents/:slug/annotations Add an annotation

Create a document

POST /api/documents

Request body

title string required Document title

content string required Markdown content

visibility string optional "public" (default), "login_required", or "domain_restricted"

allowed_emails string optional Comma-separated list of allowed email addresses

allowed_domain string optional Domain restriction, e.g. "company.com"

expires_at string optional ISO 8601 expiry timestamp

Example

curl -X POST https://mkdshare.dev/api/documents \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "title": "My Project Brief",
      "content": "# Project Brief\n\nObjective: ...",
      "visibility": "public"
    }
  }'

Response

{
  "slug": "abc12345",
  "title": "My Project Brief",
  "url": "https://mkdshare.dev/d/abc12345",
  "visibility": "public",
  "created_at": "2026-05-17T12:00:00Z"
}

Get a document

GET /api/documents/:slug

curl https://mkdshare.dev/api/documents/abc12345 \
  -H "Authorization: Bearer <your-token>"

Update a document

PATCH /api/documents/:slug

Send only the fields you want to change. Same fields as create.

curl -X PATCH https://mkdshare.dev/api/documents/abc12345 \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"document": {"content": "# Updated content\n\n..."}}'

Annotations

Annotations are inline comments anchored to specific text in a document.

List annotations

curl https://mkdshare.dev/api/documents/abc12345/annotations \
  -H "Authorization: Bearer <your-token>"

Create an annotation

curl -X POST https://mkdshare.dev/api/documents/abc12345/annotations \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "annotation": {
      "body": "This section needs more detail.",
      "quoted_text": "Objective:"
    }
  }'

Prefer MCP?

The MCP server exposes the same capabilities and works from any MCP client without writing curl commands.

MCP Setup →