Skip to main content

Post mutation endpoints

POST /api/v1/posts/:postId/update​

Update the current content of a published post.

Example request​

{
  "markdown": "# Revised title\n\nUpdated body.",
  "title": "Revised title",
  "visibility": "workspace",
  "workspaceId": "ws_123",
  "tags": ["api", "v2"],
  "sourcePath": "revised-doc.md",
  "confirmPublic": false
}

Success response​

{
  "postId": "post_123",
  "versionId": "ver_456",
  "versionNumber": 2,
  "slug": "checkout-api-reference",
  "title": "Revised title",
  "visibility": "workspace",
  "tags": ["api", "v2"]
}

POST /api/v1/posts/:postId/unpublish​

Unpublish a post.

Success response​

{
  "postId": "post_123",
  "unpublished": true
}

POST /api/v1/posts/:postId/visibility​

Change post visibility without uploading new Markdown.

Example request​

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

Success response​

{
  "postId": "post_123",
  "visibility": "public"
}

Notes​

  • Use private, workspace, or public in the normal external workflow.
  • The backend validation enum also contains a domain-restricted value for more advanced workspace flows, but the current public CLI and getting-started path are centered on the three modes above.

PATCH /api/v1/posts/:postId/tags​

Patch tags incrementally.

Example request​

{
  "add": ["reference"],
  "remove": ["draft"]
}

Success response​

{
  "postId": "post_123",
  "tags": ["api", "reference"]
}

Validation note​

At least one of add or remove must be non-empty.