Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video
TrademarkTrademark
Ctrl k
Search…
Sign up
Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video

Create a Page

POST /api/v1/sites/{siteId}/pages — create a new draft MDX page at a path.
Updated 1mo ago
Delete a Page
Sponsored
Aveiro
aveiro.app
Sponsored
Aveiro
aveiro.app
TrademarkTrademark
AveiroBlogContact
© Aveiro. All rights reserved.
Built with Aveiro
In short
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
pathyesMDX path (for example /foo.mdx or /docs/bar.mdx). Normalized automatically.
contentnoMDX string. Defaults to a heading derived from the filename.
metadatanoPage metadata object (title, summary, tag, image, publishedAt, …)

Example (curl)

curl -s -X POST 'https://help.aveiro.app/api/v1/sites/SITE_ID/pages' \
  -H 'Authorization: Bearer av_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-overview-2026-07-08' \
  -d '{
    "path": "/guides/overview.mdx",
    "content": "# Overview

Draft content here.",
    "metadata": { "title": "Overview" }
  }'

Response

201 Created

Content dialect and recommendations

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.

Errors

HTTP
Code
When
400VALIDATION_ERRORMissing path or invalid JSON
403FORBIDDENMissing content:write or page limit reached
404FOLDER_NOT_FOUNDParent folder does not exist
409ALREADY_EXISTSA page already exists at this path
409IDEMPOTENCY_CONFLICTSame key, different body
422INVALID_MDXContent failed MDX validation

Related

  • Update a page
  • Delete a page
  • List pages
{
  "page": {
    "id": "new-content-uuid",
    "path": "/guides/overview.mdx",
    "title": "Overview",
    "dirty": true,
    "never_published": true,
    "updated_at": "2026-07-08T09:00:00.000000+00:00",
    "editor_url": "https://help.aveiro.app/en/ORG_ID/SITE_ID/edit?file=new-content-uuid",
    "content": "# Overview

Draft content here.",
    "metadata": { "title": "Overview" },
    "revision": "version-uuid"
  }
}
{
  "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."
  }
}