> ## Documentation Index > Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get multiple Pages > Retrieve a paginated list of pages for a given page type, or all Single Pages using the wildcard *. Retrieve a paginated list of pages for a given page type, or all Single Pages when using the wildcard `*` as the page type. This endpoint supports comprehensive filtering and sorting for Page Type collections. **Single Pages**: Use `*` as your `page_type` parameter to retrieve Single Pages, which are unique pages like your Homepage, About page, or Contact page. This is particularly useful for generating sitemaps or building navigation structures that include your standalone pages. **Page Types**: Use the actual page type slug to retrieve all Pages of that type, like new articles, product pages, etc. Pages will all have the same field schema. > **Important**: Advanced filtering and ordering capabilities are only > available for Page Type endpoints, not when retrieving Single Pages with the > `*` wildcard. Use dotted notation for field filters (e.g., `fields.title=Home`). See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices. ## OpenAPI ````yaml /api/openapi/read_api.yaml get /pages/{page_type}/ openapi: 3.1.0 info: title: ButterCMS Read API version: 2.0.0 description: > Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog Metadata, and Feeds. contact: email: support@buttercms.com license: name: ButterCMS Terms of Service url: https://buttercms.com/terms/ servers: - url: https://api.buttercms.com/v2 description: ButterCMS API v2 security: - readTokenAuthHeader: [] - readTokenAuthQuery: [] tags: - name: Pages description: > Retrieve pages from your ButterCMS account. **Single Pages**: Use `*` as the page_type to get Single Pages (those without a Page Type) which represent unique pages on your site like your Homepage. Useful for creating your sitemap.xml. **Page Type Pages**: Use the actual page type slug to get pages of that specific type. Page Types allow you to create many pages with the same structure. **Note:** The fields of a page are defined by you, they are customizable. Sample responses below contain a basic set of fields for illustrative purposes. - name: Collections description: > Retrieve collection items from your ButterCMS account. Collections are flexible, user-defined content structures with completely customizable field schemas. See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices. - name: Blog posts description: > Retrieve blog posts from your ButterCMS account. List blog posts with pagination and filtering options, or retrieve individual posts by slug. - name: Blog metadata description: > Retrieve blog-related metadata including authors, categories, and tags. These endpoints provide access to the organizational structure of your blog content. - name: Feeds and utilities description: > Generate XML feeds for content syndication and SEO. - **RSS Feed**: Fully generated RSS 2.0 feed for your blog - **Atom Feed**: Standards-compliant Atom 1.0 feed - **Sitemap**: XML sitemap for search engine discovery All feeds can be filtered by category or tag and include only published content from your organization. - name: Images - Info description: > ButterCMS has an integration with [Filestack](https://www.filestack.com/docs/api/processing/) for image transformations. You can leverage their robust set of image transformation capabilities. After you upload an image, to create a thumbnail, here's an example: - **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy` - **Thumbnail URL**: `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy` For complete transformation options and parameters, see the [full Filestack documentation](https://www.filestack.com/docs/api/processing/). paths: /pages/{page_type}/: get: tags: - Pages summary: Get multiple Pages description: > Retrieve a paginated list of pages for a given page type, or all Single Pages when using the wildcard `*` as the page type. This endpoint supports comprehensive filtering and sorting for Page Type collections. **Single Pages**: Use `*` as your `page_type` parameter to retrieve Single Pages, which are unique pages like your Homepage, About page, or Contact page. This is particularly useful for generating sitemaps or building navigation structures that include your standalone pages. **Page Types**: Use the actual page type slug to retrieve all Pages of that type, like new articles, product pages, etc. Pages will all have the same field schema. > **Important**: Advanced filtering and ordering capabilities are only available for Page Type endpoints, not when retrieving Single Pages with the `*` wildcard. Use dotted notation for field filters (e.g., `fields.title=Home`). See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices. operationId: getMultiplePages parameters: - name: page_type in: path description: > The slug of the type of pages you want to retrieve, or `*` for Single Pages. - Use `*` to get Single Pages (those without a Page Type) - Use the actual page type slug to get pages of that specific type required: true schema: type: string examples: single_pages: value: '*' description: Get all Single Pages news_pages: value: news description: Get pages of type 'news' faq_pages: value: faq description: Get pages of type 'faq' - $ref: '#/components/parameters/preview' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/page_size' - $ref: 93cf2c7e-75ce-4beb-b455-38e9541bd339 - $ref: 86c8b313-f5c9-4a9e-9b7a-5b789f6e0aae - $ref: '#/components/parameters/locale' - $ref: 43ca77a3-2fdc-4e00-a9e8-459d3b50cfc0 - name: alt_media_text in: query description: > Media field response format. Affects only media-typed fields. Other field types are unchanged. - **0** (default): Media fields return simple URL strings - **1**: Media fields return objects with at least `url` and, when available, `alt`. If the stored media value is just a URL string, the object will include `url` only. required: false schema: type: integer enum: - 0 - 1 default: 0 examples: url_only: value: 0 description: Return media as URL strings (default) object_format: value: 1 description: >- Return media as objects with at least url (alt included when available) - $ref: '#/components/parameters/auth_token' - $ref: '#/components/parameters/order' - name: fields.seo.title in: query description: > Filter the result set by a nested field value. This is an example of field filtering — you can filter by any field using the pattern `fields.=`. You can pass in multiple filters at once. For example: `&fields.seo.title=Home&fields.headline=Welcome` To filter on Reference or Component fields use dot notation. For example: `fields.hero.title=value` or `fields.hero.reference.title=value` **Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`). required: false schema: type: string example: Home - name: fields.headline in: query description: > Filter the result set by a top-level field value. This is an example of field filtering — you can filter by any field using the pattern `fields.=`. **Note**: Field filtering is only available for Page Type endpoints, not for Single Pages (`page_type=*`). required: false schema: type: string example: Welcome responses: '200': description: > **Success** Returns a hash with a `data` property that contains an array of pages, and a `meta` property that contains pagination information. - For Single Pages (`page_type=*`): Returns pages without a page type - For Page Types: Returns pages of the specified type content: application/json: schema: oneOf: - $ref: '#/components/schemas/SinglePagesResponse' - $ref: '#/components/schemas/PageBasedPagesResponse' - $ref: '#/components/schemas/OffsetBasedPagesResponse' examples: single_pages: summary: Single Pages Response (page_type=*) value: meta: previous_page: null next_page: null count: 2 data: - slug: single-page-1 page_type: null published: '2019-11-12T17:23:53.109696Z' updated: '2020-10-22T20:07:52.965850Z' fields: title: This is a single page body:

Single PAGE!

- slug: single-page-2 page_type: null published: '2019-11-12T17:23:53.109696Z' updated: '2020-10-22T20:07:52.965850Z' fields: title: Amazing Single Page body:

Another single page!

page_type_pages: summary: Page Type Response (page_type=news) value: meta: previous_page: null next_page: null count: 2 data: - slug: example-news-page name: Example News Page page_type: news published: '2019-11-12T17:23:53.109696Z' updated: '2020-10-22T20:07:52.965850Z' fields: seo: title: Example News Page description: SEO Description keywords: SEO, Keywords headline: This is an example news page media_url_format: summary: Media field as URL string (alt_media_text=0) description: >- When `alt_media_text=0` (default), media fields are returned as URL strings. value: meta: previous_page: null next_page: null count: 1 data: - slug: poster-page name: Poster Page page_type: posters published: '2020-01-01T10:00:00Z' updated: '2020-01-02T10:00:00Z' fields: title: Poster Details media: https://cdn.example.com/media/poster.jpg media_object_format: summary: Media field as object (alt_media_text=1) description: > When `alt_media_text=1`, media fields are returned as objects. The object always includes `url`, and `alt` is included when available. value: meta: previous_page: null next_page: null count: 1 data: - slug: poster-page name: Poster Page page_type: posters published: '2020-01-01T10:00:00Z' updated: '2020-01-02T10:00:00Z' fields: title: Poster Details media: url: https://cdn.example.com/media/poster.jpg alt: Movie poster artwork offset_page_type_response: summary: Offset-based pagination for page types description: Using ?limit=10&offset=5 parameters for page type 'news' value: meta: count: 15 next_offset: 15 previous_offset: null data: - slug: news-page-3 name: News Page 3 page_type: news published: '2019-11-13T17:23:53.109696Z' updated: '2020-10-23T20:07:52.965850Z' fields: seo: title: Latest News Update description: Breaking news content keywords: News, Updates headline: Breaking news story offset_single_pages_response: summary: Offset-based pagination for single pages description: Using ?limit=10&offset=5 parameters for page_type='*' value: meta: count: 8 next_offset: null previous_offset: null data: - slug: about-us-page page_type: '*' published: '2019-11-14T17:23:53.109696Z' updated: '2020-10-24T20:07:52.965850Z' fields: title: About Our Company body:

Learn about our mission and values

'401': $ref: '#/components/responses/UnauthorizedResponse' '404': description: > **Not Found - Page Type Does Not Exist or Invalid Pagination** - The requested page type doesn't exist or you don't have access to it. - Invalid pagination parameters (page number out of range). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: page_type_not_found: summary: Page type not found value: detail: Page type not found. missing_page_type: summary: Missing page type key format value: detail: >- Page Type Key missing. Please format request like so /pages/ invalid_pagination: summary: Invalid pagination value: detail: Invalid Page. security: - readTokenAuthQuery: [] - readTokenAuthHeader: [] components: parameters: preview: name: preview in: query description: > Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. `&preview=1`. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes. Set to `1` to access unpublished/draft collection items. Useful for staging environments. required: false schema: type: integer enum: - 0 - 1 default: 0 example: 1 page: name: page in: query description: | Page number for page-based pagination. **Mutually exclusive with limit/offset parameters.** required: false schema: type: integer default: 1 minimum: 1 example: 2 page_size: name: page_size in: query description: | Number of items per page for page-based pagination. **Mutually exclusive with limit/offset parameters.** required: false schema: type: integer default: 10 minimum: 1 maximum: 100 example: 5 locale: name: locale in: query description: > Set to the api slug of your configured locale (e.g. `en` or `fr`). When omitted, this query parameter will default to your organization's default locale. required: false schema: type: string maxLength: 10 example: en examples: english: value: en description: English locale spanish: value: es description: Spanish locale french: value: fr description: French locale auth_token: name: auth_token in: query required: false schema: type: string description: | Your ButterCMS read API token example: your_api_token order: name: order in: query description: > Can order by page level `published`, `updated`, or a content field of the Page Type. Defaults to ascending, prepend '-' to sort descending. **Note**: Only available for Page Type endpoints, not for Single Pages (`page_type=*`). required: false schema: type: string examples: ascending_title: value: title description: Order by title ascending descending_published: value: '-published' description: Order by published date descending ascending_updated: value: updated description: Order by updated date ascending schemas: SinglePagesResponse: type: object properties: meta: $ref: '#/components/schemas/PaginationMeta' data: type: array items: $ref: '#/components/schemas/SinglePage' PageBasedPagesResponse: type: object description: Page type response using page-based pagination properties: meta: $ref: '#/components/schemas/PaginationMeta' data: type: array items: $ref: '#/components/schemas/PageTypePage' required: - meta - data OffsetBasedPagesResponse: type: object description: Page type response using offset-based pagination properties: meta: $ref: '#/components/schemas/OffsetPaginationMeta' data: type: array items: $ref: '#/components/schemas/PageTypePage' required: - meta - data ErrorResponse: type: object properties: detail: type: string description: Error message describing what went wrong example: Authentication credentials were not provided PaginationMeta: type: object properties: previous_page: type: - integer - 'null' description: Previous page number if it exists next_page: type: - integer - 'null' description: Next page number if it exists count: type: integer description: Total number of items SinglePage: type: object properties: slug: type: string description: Unique identifier example: single-page-1 page_type: type: - string - 'null' description: Page type - null for single pages example: null published: type: string format: date-time description: Timestamp of when the page was first published example: '2019-11-12T17:23:53.109696Z' updated: type: string format: date-time description: Timestamp of when the page was most recently published example: '2020-10-22T20:07:52.965850Z' fields: type: object description: >- Contains all of the actual content for the Page - fields are customizable additionalProperties: true example: title: This is a single page body:

Single PAGE!

PageTypePage: type: object properties: slug: type: string description: Unique identifier example: example-news-page name: type: string description: Name of the Page example: Example News Page page_type: type: string description: API slug identifier of the page_type for the Page example: news published: type: string format: date-time description: Timestamp of when the page was first published example: '2019-11-12T17:23:53.109696Z' updated: type: string format: date-time description: Timestamp of when the page was most recently published example: '2020-10-22T20:07:52.965850Z' fields: type: object description: >- Contains all of the actual content for the Page - fields are customizable additionalProperties: true example: seo: title: Example News Page description: SEO Description keywords: SEO, Keywords headline: This is an example news page tag: example genre: api OffsetPaginationMeta: type: object description: Pagination metadata for limit/offset pagination properties: count: type: integer description: Total number of items example: 25 next_offset: type: - integer - 'null' description: Offset for the next page, null if no next page example: 20 previous_offset: type: - integer - 'null' description: Offset for the previous page, null if no previous page example: null responses: UnauthorizedResponse: description: Unauthorized - Invalid or missing API token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Missing API token value: detail: Authentication credentials were not provided invalid_token: summary: Invalid API token value: detail: Invalid token securitySchemes: readTokenAuthHeader: type: apiKey in: header name: Authorization description: | Set the `Authorization` header to `Token your_read_api_token`. Example: `Authorization: Token abc123def456` Note: The header value includes the `Token` prefix. You can access your API token from your settings page. readTokenAuthQuery: type: apiKey in: query name: auth_token description: > Pass your API token via the `auth_token` parameter on every request: `?auth_token=your_read_api_token`. You can access your API token from your settings page. Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS. ````