# Tool Name: `page-create`

**Module**: Channels > Pages  
**Version**: 1.0.0  
**Status**: Stable

## Overview

Creates a new layout page within a site. Pages define the routes/paths that visitors can access on the site domain (e.g., /home, /about, /products). Each page represents a URL endpoint in your site structure.

## Use Cases

- Create home page (/) for site entry point
- Add content pages (about, contact, services)
- Build product catalog pages (/products)
- Set up nested page hierarchies (/products/category/item)
- Create dynamic content pages linked to Content entries

## Parameters

### Required Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| platformSlug | string | Platform identifier from ~/.platforms.json | "production" |
| siteId | number | The ID of the site where page will be created | 123 |
| name | string | Display name of the page (shown in admin) | "Home Page" |
| path | string | URL path for the page (must start with /) | "/" or "/about" |

### Optional Parameters

| Parameter | Type | Default | Description | Example |
|-----------|------|---------|-------------|---------|
| parent_uuid | string\|null | null | UUID of parent page for nested structure | "abc-123-def" |
| page_type | string | "default" | Type of page template to use | "home", "default" |
| grid_type | string\|null | null | Grid layout type for the page | "standard" |
| private | boolean | false | Whether the page requires authentication | true |
| has_router | boolean | false | Enable routing functionality for dynamic paths | true |
| restriction_enabled | boolean | false | Enable access restrictions based on user roles | true |
| excerpt | string\|null | null | Short description for SEO and listings | "Welcome page" |
| content_type_id | number\|null | null | Link to Content type for dynamic content | 45 |
| origination_uuid | string\|null | null | UUID of original page if this is a clone | "xyz-789" |

## Response

### Success Response

```json
{
  "id": 456,
  "uuid": "page-uuid-123",
  "name": "Home Page",
  "path": "/",
  "page_type": "home",
  "grid_type": null,
  "private": false,
  "has_router": false,
  "restriction_enabled": false,
  "excerpt": "Welcome to our site",
  "content_type_id": null,
  "parent_uuid": null,
  "origination_uuid": null,
  "created_at": "2025-01-09T10:00:00Z",
  "updated_at": "2025-01-09T10:00:00Z",
  "status": "draft",
  "workflow_id": 789,
  "site_id": 123
}
```

### Error Responses

**422 Validation Error - Duplicate Path**
```json
{
  "error": "Validation failed",
  "details": {
    "path": ["has already been taken"]
  }
}
```

**404 Not Found - Invalid Site**
```json
{
  "error": "Site not found",
  "site_id": 999
}
```

## Examples

### Example 1: Create Home Page

Create the main entry point for your site:

```json
{
  "platformSlug": "production",
  "siteId": 123,
  "name": "Home",
  "path": "/",
  "page_type": "home",
  "excerpt": "Welcome to our website"
}
```

**Result**: Creates home page accessible at site root URL.

### Example 2: Create About Page

Add a standard content page:

```json
{
  "platformSlug": "production",
  "siteId": 123,
  "name": "About Us",
  "path": "/about",
  "page_type": "default",
  "excerpt": "Learn more about our company"
}
```

**Result**: Page accessible at `https://yoursite.com/about`

### Example 3: Create Nested Product Detail Page

Build hierarchical page structure:

```json
{
  "platformSlug": "production",
  "siteId": 123,
  "name": "Product Details",
  "path": "/products/details",
  "parent_uuid": "products-page-uuid",
  "page_type": "default"
}
```

**Result**: Nested page at `https://yoursite.com/products/details`

### Example 4: Create Private Customer Portal Page

Page requiring authentication:

```json
{
  "platformSlug": "production",
  "siteId": 123,
  "name": "My Account",
  "path": "/account",
  "page_type": "default",
  "private": true,
  "restriction_enabled": true
}
```

**Result**: Page only accessible to logged-in users.

### Example 5: Dynamic Content Page

Page connected to Content entries:

```json
{
  "platformSlug": "production",
  "siteId": 123,
  "name": "Blog Post",
  "path": "/blog/:slug",
  "page_type": "entry",
  "has_router": true,
  "content_type_id": 45
}
```

**Result**: Dynamic page that displays Content entries from type 45.

## Related Tools

- `page-list` - List all pages in site to verify creation
- `page-get` - Retrieve page details including content
- `page-update` - Modify page properties and content after creation
- `page-delete` - Remove pages when no longer needed
- `site-get` - Get site details to verify siteId
- `template-create` - Create snippets to use in page content

## Common Patterns

### Pattern 1: Basic Site Structure Setup

```
1. page-create (path: "/") → home page
2. page-create (path: "/about") → about page  
3. page-create (path: "/services") → services page
4. page-create (path: "/contact") → contact page
5. page-list → verify all pages created
```

### Pattern 2: E-Commerce Page Structure

```
1. page-create (path: "/") → home
2. page-create (path: "/products") → product catalog
3. page-create (path: "/products/:slug", has_router: true) → product details
4. page-create (path: "/cart") → shopping cart
5. page-create (path: "/checkout", private: true) → checkout
6. page-update → add content with product snippets
```

### Pattern 3: Blog Structure with Dynamic Content

```
1. page-create (path: "/") → home
2. page-create (path: "/blog") → blog list
3. page-create (path: "/blog/:slug", has_router: true, content_type_id: X) → blog post
4. page-create (path: "/blog/category/:category") → category pages
5. template-create (type: "snippet") → blog post card snippet
6. page-update → add blog post cards to list page
```

### Pattern 4: Multi-Language Site

```
1. page-create (path: "/en") → English home
2. page-create (path: "/es") → Spanish home
3. page-create (path: "/en/about") → English about
4. page-create (path: "/es/acerca") → Spanish about
5. global-variable-create (scope: "site") → language switcher config
```

## Troubleshooting

### Issue: "Path has already been taken"

**Cause**: Another page in the same site uses this exact path  
**Solution**:
- Use `page-list` to see all existing paths
- Choose a different unique path
- Delete the existing page if it's no longer needed
- Check for case-sensitivity (paths are case-sensitive)

### Issue: "Parent UUID not found"

**Cause**: The parent_uuid doesn't exist or belongs to different site  
**Solution**:
- Use `page-list` to get valid parent page UUIDs
- Set parent_uuid to null for top-level pages
- Ensure parent page exists before creating child

### Issue: "Invalid path format"

**Cause**: Path doesn't start with "/" or contains invalid characters  
**Solution**:
- Always start paths with "/" : `/about` ✅ not `about` ❌
- Use lowercase and hyphens: `/my-page` ✅
- Avoid spaces and special chars: `/my page` ❌
- Use URL-safe characters only

### Issue: "Content type not found"

**Cause**: content_type_id doesn't exist in the platform  
**Solution**:
- Use `type-list` to get valid content type IDs
- Set content_type_id to null if not using dynamic content
- Create content type first using `type-create` if needed

### Issue: Page created but shows 404

**Cause**: Page is in draft status and not published  
**Solution**:
- Pages are created as drafts by default
- Must be published through Modyo admin UI or API
- Check page status with `page-get`

## Best Practices

1. **Plan URL structure** - Map out all pages before creating
2. **Use semantic paths** - `/products/shoes` is better than `/p1`
3. **Start with home page** - Create "/" path first as site entry point
4. **Hierarchical organization** - Use parent_uuid for logical structure
5. **Consistent naming** - Match page name to path (`"About Us"` → `/about-us`)
6. **Add excerpts** - Improves SEO and content organization
7. **Test paths** - Verify no conflicts before creating many pages

## Permissions Required

- Valid Admin API access token
- Channels module enabled
- Page creation permissions for the site
- Site must exist and be accessible

## Rate Limits

- **Standard**: 50 page creations per minute per site
- **Recommended**: Create pages in batches of 10-20
- **Large sites**: Consider pagination when creating 100+ pages

## Important Notes

- Page creation sets status to **"draft"** (not published)
- Pages require **publishing** through Modyo admin or API to be public
- **Paths are case-sensitive**: `/About` and `/about` are different
- **Paths must be unique** within a site
- Path cannot be changed after creation (requires page recreation)
- Router pages (has_router: true) enable **dynamic URL parameters** like `:slug`
- Private pages require site to have **realm authentication** enabled
- Parent-child relationships create **breadcrumb navigation**
- Empty pages (no content) will display **blank** until content added

## See Also

### Documentation
- [Pages Management Guide](../../guides/pages-management.md)
- [Page Content Best Practices](../../guides/page-content.md)
- [Dynamic Pages and Routing](../../guides/dynamic-pages.md)

### Official Modyo Documentation
- [Modyo Pages Docs](https://docs.modyo.com/en/platform/channels/pages.html)
- [API Reference](https://api.modyo.com/swagger#/layout_pages/post_sites__site_id__layout_pages)
- [Page Templates](https://docs.modyo.com/en/platform/channels/templates.html)

### Related Tool Documentation
- [page-update](./page-update.md) - Add content and update pages
- [page-list](./page-list.md) - List and find pages
- [site-create](../sites/site-create.md) - Create site first
- [template-create](../templates/template-create.md) - Create reusable snippets