POST /api/v1/sites/{siteId}/pages creates a draft page at the given path. Send MDX content and optional metadata. Use Idempotency-Key to safely retry. Create parent collections via POST …/collections first.
Request
POST /api/v1/sites/{siteId}/pages
Authorization: Bearer av_live_…
Content-Type: application/json
Idempotency-Key: create-docs-overview-v1
{
"path": "/guides/overview.mdx",
"content": "# Overview
Welcome to the guides.",
"metadata": {
"title": "Overview",
"summary": "Getting started with our API"
}
}
Required scope:content:write
Body fields
Field
Required
Description
path
yes
MDX path (for example /foo.mdx or /docs/bar.mdx). Normalized automatically.
content
no
MDX string. Defaults to a heading derived from the filename.
Optional `{ content_id }` or `{ path }` of the default-locale source page. Requires `locale` and creates a linked translation variant (see [Link translation](/link-translation.mdx)).
locale
no
Target locale code (for example `de`) when using `translation_of`.
Page content is Aveiro-dialect MDX: registered components only — unregistered JSX tags are rejected with 422 INVALID_MDX. Content pages stay linear editorial (markdown headings and prose). Landing pages (home, product, pricing, about) are stacks of page sections such as <HeroSection />, <FeaturesSection />, and <CtaSection /> — not hand-rolled Row/Column heroes. Agents connected over MCP should call aveiro_authoring_guide before their first write; include the sections topic for landing pages. The guide also covers LineChart, OgCard, Collection, and images.
When the stored content is valid but reads off-dialect — a row of buttons, a hand-rolled hero, a list of bare links where a Collection or OgCard belongs — the response includes an advisory recommendations array alongside page. The write has already succeeded; each entry carries a stable code and a message describing the suggested rewrite:
Idempotency
Pass Idempotency-Key on create requests so network retries do not create duplicate pages. Reusing the same key with a different body returns 409 IDEMPOTENCY_CONFLICT.
Parent folders
The path’s parent folder must already exist. For /docs/api/foo.mdx, create the docs/api folder in the editor first. If the folder is missing, the API returns:
Root-level pages (for example /about.mdx) work without a parent folder.
{
"page": { "…": "…" },
"recommendations": [
{
"code": "internal-link-list",
"message": "A list of 3+ internal links reads like a hand-maintained index that will go stale. Replace it with <Collection collectionId="__all__" layout="column" showSummary /> …"
}
]
}
{
"error": {
"code": "FOLDER_NOT_FOUND",
"message": "Parent folder /docs/api does not exist. Create the folder in the editor first."
}
}
