Retrieve Collection Item - ButterCMS Docs

Retrieve Collection Item

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

import requests

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

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.buttercms.com/v2/content/{collection_key}/{item_id}/', 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}/{item_id}/",
  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}/{item_id}/"

	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}/{item_id}/")

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

{
  "data": {
    "meta": {
      "id": 790691
    },
    "label": "Home",
    "url": "#home"
  }
}

GET

/

content

/

{collection_key}

/

{item_id}

/

Retrieve Collection Item

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

import requests

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

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.buttercms.com/v2/content/{collection_key}/{item_id}/', 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}/{item_id}/",
  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}/{item_id}/"

	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}/{item_id}/")

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

{
  "data": {
    "meta": {
      "id": 790691
    },
    "label": "Home",
    "url": "#home"
  }
}

Retrieve a single Collection item directly by its numeric item ID, instead of paging through the full collection. This is the same ID returned in every item’s meta.id field. Draft Items: By default only a published item is returned. Pass ?preview=1 to retrieve a draft item, or to preview draft field values on an otherwise-published item.

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 containing the item.

Must match an existing collection in your organization.

Maximum string length: 50

item_id

string

required

The numeric ID of the collection item, as returned in meta.id by the list/retrieve-collection endpoints.

Maximum string length: 50

Query Parameters

auth_token

string

Your ButterCMS read API token

preview

enum<integer>

default:0

Set to 1 to retrieve a draft item, or to preview draft field values on an otherwise-published item.

Available options:

0,

1

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

Response

Collection item retrieved successfully

data

object

Individual collection item with dynamic field structure and metadata

Show child attributes

Example:

{
  "meta": { "id": 123 },
  "name": "The Beatles",
  "genre": "Rock",
  "formed_year": 1960,
  "members": [
    "John Lennon",
    "Paul McCartney",
    "George Harrison",
    "Ringo Starr"
  ],
  "description": "Legendary British rock band"
}