---
title: "Create a page"
method: POST
path: "/api/v2/pages"
tags: ["Pages"]
---

# Create a page

`POST /api/v2/pages`

## Request

- Base URL: `https://yournation.nationbuilder.com`
- URL: `https://yournation.nationbuilder.com/api/v2/pages`
- Auth: HTTP bearer

Creates a page from given data

## Request body

- PageCreateRequest: The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes.
  - `data` object, required
    - `type` 'pages', required: The JSON:API resource type of the resource being created.
    - `attributes` PageReadWriteAttributes: The attributes of a page that can be both read and written.
      - `author_id` string, nullable: The author of the page.
      - `excerpt` string, nullable: Longer page description used for search engine optimization.
      - `external_id` string, nullable: Optional reference for pages imported from an external service.
      - `headline` string, nullable: This is a header rendered above the page content.
      - `name` string: The name of the page.
      - `page_type_name` 'Basic': The name of the type of page to create. Must be 'Basic' for this endpoint.
      - `parent_id` string, nullable: The parent page ID (null for top-level pages).
      - `permission_level` 'anyone' | 'logged_in' | 'members' | 'control_panel_users' | 'admins': The permission level required to view this page. Options: "anyone" (public access), "logged_in" (any authenticated user), "members" (site members only), "control_panel_users" (users with control panel access), "admins" (site administrators only).
      - `site_id` string: The site this page belongs to.
      - `slug` string: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug]
      - `status` 'archived' | 'deleted' | 'expired' | 'hidden' | 'published' | 'rule_violated' | 'unlisted': The page status - describing the visibility of the page.
      - `title` string: Brief page description seen on search engines.

## Response `201`

The newly created page.

- PageShowResponse: The JSON:API top-level document shape for responses returning a single resource under the data member.
  - `data` object, required: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
    - `id` string, required: Unique identifier of the resource.
    - `type` 'pages', required: The JSON:API resource type.
    - `attributes` object: The read-only attributes of a page.
      - `author_id` string, nullable: The author of the page.
      - `excerpt` string, nullable: Longer page description used for search engine optimization.
      - `external_id` string, nullable: Optional reference for pages imported from an external service.
      - `headline` string, nullable: This is a header rendered above the page content.
      - `name` string: The name of the page.
      - `page_type_name` 'Basic': The name of the type of page to create. Must be 'Basic' for this endpoint.
      - `parent_id` string, nullable: The parent page ID (null for top-level pages).
      - `permission_level` 'anyone' | 'logged_in' | 'members' | 'control_panel_users' | 'admins': The permission level required to view this page. Options: "anyone" (public access), "logged_in" (any authenticated user), "members" (site members only), "control_panel_users" (users with control panel access), "admins" (site administrators only).
      - `site_id` string: The site this page belongs to.
      - `slug` string: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug]
      - `status` 'archived' | 'deleted' | 'expired' | 'hidden' | 'published' | 'rule_violated' | 'unlisted': The page status - describing the visibility of the page.
      - `title` string: Brief page description seen on search engines.
      - `ancestors_permission_level` string, nullable: The most restrictive permission level inherited from parent pages in the hierarchy. Returns null if the page has no parent.
      - `effective_permission_level` string: The actual permission level that will be enforced for this page. This is the most restrictive level between the page itself and its ancestors, ensuring users need the highest required access level to view the page.
      - `parent_slug` string, nullable: The parent page slug (null for top-level pages).
      - `published_at` string, date-time, nullable: When this page was published.
      - `url_path` string: URL to the page.
  - `included` Resource[]: Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type.
    - `id` string, required: Unique identifier of the resource.
    - `type` string, required: The JSON:API resource type.
    - `attributes` object: The attributes of the resource, as documented for its resource type.
    - `relationships` object: References from this resource to other resources in the document.
  - `meta` object: Non-standard information about the document. Empty unless the endpoint has metadata to convey.

## Other responses

- `400`: The request body or query parameters are invalid, such as an unknown attribute, filter, filter operator, sort field, or sideload.
- `401`: The access token is missing, expired, or not authorized to access this resource.
- `422`: Model validations failed for the resource being created or updated. Unlike this API's other errors, validation failures are returned as a JSON:API errors document locating each invalid field.
- `429`: The access token has exceeded its request quota for the current rate-limit window.

## Changes

- **2026-11-05** `d5c88ca497ac`: 4 breaking, 1 warning, 7 info
  - added `#/components/schemas/create_request_document, subschema #2` to the request body `allOf` list
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `201`
  - removed the required property `data` from the response with the `201` status
  - …8 more
- **2026-02-14** `31995b0a1e61`: 4 breaking, 7 info
  - the request property `data/attributes/name` became not nullable
  - the request property `data/attributes/page_type_name` became not nullable
  - the request property `data/attributes/slug` became not nullable
  - the request property `data/attributes/title` became not nullable
  - …7 more

[Operation history](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/changes/api/v2/pages/post.md)

---

[API](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api.md) - [All operations](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nationbuilder/apis/nationbuilder-v2-api/revisions/d5c88ca497ac?raw)