Publish Page

Publish a page to make it publicly accessible on your domain. Publishing triggers static generation and CDN distribution.

Endpoint

POST /pages/:id/publish

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	The unique page ID

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer $PAGEGUN_API_KEY`

What Happens on Publish

Validation — PageGun checks the page has required fields (page_name, slug, subroute, type)
Static Generation — HTML is generated from your page config or markdown content
CDN Distribution — The generated page is pushed to the global CDN
Navigation Update — If the page is type docs, the docs navigation (nav.enc) is regenerated
Webhook Trigger — If configured, a page.published webhook event is sent

Prerequisites

Before publishing, ensure your page has:

A valid slug (URL-safe string)
A subroute (e.g., "blog", "docs", "pages")
A type that matches the content format
Content: config.sections for page type, markdown_content for article/docs type

Response

{
  "data": {
    "id": "page_xyz789",
    "status": "published",
    "published_at": "2024-01-21T09:00:00Z",
    "url": "https://yourdomain.com/blog/my-post"
  }
}

Response Fields

Field	Type	Description
`id`	string	The page ID
`status`	string	Always `"published"` on success
`published_at`	string	ISO 8601 timestamp of publication
`url`	string	The public URL where the page is accessible

Error Responses

Status	Code	Description
400	`validation_error`	Page is missing required fields (slug, subroute, type)
404	`not_found`	Page ID doesn't exist
409	`already_published`	Page is already published (re-publish to update)

Examples

Basic Publish

curl -X POST "https://api.pagegun.com/pages/page_xyz789/publish" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Create and Publish in One Flow

# Step 1: Create the page
PAGE_ID=$(curl -s -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_name": "Launch Announcement",
    "slug": "launch-announcement",
    "subroute": "blog",
    "type": "article",
    "project_id": "proj_abc123",
    "markdown_content": "# We just launched!\n\nExciting news..."
  }' | jq -r '.data.id')

# Step 2: Publish it
curl -X POST "https://api.pagegun.com/pages/$PAGE_ID/publish" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Re-publish After Update

After updating page content, you must re-publish to push changes live:

# Update content
curl -X PUT "https://api.pagegun.com/pages/page_xyz789" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown_content": "# Updated content\n\nNew version..."}'

# Re-publish to make changes live
curl -X POST "https://api.pagegun.com/pages/page_xyz789/publish" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY"

Important Notes

Updates require re-publish: Editing a published page does not automatically update the live version. You must call publish again.
Docs navigation: For docs type pages, publishing regenerates the navigation tree. Changing only project settings without publishing a page will not update navigation.
CDN propagation: Changes typically appear within seconds, but allow up to 60 seconds for global CDN propagation.