REST API Reference

Base URL: https://api.mder.pro. All requests must include an Authorization: Bearer <token> header (see Authentication). Responses are JSON with Content-Type: application/json.

ℹ️ Versioning

All endpoints are prefixed with /v1. Future breaking changes will increment the version number.

Endpoints Overview

POST/v1/documentsCreate a document GET/v1/documentsList documents GET/v1/documents/:idGet document PATCH/v1/documents/:idUpdate document POST/v1/documents/:id/publishPublish document POST/v1/documents/:id/revokeRevoke document POST/v1/documents/:id/renewRenew TTL GET/v1/api-keysList API keys POST/v1/api-keysCreate API key DELETE/v1/api-keys/:idRevoke API key GET/v1/usageGet usage metrics GET/healthHealth check

Documents

POST/v1/documentsCreate and optionally publish a document

Create a new document. Use content for a simple single-block markdown document, or blocks for full control over block types.

Parameter	Type	Required	Description
`title`	string	Required	Document title (max 500 chars)
`content`	string	Optional	Shorthand: markdown content (auto-wrapped in a single markdown block)
`blocks`	Block[]	Optional	Array of typed blocks (see Block Types). Required if content is not set.
`document_type`	string	Optional ("document")	Type label for categorization
`summary`	string	Optional	Brief summary (max 2000 chars)
`status`	string	Optional ("published")	"published" or "draft"
`access_policy`	object	Optional	Access control settings (see below)
`render_options`	object	Optional	Render profile, theme, and ToC settings
`metadata`	object	Optional	Arbitrary key-value metadata

access_policy

Parameter	Type	Required	Description
`mode`	string	Optional ("unlisted")	"unlisted", "public", "password_protected", or "signed_link"
`ttl_hours`	number	Optional	Auto-expire after N hours (e.g. 168 = 7 days)
`password`	string	Optional	Password for password_protected mode (min 4 chars)
`allowed_views`	number	Optional	Max number of views before auto-revocation

render_options

Parameter	Type	Required	Description
`render_profile`	string	Optional ("default")	"default", "memo", "report", or "technical_doc"
`table_of_contents`	boolean	Optional (false)	Generate a table of contents
`theme`	string	Optional ("auto")	"light", "dark", or "auto"

Idempotency

Include an Idempotency-Key header to prevent duplicate documents from agent retries. If a document with the same key already exists, the existing document is returned with a 200 status.

terminalbash

curl -X POST https://api.mder.pro/v1/documents \
  -H "Authorization: Bearer mder_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-2026-04-20" \
  -d '{ "title": "Daily Report", "content": "# April 20\n\nAll systems nominal." }'

Response

201 Createdjson

{
  "document_id": "doc_8f2d4a...",
  "status": "published",
  "current_revision": 1,
  "viewer_url": "https://mder.pro/d/ab12cd",
  "short_url": "https://mder.pro/d/ab12cd",
  "resource_uri": "mder://documents/doc_8f2d4a...",
  "access_mode": "unlisted",
  "expires_at": null,
  "request_id": "req_..."
}

GET/v1/documentsList documents in the workspace

Parameter	Type	Required	Description
`status`	string	Optional	Filter by status: draft, published, expired, revoked, archived
`page`	number	Optional (1)	Page number
`page_size`	number	Optional (20)	Items per page (1-100)

terminalbash

curl "https://api.mder.pro/v1/documents?status=published&page=1" \
  -H "Authorization: Bearer mder_YOUR_KEY"

GET/v1/documents/:idGet document metadata and content

Returns full document metadata including blocks, access policy, and revision info.

terminalbash

curl https://api.mder.pro/v1/documents/doc_8f2d4a \
  -H "Authorization: Bearer mder_YOUR_KEY"

PATCH/v1/documents/:idUpdate a draft document

Update a document in draft status. Supports the same content shorthand as creation.

Parameter	Type	Required	Description
`title`	string	Optional	New title
`content`	string	Optional	New content (shorthand)
`blocks`	Block[]	Optional	New blocks array
`summary`	string	Optional	New summary
`access_policy`	object	Optional	Updated access policy
`render_options`	object	Optional	Updated render options
`metadata`	object	Optional	Updated metadata

POST/v1/documents/:id/publishPublish a draft document

Transitions a draft document to published status, making it accessible via its viewer URL.

Parameter	Type	Required	Description
`access_policy`	object	Optional	Override access policy at publish time

POST/v1/documents/:id/revokeRevoke document access

Immediately revokes access. The viewer URL will show a "document unavailable" message. Revoked documents can be renewed.

POST/v1/documents/:id/renewRenew document TTL

Extend or restart the TTL on a published or expired document.

Parameter	Type	Required	Description
`ttl_hours`	number	Optional (168 (7 days))	New TTL in hours

API Keys

GET/v1/api-keysList all API keys

Returns all API keys for the current workspace (keys are masked, showing only the prefix).

POST/v1/api-keysCreate a new API key

Parameter	Type	Required	Description
`name`	string	Required	Key name (max 100 chars)
`scopes`	string[]	Optional (["documents:write", "documents:read"])	Permission scopes
`expires_in_days`	number	Optional	Expiration in days (1-365)

DELETE/v1/api-keys/:apiKeyIdRevoke an API key

Immediately revokes the API key. All requests using this key will return 401.

Usage & Limits

GET/v1/usageGet current usage metrics

Returns usage metrics for the current billing period including document count, view count, and active document count versus plan limits.

Health Check

GET/healthService health check (no auth required)

Returns 200 with service status. No authentication required.

200 OKjson

{
  "status": "ok",
  "version": "1.0.0"
}

Error Format

All errors follow a consistent structure with a machine-readable code and human-readable message:

error responsejson

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title is required"
  },
  "request_id": "req_abc123"
}

Code	Status	Description
VALIDATION_ERROR	400	Request body failed schema validation
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions or scope
NOT_FOUND	404	Resource does not exist
PLAN_LIMIT_REACHED	403	Plan limit exceeded (upgrade required)
DOCUMENT_TOO_LARGE	400	Content exceeds size limit
INVALID_STATE	409	Document is not in the required state for this action

Rate Limits

Free tier: 60 requests per minute. Pro tier: 1,000 requests per minute. Rate limit headers are included in every response:

response headerstext

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1713600000

Plan Limits

Limit	Free	Pro
Documents / month	25	Unlimited
Active documents	10	Unlimited
Views / month	1,000	Unlimited
Max document size	512 KB	10 MB
Max TTL	720 hours (30 days)	Unlimited
API keys	2	20
PDF exports / month	10	Unlimited
Access modes	Unlisted only	All 4 modes
Render profiles	Default only	All profiles