Public API/Posts/Create or upsert post
POST/api/posts

Create or upsert post

Create a draft, schedule a future publish, or publish now — upsert by slug with an account API key.

Primary write endpoint for the CLI and Obsidian plugin. Project is selected via X-Blogizi-Project, body fields, or automatically when the account has exactly one project. See Authentication. Supports drafting, scheduling, and immediate publish.

Request

POST /api/posts Authorization: Bearer YOUR_ACCOUNT_API_KEY X-Blogizi-Project: your-project-slug Content-Type: application/json
{ "title": "How we built our auth flow", "slug": "how-we-built-our-auth-flow", "description": "≤160 char meta description", "keyword": "indie app authentication", "content": "Markdown body…", "status": "draft", "scheduledAt": "2026-10-26T09:00", "upsert": false }

Fields

  • title, slug — required
  • description, keyword, content — optional but recommended for SEO
  • coverImageUrl — optional public cover image URL (also accepted as frontmatter coverImageUrl / coverImage). On upsert, omit to keep the existing cover. Upload bytes with Upload post image first if needed.
  • ctaTitle, ctaSubtitle, ctaButtonLabel, ctaButtonUrl — optional per-post CTA override (same rules as Write in Markdown); on upsert, omit a field to keep the existing value
  • sidebarCtaTitle, sidebarCtaText, sidebarCtaBullets (string array), sidebarCtaButtonLabel, sidebarCtaButtonUrl — optional per-post sidebar CTA override (title, button label, and URL required together); omit to keep existing values on update
  • status — draft or published (published publishes immediately and cancels any schedule)
  • scheduledAt — optional; see Scheduling below
  • upsert — when true, update an existing post with the same slug (Obsidian plugin pattern). Default create fails if the slug already exists.
  • projectSlug / project / projectId — optional if the header or sole-project rule already selects a blog

Scheduling

Use scheduledAt on this endpoint to queue a future publish. There is no separate public schedule route — set the field on create or upsert.

  • Schedule: send a future datetime. The post stays status: "draft" until Blogizi publishes it. Do not poll or flip to published early.
  • Timezone: ISO with Z or an offset (e.g. 2026-10-26T13:00:00.000Z) is absolute. Naive YYYY-MM-DDTHH:mm (e.g. 2026-10-26T09:00) is interpreted in the project timezone (Settings → General, default UTC).
  • Reschedule: upsert the same slug with a new future scheduledAt.
  • Unschedule: upsert with scheduledAt: null (keeps the draft). Omitting the field on upsert leaves the existing schedule unchanged.
  • Publish now: status: "published" goes live immediately and cancels any pending schedule.

Schedule example (project timezone):

{ "title": "How we built our auth flow", "slug": "how-we-built-our-auth-flow", "content": "Markdown body…", "status": "draft", "scheduledAt": "2026-10-26T09:00", "upsert": true }

Unschedule example:

{ "title": "How we built our auth flow", "slug": "how-we-built-our-auth-flow", "content": "Markdown body…", "status": "draft", "scheduledAt": null, "upsert": true }

List scheduled drafts via List project posts (scheduledAt on each item). MCP equivalent: schedule_post. Overview: Public API → Scheduling.

Inline images in content

Use standard Markdown after uploading a content image:

![Architecture diagram](https://media.blogizi.com/content/<postId>/<timestamp>.png)

Flow: create/upsert the post → upload with type=content → upsert again with the markdown snippet in content.

Response

Returns the post payload plus { project: { id, slug }, created: boolean }. Status is 201 on create and 200 on upsert update. When scheduled, data.status stays draft and data.scheduledAt is a UTC ISO string.

{ "data": { "slug": "how-we-built-our-auth-flow", "status": "draft", "scheduledAt": "2026-10-26T13:00:00.000Z" }, "project": { "id": "665f…", "slug": "my-app" }, "created": true }

Prefer CLI publishing for local markdown files. Use this endpoint when building your own client or when the Obsidian plugin upserts by slug.