openapi: 3.1.2
info:
title: NationBuilder V2 Async Processes 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. It layers a few
conventions on top of the JSON:API standard, described below. For a broader
introduction, see the
[NationBuilder v2 API core concepts](https://support.nationbuilder.com/en/articles/9757369-nationbuilder-v2-api-core-concepts)
guide.
### Request and response format
Requests and responses follow the [JSON:API](https://jsonapi.org/) document
structure: single resources are returned under a top-level `data` member, and
collections are paginated arrays of resource objects with `links` for the
current, previous, and next pages. Related resources can be sideloaded into a
top-level `included` array with the `include` query parameter, and responses
can be trimmed to specific attributes with `fields[resource_type]` sparse
fieldsets (plus opt-in `extra_fields[resource_type]` attributes where noted).
Responses are served as `application/vnd.api+json`; request bodies may be
sent as `application/vnd.api+json` or `application/json`.
Filtering uses an operator syntax: `filter[attribute]=value` for
equality (comma-separated values act as OR), and
`filter[attribute][operator]=value` for other comparisons. String attributes
support `eq`, `not_eq`, `eql`, `not_eql`, `prefix`, `not_prefix`, `suffix`,
`not_suffix`, `match`, and `not_match`; numeric and date attributes support
`eq`, `not_eq`, `gt`, `gte`, `lt`, and `lte`. Note that JSON:API relationship
routes (`/resource/{id}/relationships/other`) are not provided; related
resources are reachable through the filtered index URLs given in each
resource''s `relationships` links.
### Errors
Error responses use a flat JSON body with a machine-readable `code` and a
human-readable `message`. Some errors carry additional detail members (for
example `validation_errors`). The exception is 422 validation failures,
which return a JSON:API `errors` array locating each invalid field via
`source.pointer`.
### Rate limiting
Requests are limited per access token (250 requests per 10-second window).
Every response includes `RateLimit-Limit`, `RateLimit-Remaining`, and
`RateLimit-Reset` headers; exceeding the limit returns a 429 with a
`Retry-After` header.
'
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](https://support.nationbuilder.com/en/articles/2319593-types-of-nationbuilder-pages).
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_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'
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
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_sideload_values:
description: Relationship names that can be sideloaded with the include query parameter on page endpoints.
type: string
enum:
- membership_types
- parent
- site
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.
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
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.
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.
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_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
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'
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: {}
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.
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_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'
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.
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'
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.
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.
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_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.
parameters:
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
id:
name: id
in: path
description: id
required: true
schema:
type: string
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
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
pagination_number:
name: page[number]
description: Page number to list (starting at 1)
in: query
required: false
schema:
type: string
default: '1'
headers:
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: {}
RateLimit-Reset:
description: Unix timestamp (in seconds) at which the current rate-limit window resets.
schema:
type: string
examples:
- '1719964810'
examples: {}
responses:
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'
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'
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'
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'
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'
requestBodies:
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'
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'
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