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.
Page content is Aveiro-dialect MDX: linear editorial structure (markdown headings and prose) with registered components only — unregistered JSX tags are rejected with 422 INVALID_MDX. Agents connected over MCP should call the aveiro_authoring_guide tool before their first write; it returns the component catalog and the strict contracts for LineChart, OgCard (outbound link cards), Collection (internal page lists), 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."
}
}
