POST /api/v1/publish

Publish a Markdown file and receive a stable URL.

Auth

API key or session auth.

Request body

{
  "markdown": "# Launch note\n\nShip it.",
  "title": "Launch note",
  "slug": "launch-note",
  "visibility": "workspace",
  "workspaceId": "ws_123",
  "tags": ["launch", "release"],
  "sourcePath": "launch-note.md",
  "confirmPublic": false
}

Fields

Field	Type	Required	Notes
markdown	string	Yes	The raw Markdown content
title	string	No	Overrides inferred title
slug	string	No	Preferred URL slug
visibility	string	Yes	Use private, workspace, or public in the normal external workflow
workspaceId	string	Yes	Must belong to the authenticated user
tags	string[]	No	Up to 20 tags
sourcePath	string	No	Helpful source metadata
confirmPublic	boolean	No	Must be true when visibility is public

Example request

curl https://api.opendocs.cc/api/v1/publish \
  -X POST \
  -H "Authorization: Bearer od_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Checkout API reference\n\nEndpoint summary.",
    "visibility": "workspace",
    "workspaceId": "ws_123",
    "tags": ["api", "checkout"]
  }'

Success response

{
  "postId": "post_123",
  "slug": "checkout-api-reference",
  "url": "/yourteam/checkout-api-reference",
  "title": "Checkout API reference",
  "tags": ["api", "checkout"]
}

Public publishing

This fails:

{
  "visibility": "public",
  "confirmPublic": false
}

Use:

{
  "visibility": "public",
  "confirmPublic": true
}

Errors

Common application-level failures are returned as:

{
  "error": "publish_failed",
  "message": "Workspace not found."
}