UnmarkdownDocs

API Overview

The Unmarkdown REST API lets you convert, create, manage, and publish Markdown documents programmatically.

Base URL

All API requests are made to the following base URL:

text
https://api.unmarkdown.com/v1

The v1 prefix is included in every endpoint path. All requests must use HTTPS.

Authentication

Authenticate by including your API key in the Authorization header as a Bearer token. API keys start with um_ followed by 64 hex characters.

bash
curl https://api.unmarkdown.com/v1/documents \
  -H "Authorization: Bearer um_your_api_key"

You can create and manage API keys in the Settings panel under the API tab. Each account can have up to 2 active keys. Keys are shown only once at creation. If you lose a key, revoke it and create a new one.

Warning
Keep your API keys secret. Do not expose them in client-side code, public repositories, or browser requests. Always make API calls from your server.

Rate Limits

Rate limits are enforced per user via a sliding window:

  • Free: 10 requests per second
  • Pro: 30 requests per second

Rate limit status is returned in response headers:

  • X-RateLimit-Limit: Maximum requests per second for your plan
  • X-RateLimit-Remaining: Requests remaining in the current window
  • X-RateLimit-Reset: Unix timestamp when the window resets

When you exceed the rate limit, the API returns a 429 response with the rate_limited error code.

Monthly Quotas

API calls are tracked against a monthly quota:

  • Free: 1,000 API calls per month
  • Pro: 10,000 API calls per month

Quotas reset on the first day of each month (UTC). When your quota is exhausted, the API returns a 429 response with the quota_exceeded error code.

Note
The following endpoints do not count toward your monthly quota: GET /v1/documents, GET /v1/documents/:id, GET /v1/templates, and GET /v1/usage.

Content Type

All request bodies must be sent as JSON with the Content-Type: application/json header. All responses are returned as JSON.

Available Endpoints

Conversion

  • POST /v1/convert: Convert Markdown to styled HTML for any destination

Documents

  • POST /v1/documents: Create a new document
  • GET /v1/documents: List your documents (cursor-paginated)
  • GET /v1/documents/:id: Get a single document with full content
  • PATCH /v1/documents/:id: Update a document
  • DELETE /v1/documents/:id: Delete a document

Publishing

  • POST /v1/documents/:id/publish: Publish a document to the web
  • DELETE /v1/documents/:id/publish: Unpublish a document
  • POST /v1/documents/publish: Create and publish in one request

Templates

  • GET /v1/templates: List all 62 available templates

Usage

  • GET /v1/usage: Check your current plan usage and limits

Error Format

All errors return a JSON body with an error object containing a machine-readable code, a human-readable message, and the HTTP status:

json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Error Codes

The following error codes may be returned by any endpoint:

  • invalid_body (400): Request body is not valid JSON
  • validation_error (400): Missing required fields or invalid field values
  • unauthorized (401): Missing or invalid API key
  • forbidden (403): Your plan does not allow this action (e.g., Pro-only feature on Free)
  • not_found (404): The requested resource does not exist
  • conflict (409): Resource conflict (e.g., slug already taken)
  • quota_exceeded (429): Monthly API quota exhausted
  • rate_limited (429): Too many requests per second
  • internal_error (500): Unexpected server error
  • conversion_error (500): Markdown conversion pipeline failed
  • render_error (500): HTML rendering failed during publishing
Document IntelligenceConvert