bricks_create_page

Phase 4BeginnerComplexity: 3/10
Create a new WordPress page with Bricks editor mode

Overview

Create a new WordPress page or custom post type entry with the Bricks editor mode enabled. The page is created empty — use bricks_add_section afterward to add content. Returns the post ID, permalink, and Bricks editor URL.

Supports any registered post type (page, post, or custom post types like « portfolio », « team_member »). The page defaults to draft status so you can build content before publishing.

Key Features

Bricks Editor Auto-Enable
Automatically enables Bricks editor mode on the new page so it is ready for visual content building.
Custom Post Type Support
Works with any registered post type -- not just pages. Pass post_type to create portfolio items, team members, services, etc.
Hierarchical Pages
Set a parent page ID to create child pages for organized site structures like Services > Web Design.
Auto-Generated Slugs
If slug is omitted, WordPress automatically generates a URL-friendly slug from the title.

When to Use

You need to create a new page as part of Phase 4 (Build Pages)
You are setting up a multi-page website and need blank pages ready for content
You need to create a custom post type entry (e.g., portfolio, team member, service)
You want to create a page with a specific slug for SEO purposes
You need a child page under an existing parent for hierarchical content
Prerequisites
Design system must be set up first (Phase 2): colors, variables, global classes, components, and theme styles. Templates (header/footer) should be created (Phase 3) before creating pages. Always call bricks_list_pages first to check if the page already exists.

When NOT to Use

You want to duplicate an existing page with all its content (use bricks_clone_page instead)
The page already exists (use bricks_list_pages to check first)
You want to create a page AND add content in one call (create page first, then use bricks_add_section)
You need to create a blog post with ACF/meta data (use bricks_create_post for CPT entries with meta)

Parameters

5 Total Parameters1 Required4 Optional
titlestringREQUIRED
Page or post title. Used to generate the slug if slug is not provided.
slugstringoptional
URL slug (auto-generated from title if not provided). Use for SEO-friendly custom URLs.
statusstringoptional
Post status. Always start with draft and publish only after content is complete and validated.
Default: draft Values: draft, publish, pending, private
parentnumberoptional
Parent page ID for hierarchical post types. Creates a child page under the specified parent.
post_typestringoptional
Post type slug. Defaults to "page". Use for custom post types like "portfolio", "team_member", etc.
Default: page

Code Examples

Create a basic page

Create a new About page in draft status, then add a hero section to it.

JSON
// Step 1: Create the page
bricks_create_page({
  title: "About Us",
  slug: "about",
  status: "draft"
})
// Returns: { post_id: 42, ... }

// Step 2: Add content to the page
bricks_add_section({
  page_id: 42,
  section: {
    type: "section",
    children: [{
      type: "container",
      settings: { "_width": "1200px" },
      children: [
        { type: "heading", settings: { tag: "h1", text: "About Us" }, globalClasses: ["text-display"] }
      ]
    }]
  }
})
Response
{
  "post_id": 42,
  "title": "About Us",
  "status": "draft",
  "post_type": "page",
  "link": "https://example.com/?page_id=42",
  "edit_url": "https://example.com/wp-admin/post.php?post=42&action=edit",
  "bricks_edit_url": "https://example.com/?bricks=run&post_id=42"
}

Create a child page

Create a child page under an existing Services page.

JSON
bricks_create_page({
  title: "Web Design",
  slug: "web-design",
  status: "draft",
  parent: 50
})
Response
{
  "post_id": 55,
  "title": "Web Design",
  "status": "draft",
  "post_type": "page",
  "link": "https://example.com/services/web-design/"
}

Common Mistakes

Creating pages before the design system is set up
Always complete Phase 2 (colors, variables, classes, components, theme styles) before Phase 4 (page creation). Without a design system, you end up with inline styles everywhere.
Wrong
// Starting with page creation
bricks_create_page({ title: "Home" })
bricks_add_section({ ... inline styles ... })
Correct
// Phase 2 first
bricks_create_color({ name: "Primary", ... })
bricks_create_global_class({ name: "btn-primary", ... })
// Then Phase 4
bricks_create_page({ title: "Home" })
Publishing pages before content is complete
Always create pages as draft, add all content, validate with bricks_validate_page, then publish via bricks_update_page_status.
Wrong
bricks_create_page({
  title: "Contact",
  status: "publish"
})
// Empty page is now live!
Correct
bricks_create_page({
  title: "Contact",
  status: "draft"
})
// Add content, validate, then publish

Tips & Warnings

Tips & Warnings

Always draft first: Create pages with status « draft » and only publish after all content is added and validated. Empty published pages hurt SEO.

Check before creating: Run bricks_list_pages with a title search first to avoid creating duplicate pages.

Workflow order: Phase 1 (site context) → Phase 2 (design system) → Phase 3 (templates) → Phase 4 (bricks_create_page + bricks_add_section for each page).

Return Values

FieldTypeDescription
post_idnumberThe WordPress post ID of the newly created page. Use this ID with bricks_add_section and other tools.
titlestringThe title as stored in WordPress.
statusstringThe post status (draft, publish, etc.).
post_typestringThe post type of the created entry.
linkstringFrontend permalink URL.
edit_urlstringWordPress admin edit URL.
bricks_edit_urlstringBricks visual editor URL for the new page.

Related Tools

Technical Details

Tool ID
bricks_create_page
API Endpoint
/bricks-mcp/v1/pages
HTTP Method
POST
Namespace
pages-elements
Source File
pages/create.ts
Version
1.0
Min Bricks Version
1.9
Requires Auth
Yes

Changelog

v1.0
Initial release with custom post type support and parent page hierarchy.
20250101