Publish Your First Document

End-to-end guide from API key creation to published URL.

Publish Your First Document

This guide walks through the full process: creating an API key, writing markdown, choosing a template, and publishing a document with a permanent URL.

Prerequisites

You need an Unmarkdown™ account. Sign up for free if you have not already.

1. Create an API key

Open unmarkdown.com and sign in
Click your avatar in the top bar, then select Settings
Go to the API tab
Click Create API key
Copy the key (it starts with um_ and will only be shown once)

IMPORTANT

Store your API key securely. It cannot be retrieved after creation. If you lose it, delete it and create a new one.

You can have up to 2 active API keys per account.

2. Prepare your markdown

Write the markdown content you want to publish. The API supports all standard markdown plus Unmarkdown™ extensions: Mermaid diagrams, Chart.js charts, Graphviz graphs, KaTeX math, callouts, task lists, highlights, and more.

Here is an example document:

# Project Update

## Summary

We shipped three features this week and closed 12 bugs.

## Highlights

- **Search**: Full-text search across all documents
- **Templates**: Added 8 new developer templates
- **API**: Rate limiting and usage quotas

> [!TIP]
> Use the executive template for business reports.

## Metrics

| Metric | This Week | Last Week | Change |
|--------|-----------|-----------|--------|
| Users  | 1,240     | 1,180     | +5.1%  |
| Docs   | 3,450     | 3,200     | +7.8%  |

3. Choose a template

Browse available templates to find the right style for your document. You can list all templates via the API:

curl https://api.unmarkdown.com/v1/templates \
  -H "Authorization: Bearer um_your_key_here"

const response = await fetch(
  "https://api.unmarkdown.com/v1/templates",
  {
    headers: { "Authorization": "Bearer um_your_key_here" },
  }
);

const { data } = await response.json();
data.forEach(t => console.log(`${t.id}: ${t.name} (${t.category})`));

import requests

response = requests.get(
    "https://api.unmarkdown.com/v1/templates",
    headers={"Authorization": "Bearer um_your_key_here"},
)

for t in response.json()["data"]:
    print(f"{t['id']}: {t['name']} ({t['category']})")

Free accounts have access to 8 templates. Pro accounts can use all 62. See Working with Templates for the full list.

4. Publish

Use the create-and-publish endpoint to publish in a single API call:

curl -X POST https://api.unmarkdown.com/v1/documents/publish \
  -H "Authorization: Bearer um_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Update",
    "content": "# Project Update\n\n## Summary\n\nWe shipped three features this week.",
    "template_id": "executive",
    "theme_mode": "light"
  }'

const response = await fetch(
  "https://api.unmarkdown.com/v1/documents/publish",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer um_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Project Update",
      content: "# Project Update\n\n## Summary\n\nWe shipped three features this week.",
      template_id: "executive",
      theme_mode: "light",
    }),
  }
);

const data = await response.json();
console.log(data.published_url);

import requests

response = requests.post(
    "https://api.unmarkdown.com/v1/documents/publish",
    headers={"Authorization": "Bearer um_your_key_here"},
    json={
        "title": "Project Update",
        "content": "# Project Update\n\n## Summary\n\nWe shipped three features this week.",
        "template_id": "executive",
        "theme_mode": "light",
    },
)

data = response.json()
print(data["published_url"])

The response includes:

{
  "id": "d4f7a8b2-1234-5678-9abc-def012345678",
  "title": "Project Update",
  "published_url": "https://unmarkdown.com/u/yourname/project-update",
  "published_at": "2026-02-15T12:00:00.000Z",
  "template_id": "executive",
  "word_count": 85,
  "reading_time_minutes": 1
}

Open the published_url to see your live document.

5. Update your document

To update the content later, use the PATCH endpoint with the document ID:

curl -X PATCH https://api.unmarkdown.com/v1/documents/d4f7a8b2-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer um_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Project Update\n\n## Summary\n\nUpdated content here."}'

await fetch(
  "https://api.unmarkdown.com/v1/documents/d4f7a8b2-1234-5678-9abc-def012345678",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer um_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: "# Project Update\n\n## Summary\n\nUpdated content here.",
    }),
  }
);

requests.patch(
    "https://api.unmarkdown.com/v1/documents/d4f7a8b2-1234-5678-9abc-def012345678",
    headers={"Authorization": "Bearer um_your_key_here"},
    json={"content": "# Project Update\n\n## Summary\n\nUpdated content here."},
)

Changes are reflected on the published page immediately.

Next steps

Demo Publish: Publish without an account
Rich Content: Add diagrams, charts, and math
API Reference: Create and Publish: Full endpoint documentation

Quickstart

Demo Publish (No Auth)