Retrieve Collection

curl --request GET \
  --url https://api.buttercms.com/v2/content/{collection_key}/ \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.buttercms.com/v2/content/{collection_key}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.buttercms.com/v2/content/{collection_key}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.buttercms.com/v2/content/{collection_key}/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.buttercms.com/v2/content/{collection_key}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": {
    "artists": [
      {
        "meta": {
          "id": 123
        },
        "name": "The Beatles",
        "genre": "Rock",
        "formed_year": 1960,
        "description": "Legendary British rock band"
      },
      {
        "meta": {
          "id": 124
        },
        "name": "The Rolling Stones",
        "genre": "Rock",
        "formed_year": 1962,
        "description": "Iconic rock and roll band"
      }
    ]
  }
}

GET

content

{collection_key}

Retrieve Collection

curl --request GET \
  --url https://api.buttercms.com/v2/content/{collection_key}/ \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.buttercms.com/v2/content/{collection_key}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.buttercms.com/v2/content/{collection_key}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.buttercms.com/v2/content/{collection_key}/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.buttercms.com/v2/content/{collection_key}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": {
    "artists": [
      {
        "meta": {
          "id": 123
        },
        "name": "The Beatles",
        "genre": "Rock",
        "formed_year": 1960,
        "description": "Legendary British rock band"
      },
      {
        "meta": {
          "id": 124
        },
        "name": "The Rolling Stones",
        "genre": "Rock",
        "formed_year": 1962,
        "description": "Iconic rock and roll band"
      }
    ]
  }
}

Retrieve items from a specific Collection with comprehensive filtering, pagination, and relationship serialization capabilities. This endpoint provides flexible access to your dynamic content with powerful query options. Collection Structure: Collections contain completely user-defined content with customizable field schemas that you configure through the dashboard. Each collection can have different field types, validation rules, and structural requirements based on your content needs. Response Format: The response includes a meta object containing pagination information and result counts, a data array with the actual collection items, and individual item.meta objects containing unique IDs that you’ll need for update and delete operations. See also: Architecture & Performance for guidance on levels, pagination, and performance best practices.

Authorizations

Authorization

string

header

required

Set the Authorization header to Token your_read_api_token.

Example: Authorization: Token abc123def456

Note: The header value includes the Token prefix. Authorization: Bearer ... is not accepted and returns 401.

You can access your API token from your settings page.

Path Parameters

collection_key

string

required

The unique identifier/slug of the Collection to retrieve.

Must match an existing collection in your organization.

Maximum string length: 50

Query Parameters

auth_token

string

Your ButterCMS read API token

preview

enum<integer>

default:0

Set to 1 to include draft/unpublished collection items. Useful for staging environments.

Alias: test=1 is also accepted and has the same effect.

Available options:

0,

1

test

enum<integer>

default:0

Legacy alias for preview. Set to 1 to include draft/unpublished collection items.

Available options:

0,

1

order

string

Order items by one of this Collection's own field keys (optionally prefixed with - for descending). The value must match a field actually defined on the Collection's schema. Pages-style meta keys like published/updated are not valid here and return a 403.

When omitted, items are returned in natural (insertion) order.

page

integer

default:1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: x >= 1

page_size

integer

default:10

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: 1 <= x <= 100

locale

string

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.

Maximum string length: 10

Example:

"en"

levels

integer

default:2

Depth of relationship serialization.

Controls how many levels of referenced content to include:

1: Direct fields only, references as URIs
2: Direct fields + one level of references (default)
3-5: Deeper relationship traversal

Important: Higher levels increase response size. Maximum 10MB per response.

Valid range: 1-5 (inclusive). Values outside this range will be automatically capped.

Required range: 1 <= x <= 5

alt_media_text

enum<integer>

default:0

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.

Available options:

0,

1

fields

object

Dynamic field filtering using individual fields.<field_name>=<value> query parameters (not an OpenAPI deepObject-style parameter).

Filter collection items by any field using the pattern fields.{field_name}=value:

fields.genre=Rock - Filter by genre field
fields.status=published - Filter by status field
fields.year=2023 - Filter by year field

Multiple field filters can be combined in a single request.

Show child attributes

Response

Collection retrieved successfully

Collection response using page-based pagination

Overview

Read API

Write API

Webhooks API

Image API

Retrieve Collection

Authorizations

Path Parameters

Query Parameters

Response