/api/postsCreate 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— requireddescription,keyword,content— optional but recommended for SEOcoverImageUrl— optional public cover image URL (also accepted as frontmattercoverImageUrl/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 valuesidebarCtaTitle,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 updatestatus—draftorpublished(publishedpublishes immediately and cancels any schedule)scheduledAt— optional; see Scheduling belowupsert— whentrue, 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 topublishedearly. - Timezone: ISO with
Zor an offset (e.g.2026-10-26T13:00:00.000Z) is absolute. NaiveYYYY-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:
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.