Create Page

Create a new page in your PageGun project. This is the core endpoint for building pages programmatically — whether you're creating landing pages, blog articles, documentation, or directory items.

Prerequisites

Before creating pages, ensure you have:

A valid API key with the format pgk_live_...
A project ID where the page will be created
Understanding of page types to choose the right type

Endpoint

POST https://api.pagegun.com/pages

Authentication

Include your API key in the Authorization header:

Authorization: Bearer pgk_live_your_api_key_here

Request Headers

Header	Required	Value	Description
`Authorization`	Yes	`Bearer pgk_live_...`	Your PageGun API key
`Content-Type`	Yes	`application/json`	JSON request body

Request Body Parameters

Required Parameters

Parameter	Type	Description	Example
`title`	`string`	Display name for the page (used in dashboard and `<title>` tag)	`"Product Features"`
`slug`	`string`	URL-friendly identifier (letters, numbers, hyphens only)	`"product-features"`
`subroute`	`string`	URL path prefix that groups related pages	`"pages"`, `"blog"`, `"docs"`
`type`	`string`	Page type: `page`, `article`, `docs`, `item`	`"page"`
`project_id`	`string`	Target project ID (starts with `proj_`)	`"proj_abc123xyz"`

Optional Parameters

Parameter	Type	Description	Example	Default
`description`	`string`	SEO meta description (max 160 chars recommended)	`"Discover our product features"`	`""`
`og_image_url`	`string`	Open Graph image URL for social sharing	`"https://cdn.example.com/og.jpg"`	`null`
`config`	`object`	JSON configuration for `page` and `item` types	See examples below	`{}`
`markdown_content`	`string`	Markdown content for `article` and `docs` types	`"# Hello World\n\nThis is my content"`	`""`

Content by Page Type

The content format depends on your chosen page type:

Page Type	Content Field	Format	Use Case
`page`	`config.sections`	JSON array of section objects	Landing pages, marketing pages
`article`	`markdown_content`	Markdown string	Blog posts, SEO content
`docs`	`markdown_content`	Markdown string	Documentation, help articles
`item`	`config`	JSON object with custom fields	Product directories, listings

Response Format

Success Response (201 Created)

{
  "data": {
    "id": "page_xyz789abc123",
    "title": "Product Features",
    "slug": "product-features",
    "subroute": "pages",
    "type": "page",
    "status": "draft",
    "url": "https://myproject.pagegun.io/pages/product-features",
    "project_id": "proj_abc123xyz",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "published_at": null
  }
}

Response Fields

Field	Type	Description
`id`	`string`	Unique page identifier (use for updates/publishing)
`url`	`string`	Full URL where the page will be accessible
`status`	`string`	Current status: `draft` or `published`
`published_at`	`string` or `null`	ISO timestamp of last publish (null if never published)

Complete Examples

1. Landing Page with Multiple Sections

Create a full landing page with hero, features, and call-to-action:

curl -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI Writing Tool",
    "slug": "ai-writing-tool",
    "subroute": "pages",
    "type": "page",
    "project_id": "proj_abc123xyz",
    "description": "The most powerful AI writing assistant for content creators and marketers.",
    "og_image_url": "https://cdn.mysite.com/ai-tool-og.jpg",
    "config": {
      "theme": "default",
      "sections": [
        {
          "type": "hero",
          "heading": "Write Better Content, 10x Faster",
          "description": "Our AI writing tool helps you create engaging content that converts. From blog posts to social media, get professional results in minutes.",
          "ctaText": "Start Writing Free",
          "ctaHref": "/signup",
          "heroImage": "https://cdn.mysite.com/hero-image.jpg"
        },
        {
          "type": "features",
          "heading": "Everything You Need to Create Amazing Content",
          "features": [
            {
              "title": "AI Blog Posts",
              "content": "Generate SEO-optimized blog posts that rank on Google and engage your audience.",
              "icon": "Edit"
            },
            {
              "title": "Social Media Copy",
              "content": "Create scroll-stopping posts for Twitter, LinkedIn, Facebook, and Instagram.",
              "icon": "Share"
            },
            {
              "title": "Email Campaigns", 
              "content": "Write compelling email sequences that nurture leads and drive conversions.",
              "icon": "Mail"
            }
          ]
        },
        {
          "type": "cta",
          "heading": "Ready to Transform Your Content?",
          "description": "Join 10,000+ creators using our AI writing tool",
          "ctaText": "Get Started Free",
          "ctaHref": "/signup"
        }
      ]
    }
  }'

Response:

{
  "data": {
    "id": "page_ai_tool_xyz789",
    "title": "AI Writing Tool",
    "slug": "ai-writing-tool", 
    "url": "https://myproject.pagegun.io/pages/ai-writing-tool",
    "status": "draft"
  }
}

2. Blog Article with Markdown

Create an SEO-optimized blog post:

curl -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "10 AI Writing Tips for Better Content",
    "slug": "ai-writing-tips-better-content",
    "subroute": "blog",
    "type": "article",
    "project_id": "proj_abc123xyz",
    "description": "Learn 10 proven AI writing techniques to create compelling content that engages readers and drives conversions.",
    "og_image_url": "https://cdn.mysite.com/ai-tips-og.jpg",
    "markdown_content": "# 10 AI Writing Tips for Better Content\n\nArtificial intelligence is revolutionizing how we create content. Whether you'\''re writing blog posts, social media updates, or email campaigns, AI can help you work faster and produce better results.\n\n## 1. Start with Clear Prompts\n\nThe quality of your AI output depends heavily on the quality of your input. Instead of vague requests like \"write about marketing,\" try specific prompts:\n\n- ❌ Bad: \"Write about social media\"\n- ✅ Good: \"Write a 500-word guide on Instagram Story best practices for B2B companies\"\n\n## 2. Provide Context and Examples\n\nAI works best when you give it context about your audience, brand voice, and goals...\n\n[Content continues...]"
  }'

3. Documentation Page

Create a help article with structured content:

curl -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with the PageGun API",
    "slug": "getting-started",
    "subroute": "docs",
    "type": "docs",
    "project_id": "proj_abc123xyz",
    "description": "Learn how to get started with the PageGun API in under 10 minutes.",
    "markdown_content": "# Getting Started with the PageGun API\n\nWelcome to PageGun! This guide will walk you through everything you need to know to start building pages programmatically.\n\n## Prerequisites\n\nBefore you begin, make sure you have:\n\n- [ ] A PageGun account ([sign up free](https://pagegun.com/signup))\n- [ ] Your API key from the dashboard\n- [ ] A project to work with\n\n## Your First API Call\n\nLet'\''s test your setup with a simple request:\n\n```bash\ncurl -X GET \"https://api.pagegun.com/projects\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n✅ **Success?** You'\''re ready to start building!\n❌ **Error?** Check your API key format and try again."
  }'

4. Directory Item

Create a product listing for a directory site:

curl -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PageGun - API-First Website Builder",
    "slug": "pagegun",
    "subroute": "tools",
    "type": "item",
    "project_id": "proj_abc123xyz",
    "description": "Build websites programmatically with PageGun'\''s powerful REST API. Perfect for developers and AI agents.",
    "config": {
      "category": "Website Builders",
      "price": "$29/month",
      "badge": "Developer Friendly",
      "rating": 4.8,
      "website": "https://pagegun.com",
      "features": [
        "REST API for all operations",
        "Pre-built sections and themes",
        "SEO optimization built-in",
        "Custom domain support"
      ],
      "description": "PageGun is the first website builder designed specifically for programmatic use. Whether you'\''re building with code or AI, PageGun makes it easy to create professional websites at scale."
    }
  }'

Error Responses

400 Bad Request - Validation Error

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Invalid request parameters"
}

401 Unauthorized - Invalid API Key

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}

404 Not Found - Project Doesn't Exist

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Project not found or you don't have access"
}

409 Conflict - Slug Already Exists

{
  "statusCode": 400,
  "name": "conflict",
  "message": "A page with this slug already exists in this subroute"
}

Next Steps

After creating your page:

Preview it at the returned URL (it's in draft status)
Publish it to make it live
Update content as needed
Add more pages to build your site

Common Patterns

Batch Page Creation

Creating multiple pages? Consider these patterns:

# Create multiple blog posts from an array
for title in "Post 1" "Post 2" "Post 3"; do
  curl -X POST "https://api.pagegun.com/pages" \
    -H "Authorization: Bearer $PAGEGUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"title\":\"$title\", ...}"
done

AI-Generated Content

Perfect for AI agents creating content:

// Example: AI agent creating pages
const prompt = "Create a landing page for a SaaS tool";
const content = await ai.generate(prompt);

const response = await fetch('https://api.pagegun.com/pages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PAGEGUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: content.title,
    slug: content.slug,
    type: 'page',
    config: content.sections
  })
});

Ready to build more? Check out our complete guides and section references!