Publish pages

A page is a lightweight document — a brand guide, a one-off brief — built from structured blocks rather than freeform Markdown. Scopes needed: pages:write to create, append and publish; pages:read to read it back.

1. Create a page

curl -X POST https://us.api.brault.app/v1/pages \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-9999-4c1a-9c1e-page-create" \
  -d '{
    "name": "Q4 Brand Brief",
    "folder_id": "<folder_id>",
    "blocks": [
      { "type": "heading", "level": 1, "text": "Q4 Brand Brief" },
      { "type": "paragraph", "text": "Everything the extended team needs for this quarter’s campaign." },
      { "type": "bullet_list", "items": ["Primary palette locked", "New product shots due Nov 1"] }
    ]
  }'

The response is the page detail, including the stored content:

{
  "object": "page",
  "id": "<page_id>",
  "name": "Q4 Brand Brief",
  "library_id": "<library_id>",
  "folder_id": "<folder_id>",
  "published": false,
  "published_at": null,
  "published_by_id": null,
  "public_url": null,
  "created_at": "2026-09-06T10:00:00.000Z",
  "updated_at": "2026-09-06T10:00:00.000Z",
  "created_by_id": "<user_id>",
  "trashed_at": null,
  "content": { "format": "json", "json": { "type": "doc", "content": [ /* … */ ] } }
}

Available block types: paragraph, heading (levels 1–3), bullet_list, ordered_list, code_block, quote, divider. There's no inline formatting (bold, links), no images and no nesting yet — see the Pages reference for exact field limits.

2. Append more content later

curl -X POST https://us.api.brault.app/v1/pages/<page_id>/blocks \
  -H "Authorization: Bearer $BRAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-aaaa-4c1a-9c1e-page-append" \
  -d '{"blocks": [{"type": "paragraph", "text": "Update: shots pushed to Nov 8."}]}'

Always send an Idempotency-Key here — unlike most /v1 writes, appending blocks is not naturally idempotent: a blind retry appends the same paragraph twice.

3. Publish it

curl -X POST https://us.api.brault.app/v1/pages/<page_id>/publish \
  -H "Authorization: Bearer $BRAULT_API_KEY"

The response's public_url (https://brault.app/site/<page_id>) is now reachable by anyone who has the link — no account required. POST …/unpublish withdraws it again.

Reading it back

curl "https://us.api.brault.app/v1/pages/<page_id>?format=markdown" \
  -H "Authorization: Bearer $BRAULT_API_KEY"

format=markdown renders the same content as plain-text Markdown for the block types above — useful for feeding a page into something that expects text rather than the raw ProseMirror JSON. It never carries image sources, and it does not escape Markdown special characters in your prose, so treat it as a rendering convenience rather than a lossless export.