Publish

Publish an existing document to the web. The document becomes accessible at a unique URL.

Publishing makes your document available as a live web page. You can optionally specify a custom URL slug and control visibility. If the document is already published, calling this endpoint again republishes it with any updated content or settings.

Tip

To update a published page, first update the document content with the Update endpoint, then call Publish again to push the changes live.

Endpoint

POST/v1/documents/:id/publish

Publish a document to the web. Republishing updates the live page.

Parameters

Parameter	Type	Description
`slug`	string	Custom URL slug (Pro only). If omitted, auto-generated from title
`description`	string	Page meta description for SEO
`hide_badge`	boolean	Hide the 'Published with Unmarkdown' badge (Pro only)
`visibility`	string	Page visibility: link (default), public (Pro), or specific (Pro)Default: `link`
`page_width`	string	Page width: full, wide, or standardDefault: `standard`

Request

bash

curl -X POST https://api.unmarkdown.com/v1/documents/d290f1ee-6c54-4b01-90e6-d701748f0851/publish \
  -H "Authorization: Bearer um_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "project-roadmap",
    "description": "Our Q1 roadmap and milestones",
    "visibility": "link"
  }'

Response

json

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "title": "Project Roadmap",
  "published_url": "https://unmarkdown.com/u/leonard/project-roadmap",
  "published_at": "2026-02-17T10:30:00Z",
  "template_id": "swiss",
  "word_count": 1250,
  "reading_time_minutes": 7
}

Error Response

json

{
  "error": {
    "code": "conflict",
    "message": "The slug 'project-roadmap' is already taken",
    "status": 409
  }
}

Status Codes

Status	Description
200	Document published successfully
400	Invalid slug format
401	Missing or invalid API key
403	Pro-only feature used on Free plan (custom slug, hide badge, public visibility)
404	Document not found
409	Slug already taken
429	Rate limit or quota exceeded
500	Render error or internal server error

Free vs Pro

Free accounts can publish with auto-generated slugs and link visibility. The Unmarkdown badge is always shown. Pro accounts unlock custom slugs, public and specific visibility options, and the ability to hide the badge.

Delete Document Unpublish