POST/v1/documents/publish

Create and Publish

Create a document and publish it in a single API call. This is the most commonly used endpoint.

Create a new document and publish it in a single API call. This is the most commonly used endpoint for programmatic publishing. It combines Create Document and Publish Document into one step.

The document is saved to your account and immediately accessible at the returned published_url.

Request Body

Parameter	Type	Required	Default	Description
`content`	`string`	Yes		The markdown content to publish
`title`	`string`		`"Untitled"`	Document title
`template_id`	`string`		`"swiss"`	Template ID from the template catalog
`theme_mode`	`"light" \| "dark"`		`"light"`	Color theme
`slug`	`string`		auto-generated	Custom URL slug. Pro only.
`description`	`string`			Description for SEO metadata

Response

Returns the published document with its public URL.

Field	Type	Description
`id`	`string`	Document UUID
`title`	`string`	Document title
`published_url`	`string`	Full public URL
`published_at`	`string`	ISO 8601 timestamp
`template_id`	`string`	Template applied to the published page
`word_count`	`number`	Total word count
`reading_time_minutes`	`number`	Estimated reading time

Errors

Status	Code	Description
400	`validation_error`	Missing `content` field, invalid template, or invalid slug format
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	Custom slugs require Pro
403	`quota_exceeded`	Free tier limited to 3 documents
409	`conflict`	Slug is already taken
500	`internal_error`	Unexpected server error

NOTE

Free tier accounts are limited to 3 documents total. Once the limit is reached, you will receive a 403 error. Upgrade to Pro for unlimited documents.

curl -X POST https://api.unmarkdown.com/v1/documents/publish \
  -H "Authorization: Bearer um_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello World\n\nThis is my first published document.",
    "title": "Hello World",
    "template_id": "swiss"
  }'

const res = await fetch('https://api.unmarkdown.com/v1/documents/publish', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer um_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: '# Hello World\n\nThis is my first published document.',
    title: 'Hello World',
    template_id: 'swiss'
  })
});
const data = await res.json();
console.log(data.published_url);

import requests

res = requests.post(
    'https://api.unmarkdown.com/v1/documents/publish',
    headers={'Authorization': 'Bearer um_your_key'},
    json={
        'content': '# Hello World\n\nThis is my first published document.',
        'title': 'Hello World',
        'template_id': 'swiss'
    }
)
data = res.json()
print(data['published_url'])

Response (201)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Hello World",
  "published_url": "https://unmarkdown.com/u/jane/hello-world",
  "published_at": "2026-02-15T10:30:00.000Z",
  "template_id": "swiss",
  "word_count": 8,
  "reading_time_minutes": 1
}

With dark theme and custom template

curl -X POST https://api.unmarkdown.com/v1/documents/publish \
  -H "Authorization: Bearer um_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Release Notes\n\n## v2.1.0\n\n- Added dark mode\n- Fixed pagination bug",
    "title": "Release Notes",
    "template_id": "tokyo-night",
    "theme_mode": "dark"
  }'

Unpublish Document

Demo Publish