Blog API

18 operations. Authentication, errors and pagination work as described in the REST API overview.

Published blog posts, or your own

GET/api/v1/postsToken optional

Live posts newest first (tag, author handle, series slug, q), keyset-paginated with cursor. scope=mine lists the caller's own posts in every state (draft, in review, scheduled, published, rejected, unpublished).

listPosts parameters
Name	Type	Description
`scope` query	`"published" \| "mine"`
`tag` query	`string`
`author` query	`string`
`series` query	`string`
`q` query	`string`
`cursor` query	`string`
`limit` query	`integer (1–50)`

Responses: 200 OK304, 400, 404, 429

Response fields

listPosts response fields
Name	Type	Description
`items`required	`object[]`
`nextCursor`required	`string \| null`	Opaque cursor for the next page; null at the end

Example

curl 'https://incantory.ai/api/v1/posts' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Create a draft post

POST/api/v1/postsToken required

Owned by the caller; tags must exist; the slug is derived from the title unless given. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

Request body

createPost body fields
Name	Type	Description
`title`required	`string`
`subtitle`	`string`
`body`	`string`
`slug`	`string`
`tags`	`string[]`
`seriesId`	`string \| null`
`coverMediaId`	`string \| null`
`canonicalUrl`	`string \| null`

Responses: 201 OK400, 401, 403, 404, 409, 422, 429

Response fields

createPost response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`subtitle`required	`string`
`excerpt`required	`string`
`status`required	`"draft" \| "submitted" \| "in_review" \| "published" \| "rejected" \| "unpublished"`
`statusLabel`required	`string`
`publishedAt`required	`string \| null`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`readingMinutes`required	`integer (-9007199254740991–9007199254740991)`
`author`required	`object`
`tags`required	`string[]`
`cover`required	`object \| null`	A media view
`series`required	`object \| null`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`commentCount`required	`integer (-9007199254740991–9007199254740991)`
`hasPendingRevision`	`boolean`	Owner view only
`body`required	`string`	Markdown
`canonicalUrl`required	`string \| null`
`canonicalPath`required	`string`
`scheduled`required	`boolean`
`live`required	`boolean`
`deleted`required	`boolean`
`commentsLocked`required	`boolean`
`reviewNotes`required	`string \| null`
`pending`required	`object \| null`
`workingCopy`required	`object \| null`
`featured`required	`boolean`
`viewer`required	`object`
`toc`	`object[]`	With toc=1

Example

curl -X POST 'https://incantory.ai/api/v1/posts' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"title"}'

Get one post

GET/api/v1/posts/{id}Token optional

By id or slug. Drafts, posts in review and scheduled posts are visible to their author and moderators only. toc=1 adds the h2/h3 outline with the ids the page uses.

getPost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug
`toc` query	`"0" \| "1" \| "true" \| "false"`

Responses: 200 OK400, 404, 410, 429

Response fields

getPost response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`subtitle`required	`string`
`excerpt`required	`string`
`status`required	`"draft" \| "submitted" \| "in_review" \| "published" \| "rejected" \| "unpublished"`
`statusLabel`required	`string`
`publishedAt`required	`string \| null`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`readingMinutes`required	`integer (-9007199254740991–9007199254740991)`
`author`required	`object`
`tags`required	`string[]`
`cover`required	`object \| null`	A media view
`series`required	`object \| null`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`commentCount`required	`integer (-9007199254740991–9007199254740991)`
`hasPendingRevision`	`boolean`	Owner view only
`body`required	`string`	Markdown
`canonicalUrl`required	`string \| null`
`canonicalPath`required	`string`
`scheduled`required	`boolean`
`live`required	`boolean`
`deleted`required	`boolean`
`commentsLocked`required	`boolean`
`reviewNotes`required	`string \| null`
`pending`required	`object \| null`
`workingCopy`required	`object \| null`
`featured`required	`boolean`
`viewer`required	`object`
`toc`	`object[]`	With toc=1

Example

curl 'https://incantory.ai/api/v1/posts/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Edit a post

PATCH/api/v1/posts/{id}Token required

Author or admin. For a published post, title/subtitle/body become the working copy (savedTo: "working_copy"): the live text changes only when a submitted revision is approved. A new slug 301s the old URL. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

updatePost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Request body

updatePost body fields
Name	Type	Description
`title`	`string`
`subtitle`	`string`
`body`	`string`
`slug`	`string`
`tags`	`string[]`
`seriesId`	`string \| null`
`seriesPosition`	`integer (1–10000) \| null`
`coverMediaId`	`string \| null`
`canonicalUrl`	`string \| null`

Responses: 200 OK400, 401, 403, 404, 409, 410, 422, 429

Response fields

updatePost response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`subtitle`required	`string`
`excerpt`required	`string`
`status`required	`"draft" \| "submitted" \| "in_review" \| "published" \| "rejected" \| "unpublished"`
`statusLabel`required	`string`
`publishedAt`required	`string \| null`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)
`createdAt`required	`string`	ISO 8601 timestamp (UTC)
`readingMinutes`required	`integer (-9007199254740991–9007199254740991)`
`author`required	`object`
`tags`required	`string[]`
`cover`required	`object \| null`	A media view
`series`required	`object \| null`
`starCount`required	`integer (-9007199254740991–9007199254740991)`
`commentCount`required	`integer (-9007199254740991–9007199254740991)`
`hasPendingRevision`	`boolean`	Owner view only
`body`required	`string`	Markdown
`canonicalUrl`required	`string \| null`
`canonicalPath`required	`string`
`scheduled`required	`boolean`
`live`required	`boolean`
`deleted`required	`boolean`
`commentsLocked`required	`boolean`
`reviewNotes`required	`string \| null`
`pending`required	`object \| null`
`workingCopy`required	`object \| null`
`featured`required	`boolean`
`viewer`required	`object`
`toc`	`object[]`	With toc=1
`savedTo`required	`"post" \| "working_copy" \| "none"`

Example

curl -X PATCH 'https://incantory.ai/api/v1/posts/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Delete a post (soft)

DELETE/api/v1/posts/{id}Token required

Author or admin; the page answers 410. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

deletePost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Request body (optional)

deletePost body fields
Name	Type	Description
`reason`	`string`

Responses: 204 OK400, 401, 403, 404, 410, 429

Example

curl -X DELETE 'https://incantory.ai/api/v1/posts/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Save the working copy (editor autosave)

PUT/api/v1/posts/{id}/autosaveToken required

Drafts change in place; published posts get a revision. Kept as history (coalesced, newest 50). 409 while in review. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

autosavePost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Request body

autosavePost body fields
Name	Type	Description
`title`	`string`
`subtitle`	`string`
`body`	`string`

Responses: 200 OK400, 401, 403, 404, 409, 429

Response fields

autosavePost response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`savedTo`required	`"post" \| "working_copy" \| "none"`
`at`required	`string`	ISO 8601 timestamp (UTC)

Example

curl -X PUT 'https://incantory.ai/api/v1/posts/{id}/autosave' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Revision history

GET/api/v1/posts/{id}/revisionsToken required

Author or admin. Newest first; bodies via the single-revision route.

listPostRevisions parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Responses: 200 OK400, 401, 403, 404, 429

Response fields

listPostRevisions response fields
Name	Type	Description
`items`required	`object[]`

Example

curl 'https://incantory.ai/api/v1/posts/{id}/revisions' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

One revision with its body

GET/api/v1/posts/{id}/revisions/{revisionId}Token required

getPostRevision parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug
`revisionId` pathrequired	`string`	PostRevision id

Responses: 200 OK400, 401, 403, 404, 429

Response fields

getPostRevision response fields
Name	Type	Description
`id`required	`string`
`kind`required	`string`
`title`required	`string`
`subtitle`required	`string`
`body`required	`string`
`at`required	`string`	ISO 8601 timestamp (UTC)

Example

curl 'https://incantory.ai/api/v1/posts/{id}/revisions/{revisionId}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Restore a revision as the working text

POST/api/v1/posts/{id}/revisions/{revisionId}/restoreToken required

Author or admin. A published post gets a new working copy (submit it to go live). Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

restorePostRevision parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug
`revisionId` pathrequired	`string`	PostRevision id

Responses: 200 OK400, 401, 403, 404, 409, 429

Response fields

restorePostRevision response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`savedTo`required	`"post" \| "working_copy" \| "none"`

Example

curl -X POST 'https://incantory.ai/api/v1/posts/{id}/revisions/{revisionId}/restore' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Submit for review (or publish, for trusted authors)

POST/api/v1/posts/{id}/submitToken required

Drafts/rejected/unpublished → in review; a published post → a pending revision. Trusted authors publish directly; a future publishAt schedules. Spam and rate checks apply. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

submitPost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Request body (optional)

submitPost body fields
Name	Type	Description
`publishAt`	`any`
`title`	`string`
`subtitle`	`string`
`body`	`string`

Responses: 200 OK400, 401, 403, 404, 409, 422, 429

Response fields

submitPost response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`status`required	`"draft" \| "submitted" \| "in_review" \| "published" \| "rejected" \| "unpublished"`
`outcome`required	`"in_review" \| "published" \| "scheduled" \| "revision_in_review" \| "revision_published"`
`publishedAt`required	`string \| null`
`reviewItemId`required	`string \| null`

Example

curl -X POST 'https://incantory.ai/api/v1/posts/{id}/submit' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Unpublish a post

POST/api/v1/posts/{id}/unpublishToken required

Author, moderator or admin; a moderator's reason is sent to the author. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

unpublishPost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Request body (optional)

unpublishPost body fields
Name	Type	Description
`reason`	`string`

Responses: 200 OK400, 401, 403, 404, 409, 429

Response fields

unpublishPost response fields
Name	Type	Description
`id`required	`string`
`status`required	`"draft" \| "submitted" \| "in_review" \| "published" \| "rejected" \| "unpublished"`

Example

curl -X POST 'https://incantory.ai/api/v1/posts/{id}/unpublish' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Withdraw a submission

POST/api/v1/posts/{id}/withdrawToken required

Author. Back to draft (or the working copy for a pending revision). Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

withdrawPost parameters
Name	Type	Description
`id` pathrequired	`string`	Post id or slug

Responses: 200 OK400, 401, 403, 404, 409, 429

Response fields

withdrawPost response fields
Name	Type	Description
`id`required	`string`
`status`required	`"draft" \| "submitted" \| "in_review" \| "published" \| "rejected" \| "unpublished"`

Example

curl -X POST 'https://incantory.ai/api/v1/posts/{id}/withdraw' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Your series

GET/api/v1/posts/seriesToken required

Responses: 200 OK400, 401, 403, 404, 429

Response fields

listMySeries response fields
Name	Type	Description
`items`required	`object[]`

Example

curl 'https://incantory.ai/api/v1/posts/series' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Create a series

POST/api/v1/posts/seriesToken required

Series slugs are globally unique (/blog/series/{slug}). Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

Request body

createSeries body fields
Name	Type	Description
`title`required	`string`
`slug`	`string`
`description`	`string`

Responses: 201 OK400, 401, 403, 404, 409, 429

Response fields

createSeries response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`

Example

curl -X POST 'https://incantory.ai/api/v1/posts/series' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"title"}'

One series with its published posts in order

GET/api/v1/posts/series/{id}Token optional

getSeries parameters
Name	Type	Description
`id` pathrequired	`string`	Series id (GET: slug)

Responses: 200 OK400, 404, 429

Response fields

getSeries response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`
`title`required	`string`
`description`required	`string`
`author`required	`object`
`posts`required	`object[]`
`updatedAt`required	`string`	ISO 8601 timestamp (UTC)

Example

curl 'https://incantory.ai/api/v1/posts/series/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Edit a series

PATCH/api/v1/posts/series/{id}Token required

Owner or admin; a new slug 301s the old URL. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

updateSeries parameters
Name	Type	Description
`id` pathrequired	`string`	Series id (GET: slug)

Request body

updateSeries body fields
Name	Type	Description
`title`	`string`
`slug`	`string`
`description`	`string`

Responses: 200 OK400, 401, 403, 404, 409, 429

Response fields

updateSeries response fields
Name	Type	Description
`id`required	`string`
`slug`required	`string`

Example

curl -X PATCH 'https://incantory.ai/api/v1/posts/series/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Delete a series

DELETE/api/v1/posts/series/{id}Token required

Its posts stay published, outside any series. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

deleteSeries parameters
Name	Type	Description
`id` pathrequired	`string`	Series id (GET: slug)

Responses: 204 OK400, 401, 403, 404, 429

Example

curl -X DELETE 'https://incantory.ai/api/v1/posts/series/{id}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"

Reorder a series

POST/api/v1/posts/series/{id}/reorderToken required

postIds in reading order; every id must be in the series. Needs a signed-in session or an admin:mcp token (posts are not writable with a plain write token, PLAN §3).

reorderSeries parameters
Name	Type	Description
`id` pathrequired	`string`	Series id (GET: slug)

Request body

reorderSeries body fields
Name	Type	Description
`postIds`required	`string[]`

Responses: 200 OK400, 401, 403, 404, 422, 429

Response fields

reorderSeries response fields
Name	Type	Description
`ok`required	`true`

Example

curl -X POST 'https://incantory.ai/api/v1/posts/series/{id}/reorder' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"postIds":["postIds"]}'