NationBuilder Pages API

openapi: 3.2.0
info:
  title: NationBuilder V2 Pages API
  version: '2.0'
  description: 'The NationBuilder V2 API is a JSON:API-compliant API for managing NationBuilder

    resources such as people, donations, events, and lists.'
servers:
- url: https://{subdomain}.nationbuilder.com
  variables:
    subdomain:
      default: yournation
      description: Your NationBuilder nation slug
security:
- BearerAuth: []
tags:
- name: Pages
  x-tag-expanded: false
  description: Pages are published on your site. Each page type offers different features, you can view them here.
paths:
  /api/v2/pages:
    parameters:
    - $ref: '#/components/parameters/page_index_include'
    - $ref: '#/components/parameters/page_sparse_fields'
    post:
      summary: Create a page
      tags:
      - Pages
      description: Creates a page from given data
      operationId: createPage
      responses:
        '201':
          description: The newly created page.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/page_show_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '422':
          $ref: '#/components/responses/unprocessable'
        '429':
          $ref: '#/components/responses/rate_limited'
      requestBody:
        $ref: '#/components/requestBodies/page_create_request_body'
    get:
      summary: List all pages in a nation
      tags:
      - Pages
      description: Lists all pages
      operationId: listPages
      parameters:
      - $ref: '#/components/parameters/pagination_number'
      - $ref: '#/components/parameters/pagination_size'
      responses:
        '200':
          description: A page of matching pages.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/page_index_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '429':
          $ref: '#/components/responses/rate_limited'
  /api/v2/pages/{id}:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/page_show_include'
    - $ref: '#/components/parameters/page_sparse_fields'
    get:
      summary: Show page with provided ID
      tags:
      - Pages
      description: Returns the JSON:API resource object for a single page.
      operationId: showPage
      responses:
        '200':
          description: The requested page.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/page_show_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
    patch:
      summary: Update an existing page
      tags:
      - Pages
      description: Updates an existing page
      operationId: updatePage
      parameters:
      - $ref: '#/components/parameters/page_show_include'
      responses:
        '200':
          description: The updated page.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/page_show_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/unprocessable'
        '429':
          $ref: '#/components/responses/rate_limited'
      requestBody:
        $ref: '#/components/requestBodies/page_update_request_body'
    delete:
      summary: Delete page with provided ID
      tags:
      - Pages
      description: Permanently removes the page that matches the given ID.
      operationId: deletePage
      responses:
        '200':
          description: Confirmation that the page was deleted.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/delete_document'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
components:
  schemas:
    page_sideload_values:
      description: Relationship names that can be sideloaded with the include query parameter on page endpoints.
      type: string
      enum:
      - membership_types
      - parent
      - site
    index_document:
      description: The JSON:API top-level document shape for paginated collection responses, with resource objects under data and pagination links.
      type: object
      required:
      - data
      properties:
        data:
          type: array
          description: The page of resource objects for this collection; each resource binds its concrete item schema here via allOf composition.
        links:
          $ref: '#/components/schemas/pagination_links'
        included:
          $ref: '#/components/schemas/included'
        meta:
          type: object
          description: Non-standard information about the document, such as requested statistics. Empty unless the endpoint has metadata to convey.
    page_read_only_attributes:
      description: The read-only attributes of a page.
      type: object
      properties:
        ancestors_permission_level:
          type:
          - string
          - 'null'
          examples:
          - members
          description: The most restrictive permission level inherited from parent pages in the hierarchy. Returns null if the page has no parent.
        effective_permission_level:
          type: string
          examples:
          - control_panel_users
          description: 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:
          type:
          - string
          - 'null'
          examples:
          - blog
          description: The parent page slug (null for top-level pages).
        published_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: When this page was published.
        url_path:
          type: string
          examples:
          - /your-slug
          description: URL to the page.
    validation_error_document:
      description: The JSON:API errors document returned with status 422 when model validations fail on create or update. Unlike this API's flat 4xx error bodies, validation failures follow the JSON:API errors format.
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/validation_error'
    page_update_request:
      description: The request body for updating an existing page.
      allOf:
      - $ref: '#/components/schemas/update_request_document'
      - type: object
        properties:
          data:
            type: object
            properties:
              id:
                type: string
                examples:
                - '1'
              type:
                const: pages
                examples:
                - pages
              attributes:
                $ref: '#/components/schemas/page_read_write_attributes'
    page_show_response:
      description: A JSON:API response containing a single page.
      allOf:
      - $ref: '#/components/schemas/show_document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/page_response_data'
    resource_identifier:
      description: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
      type: object
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: Unique identifier of the resource.
          examples:
          - '1'
        type:
          type: string
          description: The JSON:API resource type.
    page_read_write_attributes:
      description: The attributes of a page that can be both read and written.
      type: object
      properties:
        author_id:
          type:
          - string
          - 'null'
          examples:
          - '1'
          description: The author of the page.
        excerpt:
          type:
          - string
          - 'null'
          examples:
          - Page excerpt...
          description: Longer page description used for search engine optimization.
        external_id:
          type:
          - string
          - 'null'
          examples:
          - abc
          description: Optional reference for pages imported from an external service.
        headline:
          type:
          - string
          - 'null'
          examples:
          - Page headline
          description: This is a header rendered above the page content.
        name:
          type: string
          examples:
          - Page Name
          description: The name of the page.
        page_type_name:
          type: string
          enum:
          - Basic
          examples:
          - Basic
          description: The name of the type of page to create. Must be 'Basic' for this endpoint.
        parent_id:
          type:
          - string
          - 'null'
          examples:
          - '1'
          description: The parent page ID (null for top-level pages).
        permission_level:
          type: string
          enum:
          - anyone
          - logged_in
          - members
          - control_panel_users
          - admins
          examples:
          - anyone
          description: '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:
          type: string
          examples:
          - '1'
          description: The site this page belongs to.
        slug:
          type: string
          examples:
          - your-slug
          description: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug]
        status:
          type: string
          enum:
          - archived
          - deleted
          - expired
          - hidden
          - published
          - rule_violated
          - unlisted
          examples:
          - unlisted
          description: The page status - describing the visibility of the page.
        title:
          type: string
          examples:
          - Page Title
          description: Brief page description seen on search engines.
    delete_document:
      examples:
      - meta: {}
      description: The successful destroy response, an empty JSON:API meta-only document returned with status 200 (rather than JSON:API's commonly used 204 No Content).
      type: object
      required:
      - meta
      additionalProperties: false
      properties:
        meta:
          examples:
          - {}
          type: object
          properties: {}
    error_response:
      description: The error body returned for 4xx and 5xx responses, with a machine-readable code and a human-readable message. Some errors include additional detail members alongside these two. The exception is 422 validation failures, which are returned as JSON:API errors documents instead.
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code identifying the failure.
          examples:
          - not_found
        message:
          type: string
          description: Human-readable explanation of the failure.
          examples:
          - Record not found
    pagination_links:
      description: JSON:API pagination links for the pages of a collection. A key whose page is unavailable, or that the server's pagination strategy does not provide, is omitted or null.
      type: object
      properties:
        self:
          type: string
          description: Link to the current page.
          examples:
          - /articles?page[number]=2
        first:
          type:
          - string
          - 'null'
          description: Link to the first page.
          examples:
          - /articles?page[number]=1
        last:
          type:
          - string
          - 'null'
          description: Link to the last page.
          examples:
          - /articles?page[number]=5
        prev:
          type:
          - string
          - 'null'
          description: Link to the previous page.
          examples:
          - /articles?page[number]=1
        next:
          type:
          - string
          - 'null'
          description: Link to the next page.
          examples:
          - /articles?page[number]=3
    rate_limited_response:
      description: The body returned by the rate limiter when an access token exceeds its request quota.
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable explanation of the rate limit.
          examples:
          - You have made too many requests. Please try again later.
    update_request_document:
      description: The JSON:API top-level document shape for update requests, whose data member identifies the resource by type and id and carries the changed attributes.
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          - id
          properties:
            id:
              type: string
              description: The ID of the resource being updated.
            type:
              type: string
              description: The JSON:API resource type of the resource being updated.
    included:
      description: Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type.
      type: array
      items:
        $ref: '#/components/schemas/resource'
    page_create_request:
      description: The request body for creating a new page.
      allOf:
      - $ref: '#/components/schemas/create_request_document'
      - type: object
        properties:
          data:
            type: object
            properties:
              type:
                const: pages
                examples:
                - pages
              attributes:
                $ref: '#/components/schemas/page_read_write_attributes'
    show_document:
      description: The JSON:API top-level document shape for responses returning a single resource under the data member.
      type: object
      required:
      - data
      properties:
        data:
          type: object
          description: The primary resource object; each resource binds its concrete schema here via allOf composition.
        included:
          $ref: '#/components/schemas/included'
        meta:
          type: object
          description: Non-standard information about the document. Empty unless the endpoint has metadata to convey.
    page_field_values:
      description: Readable page attribute names selectable with sparse fieldsets (fields[pages]).
      type: string
      enum:
      - ancestors_permission_level
      - author_id
      - effective_permission_level
      - excerpt
      - external_id
      - headline
      - name
      - page_type_name
      - parent_id
      - parent_slug
      - permission_level
      - published_at
      - site_id
      - slug
      - status
      - title
      - url_path
    resource:
      description: A generic JSON:API resource object. Resources sideloaded in a document's included member use this shape; their attributes are those of the resource type named in the type member.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          attributes:
            type: object
            description: The attributes of the resource, as documented for its resource type.
          relationships:
            type: object
            description: References from this resource to other resources in the document.
    page_index_response:
      description: A paginated JSON:API response containing a list of pages.
      allOf:
      - $ref: '#/components/schemas/index_document'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/page_response_data'
    page_response_data:
      description: The JSON:API resource object representing a page.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          type:
            const: pages
            examples:
            - pages
          attributes:
            allOf:
            - $ref: '#/components/schemas/page_read_write_attributes'
            - $ref: '#/components/schemas/page_read_only_attributes'
    create_request_document:
      description: The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes.
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - type
          properties:
            type:
              type: string
              description: The JSON:API resource type of the resource being created.
    validation_error:
      description: A single JSON:API error object describing a validation failure, locating the invalid field via source.pointer and carrying the model-level attribute, message, and code under meta.
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          examples:
          - unprocessable_entity
        status:
          type: string
          description: The HTTP status code, as a string.
          examples:
          - '422'
        title:
          type: string
          description: Short human-readable summary of the error type.
          examples:
          - Validation Error
        detail:
          type: string
          description: Human-readable explanation specific to this failure.
          examples:
          - Email 'not-an-email' should look like an email address
        source:
          type: object
          properties:
            pointer:
              type: string
              description: JSON Pointer to the request document member the error relates to.
              examples:
              - /data/attributes/email
        meta:
          type: object
          description: The underlying model validation error, including the attribute name, message, and code. Errors on sideposted resources nest these members under a relationship key.
          properties:
            attribute:
              type: string
              description: The attribute that failed validation.
            message:
              type: string
              description: The validation failure message.
            code:
              type: string
              description: The validation failure code.
  headers:
    RateLimit-Reset:
      description: Unix timestamp (in seconds) at which the current rate-limit window resets.
      schema:
        type: string
        examples:
        - '1719964810'
      examples: {}
    RateLimit-Remaining:
      description: Number of requests remaining for the current access token in the current rate-limit window.
      schema:
        type: string
        examples:
        - '249'
      examples: {}
    Retry-After:
      description: Number of seconds to wait before retrying. Sent with 429 responses.
      schema:
        type: string
        examples:
        - '10'
      examples: {}
    RateLimit-Limit:
      description: Maximum number of requests allowed for the current access token per rate-limit window (10 seconds).
      schema:
        type: string
        examples:
        - '250'
      examples: {}
  responses:
    not_found:
      description: No resource exists with the provided ID.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          example:
            code: not_found
            message: Record not found
          schema:
            $ref: '#/components/schemas/error_response'
    unauthorized:
      description: The access token is missing, expired, or not authorized to access this resource.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          example:
            code: unauthorized
            message: You are not authorized to access this content. Your access token may be missing. The resource owner also may not have a permission level sufficient to grant access.
          schema:
            $ref: '#/components/schemas/error_response'
    rate_limited:
      description: The access token has exceeded its request quota for the current rate-limit window.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          example:
            message: You have made too many requests. Please try again later.
          schema:
            $ref: '#/components/schemas/rate_limited_response'
    bad_request:
      description: The request body or query parameters are invalid, such as an unknown attribute, filter, filter operator, sort field, or sideload.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          example:
            code: bad_request
            message: Tried to filter on attribute :bogus, but could not find an attribute with that name.
          schema:
            $ref: '#/components/schemas/error_response'
    unprocessable:
      description: 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.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/vnd.api+json:
          example:
            errors:
            - code: unprocessable_entity
              status: '422'
              title: Validation Error
              detail: Email 'not-an-email' should look like an email address
              source:
                pointer: /data/attributes/email
              meta:
                attribute: email
                message: '''not-an-email'' should look like an email address'
          schema:
            $ref: '#/components/schemas/validation_error_document'
  requestBodies:
    page_update_request_body:
      description: The attributes to update on the existing page.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/page_update_request'
        application/json:
          schema:
            $ref: '#/components/schemas/page_update_request'
    page_create_request_body:
      description: The page to create.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/page_create_request'
        application/json:
          schema:
            $ref: '#/components/schemas/page_create_request'
  parameters:
    page_show_include:
      name: include
      in: query
      description: 'Comma-delimited list of sideloaded resources to include as part of the page response.

        See guidance [here](https://support.nationbuilder.com/en/articles/9899245-api-v2-walkthrough#h_2d5333adab) about

        sideloading large numbers of resources and pagination.

        '
      schema:
        type: array
        default: []
        uniqueItems: true
        items:
          $ref: '#/components/schemas/page_sideload_values'
      required: false
      style: form
      explode: false
    id:
      name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    pagination_number:
      name: page[number]
      description: Page number to list (starting at 1)
      in: query
      required: false
      schema:
        type: string
        default: '1'
    pagination_size:
      name: page[size]
      description: 'Number of results to display per page (default: 20, max: 100, min: 1)'
      in: query
      required: false
      schema:
        type: string
        default: '20'
    page_index_include:
      name: include
      in: query
      description: 'Comma-delimited list of sideloaded resources to include as part of the page index response.

        See guidance [here](https://support.nationbuilder.com/en/articles/9899245-api-v2-walkthrough#h_2d5333adab) about

        sideloading large numbers of resources and pagination.

        '
      schema:
        type: array
        default: []
        uniqueItems: true
        items:
          $ref: '#/components/schemas/page_sideload_values'
      required: false
      style: form
      explode: false
    page_sparse_fields:
      name: fields[pages]
      in: query
      required: false
      description: Comma-delimited list of page attributes to only return in the response
      schema:
        type: array
        default: []
        uniqueItems: true
        items:
          $ref: '#/components/schemas/page_field_values'
      style: form
      explode: false
  securitySchemes:
    BearerAuth:
      description: Authentication using a bearer token (JWT) issued via OAuth.
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Get started with the NationBuilder API
  url: https://nationbuilder.com/api_quickstart