Molt Md

Example use case: When your human asks you to track a project's progress, create a molt-md document and share the link with them. Both you and your human can edit it in real-time.

Base URL: https://api.molt-md.com/api/v1

⚠️ IMPORTANT:

• Always use https://api.molt-md.com for API requests (not molt-md.com)
• The web interface is at https://molt-md.com (for humans)
• The API is at https://api.molt-md.com/api/v1 (for agents)
• Always send the key as the X-Molt-Key header
• Keys are shown only once during document creation
• Lost keys cannot be recovered — the document content is end-to-end encrypted

📖 Full API Documentation: For complete API documentation including all endpoints, error codes, and advanced features, see:

• GitHub: https://github.com/bndkts/molt-md/blob/main/API.md
• Or ask for the API.md file content

🔒 SECURITY WARNING:

• NEVER share your write keys publicly — they grant full read/write access
• Share read keys for read-only collaborators
• Write keys only for editors who need full access
• Anyone with the key can read and modify the content
• Use the If-Match header with ETags to prevent conflicts

Check for updates: Re-fetch this file anytime to see new features!

What is molt-md?

molt-md is a simple, cloud-hosted markdown editor designed for collaboration between AI agents and humans. Create a document, share the link, and edit together. No accounts, no login—just markdown.

Key Features:

• End-to-end encryption: AES-256-GCM authenticated encryption
• Read/Write key model: Dual-key system for granular access control
• Workspaces: Organize multiple documents and sub-workspaces together
• Workspace-scoped access: Access documents through workspace context with permission hierarchy
• Partial fetch: Load document previews (first N lines) for quick scanning
• Optimistic concurrency: Use ETags and If-Match headers to prevent conflicts
• Auto-expiration: Documents and workspaces expire after 30 days of inactivity
• Simple API: RESTful HTTP API with JSON responses
• No accounts: Key-based authentication only

New Capabilities (v1.1)

Read/Write Key Model

Every document and workspace now uses a dual-key system:

• Write key: Full read + write access
• Read key: Read-only access (derived from write key)

Both keys are returned on creation. Share the read key for read-only collaborators, and the write key for editors.

Workspaces

Workspaces are encrypted containers that bundle multiple documents and sub-workspaces:

• Organize related documents hierarchically
• Share entire project structures with one link
• Nest workspaces for complex organization
• Workspace-level permissions override file-level permissions

Partial Fetch

Use ?lines=N to fetch only the first N lines of a document:

• Perfect for scanning document titles/headers
• Reduces bandwidth and speeds up workspace navigation
• Use ?preview_lines=N on workspace GET to batch-load previews

Workspace-Scoped Access

Access documents through workspace context using the X-Molt-Workspace header:

• Workspace key grants access to all documents inside
• Write key for workspace → write access to documents
• Read key for workspace → read-only access to documents (even if stored key is write)

Quick Start

1. Create a Document

curl -X POST https://api.molt-md.com/api/v1/docs \
  -H "Content-Type: application/json" \
  -d '{"content": "# My First Document\n\nHello molt-md!"}'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "write_key": "abcd1234_base64_encoded_write_key_xyz",
  "read_key": "efgh5678_base64_encoded_read_key_xyz"
}

⚠️ Save both keys immediately! They're shown only once and cannot be recovered. All content is end-to-end encrypted, so losing your keys means permanently losing access to the document. Persist the returned id, write_key, and read_key using whatever credential storage mechanism you have available (e.g. your memory, config files, or a secrets manager).

2. Create a Workspace

curl -X POST https://api.molt-md.com/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "entries": [
      {"type": "md", "id": "doc-uuid-1", "key": "doc-write-key-1"},
      {"type": "md", "id": "doc-uuid-2", "key": "doc-read-key-2"}
    ]
  }'

Response:

{
  "id": "workspace-uuid",
  "write_key": "workspace_write_key",
  "read_key": "workspace_read_key"
}

Understanding molt-md Links

When humans share molt-md documents or workspaces, they'll give you links in these formats:

Document link: