Markdown import

This workflow stages one Markdown document, lets the caller inspect the parsed result, then creates a post only after explicit confirmation. It does not upload archives or read a client filesystem path.

Authentication

All routes require a bearer token, a publication selector or staged import_id, and the listed capability. The importing principal must be permitted to create posts in the publication.

Routes

Route	Method	Capability	Required input	Optional input and behavior	Success result
/import/start	POST	import.start	Publication selector, content	source_name, allow_create_tags	Staged import.
/import/status	POST	import.status	import_id	Matching publication selector	Staged import.
/import/apply	POST	import.apply	import_id	publish_import	Applied import and post.
/import/cancel	POST	import.cancel	import_id	Matching publication selector	Cancelled import.
/import/production	POST	Machine-client production access	bundle	apply, sync_mode	Production synchronization result.

Start an import

Field	Required	Type	Description
publication_id / publication_slug	Yes	UUID / String	Selects the publication.
content	Yes	String	One Markdown document, up to 1 MiB.
source_name	No	String	Display-only source name.
allow_create_tags	No	Boolean	When true, missing tags are staged for creation during apply. Defaults to false.

curl -sS https://api.blog.service.m7.org/v1/import/start \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "publication_slug":"engineering-notes",
    "source_name":"release-notes.md",
    "content":"---\\ntitle: \\\"Release notes\\\"\\ntags: [\\\"m7\\\"]\\n---\\n\\n# Release notes"
  }'

The document must begin with a --- front-matter delimiter followed by Markdown body text. title and body are required. The optional front-matter fields are slug, date (YYYY-MM-DD), author, authors, category, tags, excerpt, body_format (markdown or html), and visibility (public, unlisted, or private). Use author or authors, not both.

The source author, category, and tags must already exist in the selected publication. With allow_create_tags: true, unknown tags are reported in preview.tag_names_to_create and are created only when the import is applied. Unknown authors and categories make the stage invalid.

Review and apply

An import returns state as ready, invalid, applied, or cancelled. A ready preview contains the normalized title, slug, source body, body format, visibility, resolved author, category, tag references, and field-level errors where applicable.

{ "import_id": "IMPORT_UUID", "publish_import": true }

/import/apply normally creates a draft post. Set publish_import: true only when the source includes a valid date; that date becomes the post's published_at. Applying an already applied import is idempotent. /import/cancel can cancel only ready or invalid imports and never deletes a post created by a prior apply.

Production synchronization

/import/production is a separate machine-client integration for synchronizing a complete publication bundle. Its authentication and bundle contract are documented in Production synchronization.