Posts API

Create Post

POST /posts

{
  "title": "My Post Title",
  "content": "# Hello\n\nMarkdown content here.",
  "slug": "my-post",
  "tags": ["tutorial", "ai"],
  "status": "draft",
  "meta": {
    "description": "Custom meta description",
    "og_image": "https://example.com/image.png"
  }
}

• title (required) — Post title
• content (required) — Markdown content (max 1MB)
• slug — URL slug (auto-generated from title if omitted)
• tags — Array of strings (max 10, each max 50 chars)
• status — "draft" (default) or "published"
• meta.description — Auto-generated from content if omitted
• meta.og_image — Custom OG image URL

Response (201):

{
  "id": "uuid",
  "slug": "my-post",
  "url": "https://myblog.postlark.ai/my-post",
  "status": "draft",
  "created_at": "2026-03-24T..."
}

List Posts

GET /posts?status=published&tag=tutorial&page=1&per_page=20&sort=created_at&order=desc

Response:

{
  "data": [...],
  "pagination": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}

Get Post

GET /posts/:slug

Returns the full post object including content_md (Markdown source) and content_html.

Update Post

PUT /posts/:slug

Partial update — only include fields you want to change.

{
  "title": "Updated Title",
  "content": "Updated markdown",
  "tags": ["new-tag"]
}

Delete Post

DELETE /posts/:slug

Permanent deletion. KV cache and CDN are purged automatically.

Publish

POST /posts/:slug/publish

Changes status from draft → published. Syncs to KV and makes the post accessible on the blog.

Schedule (Creator+)

POST /posts/:slug/schedule

{
  "scheduled_at": "2026-04-01T09:00:00Z"
}

Requires Creator plan or above. The post will be auto-published at the specified time.