> ## 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.

# Request/response format

> A summary of all ButterCMS API responses, including formats and status codes.

## Response structure

All successful API responses return JSON with a `data` property containing the requested content. List endpoints also include a `meta` property with pagination information. Detail endpoints for single items return only the `data` property.

**List response:**

```json theme={null}
{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": [
    // Your content here
  ]
}
```

**Detail response:**

```json theme={null}
{
  "data": {
    // Your content here
  }
}
```

### The `meta` object

Included in list responses and blog post detail responses. Contains metadata about the response such as pagination information or navigation links:

| Field           | Type         | Description                               |
| --------------- | ------------ | ----------------------------------------- |
| `count`         | integer      | Total number of items available           |
| `next_page`     | integer/null | Next page number (null if last page)      |
| `previous_page` | integer/null | Previous page number (null if first page) |

For offset-based pagination:

| Field             | Type         | Description                     |
| ----------------- | ------------ | ------------------------------- |
| `count`           | integer      | Total number of items available |
| `next_offset`     | integer/null | Next offset value               |
| `previous_offset` | integer/null | Previous offset value           |

### The `data` object

Contains the actual content. Structure varies by endpoint type:

* **List endpoints**: Array of items or keyed object
* **Detail endpoints**: Single item object
* **Write operations**: Success confirmation or created item

## Content type responses

### Pages response

**Single Page Detail:**

```json theme={null}
{
  "data": {
    "slug": "homepage",
    "name": "Homepage",
    "published": "2024-01-15T10:30:00Z",
    "updated": "2024-01-20T14:45:00Z",
    "scheduled": null,
    "status": "published",
    "page_type": null,
    "fields": {
      "hero_title": "Welcome to Our Site",
      "hero_image": "https://cdn.buttercms.com/abc123",
      "body_content": "<p>Welcome to our homepage...</p>",
      "cta_button_text": "Get Started"
    }
  }
}
```

**Page Type List:**

```json theme={null}
{
  "meta": {
    "count": 15,
    "next_page": 2,
    "previous_page": null
  },
  "data": [
    {
      "slug": "summer-sale",
      "name": "Summer Sale",
      "published": "2024-01-15T10:30:00Z",
      "updated": "2024-01-16T09:00:00Z",
      "scheduled": null,
      "status": "published",
      "page_type": "landing-pages",
      "fields": {
        "title": "Summer Sale 2024",
        "description": "..."
      }
    },
    {
      "slug": "winter-promo",
      "name": "Winter Promo",
      "published": "2024-01-10T08:00:00Z",
      "updated": "2024-01-11T11:00:00Z",
      "scheduled": null,
      "status": "published",
      "page_type": "landing-pages",
      "fields": {
        "title": "Winter Promotion",
        "description": "..."
      }
    }
  ]
}
```

### Collections response

**Collection List:**

```json theme={null}
{
  "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"
      }
    ]
  }
}
```

<Info>
  Collection items include a nested `meta` object with the item's numeric `id`, which is required for update and delete operations.
</Info>

### Blog Posts response

**Post List:**

```json theme={null}
{
  "meta": {
    "count": 50,
    "next_page": 2,
    "previous_page": null
  },
  "data": [
    {
      "status": "published",
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-01-20T14:45:00Z",
      "published": "2024-01-15T12:00:00Z",
      "scheduled": null,
      "title": "Getting Started with ButterCMS",
      "slug": "getting-started-buttercms",
      "body": "<p>Welcome to ButterCMS...</p>",
      "summary": "Learn how to get started with ButterCMS",
      "seo_title": "Getting Started with ButterCMS | Tutorial",
      "meta_description": "A complete guide to getting started...",
      "featured_image": "https://cdn.buttercms.com/xyz789",
      "featured_image_alt": "ButterCMS dashboard screenshot",
      "url": "https://www.example.com/blog/getting-started-buttercms",
      "author": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "slug": "john-doe",
        "bio": "Technical writer and CMS enthusiast.",
        "title": "Developer Advocate",
        "linkedin_url": "https://www.linkedin.com/in/johndoe",
        "facebook_url": "https://www.facebook.com/johndoe",
        "instagram_url": "https://www.instagram.com/johndoe",
        "pinterest_url": "https://www.pinterest.com/johndoe",
        "twitter_handle": "johndoe",
        "profile_image": "https://cdn.buttercms.com/author123.jpg"
      },
      "categories": [
        {
          "name": "Tutorials",
          "slug": "tutorials"
        }
      ],
      "tags": [
        {
          "name": "Getting Started",
          "slug": "getting-started"
        }
      ]
    }
  ]
}
```

**Single Post Detail:**

```json theme={null}
{
  "meta": {
    "next_post": {
      "slug": "advanced-features",
      "title": "Advanced ButterCMS Features",
      "featured_image": "https://cdn.buttercms.com/next123.jpg"
    },
    "previous_post": {
      "slug": "introduction",
      "title": "Introduction to Headless CMS",
      "featured_image": null
    }
  },
  "data": {
    "status": "published",
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-01-20T14:45:00Z",
    "published": "2024-01-15T12:00:00Z",
    "scheduled": null,
    "slug": "getting-started-buttercms",
    "title": "Getting Started with ButterCMS",
    "body": "<p>Full post content here...</p>",
    // ... additional fields (same as list response)
  }
}
```

## Reference field responses

Reference fields return different data based on the `levels` parameter:

### Level 1 (URIs only)

```json theme={null}
{
  "data": {
    "meta": {"id": 123},
    "name": "Technology",
    "related_items": ["/v2/content/?keys=categories[_id=456]"],
    "featured_page": ["/v2/pages/product-guides/tech-overview/"]
  }
}
```

### Level 2+ (complete objects)

```json theme={null}
{
  "data": {
    "meta": {"id": 123},
    "name": "Technology",
    "related_items": [
      {"meta": {"id": 456}, "name": "Software", "description": "..."}
    ],
    "featured_page": [
      {"slug": "tech-overview", "fields": {"title": "Technology Guide", "summary": "..."}}
    ]
  }
}
```

## Media field formats

Media fields can return data in two formats based on the `alt_media_text` parameter:

### Default format (URL string)

When `alt_media_text=0` (default):

```json theme={null}
{
  "data": {
    "title": "Product Image",
    "media": "https://cdn.buttercms.com/abc123.jpg"
  }
}
```

### Object format with alt text

When `alt_media_text=1`:

```json theme={null}
{
  "data": {
    "title": "Product Image",
    "media": {
      "url": "https://cdn.buttercms.com/abc123.jpg",
      "alt": "Product showcase image"
    }
  }
}
```

## Localized responses

When requesting content in a specific locale using the `locale` query parameter (e.g., `?locale=de`), the response returns the localized content for that locale. The response structure is the same as a standard response — there is no additional `locale` field in the response body:

```json theme={null}
{
  "data": {
    "slug": "about-us",
    "name": "About Us",
    "published": "2024-01-15T10:30:00Z",
    "updated": "2024-01-20T14:45:00Z",
    "scheduled": null,
    "status": "published",
    "page_type": null,
    "fields": {
      "title": "Über uns",
      "description": "Willkommen bei unserem Unternehmen..."
    }
  }
}
```

## Request formats

### GET requests

Query parameters are passed in the URL:

```bash theme={null}
GET /v2/posts/?auth_token=TOKEN&page=1&page_size=10&locale=en
```

### POST/PUT/PATCH requests

Data is sent as JSON in the request body:

```bash theme={null}
POST /v2/pages/
Content-Type: application/json
Authorization: Token YOUR_WRITE_TOKEN

{
  "title": "New Landing Page",
  "slug": "new-landing-page",
  "page_type": "landing-pages",
  "status": "draft",
  "fields": {
    "en": {
      "hero_title": "Welcome",
      "hero_subtitle": "Get started today"
    }
  }
}
```

## Write operation responses

### Successful creation (202 Accepted)

```json theme={null}
{
  "status": "pending"
}
```

Write operations are processed asynchronously. The `pending` status indicates the request has been accepted and is being processed in the background.

### Successful update (202 Accepted)

```json theme={null}
{
  "status": "pending"
}
```

### Successful deletion (204 No Content)

No response body is returned for successful deletions.

## Pagination patterns

### Page-based pagination

Use `page` and `page_size` parameters:

```bash theme={null}
GET /v2/posts/?page=2&page_size=10
```

Response includes:

```json theme={null}
{
  "meta": {
    "count": 100,
    "next_page": 3,
    "previous_page": 1
  }
}
```

### Offset-based pagination

Use `limit` and `offset` parameters:

```bash theme={null}
GET /v2/content/products/?limit=10&offset=20
```

Response includes:

```json theme={null}
{
  "meta": {
    "count": 100,
    "next_offset": 30,
    "previous_offset": 10
  }
}
```

## Content-type headers

### Request headers

```
Content-Type: application/json
Authorization: Token your_api_token
```

### Response headers

```
Content-Type: application/json
```

## Next steps

<CardGroup cols={2}>
  <Card title="HTTP Status Codes" icon="circle-exclamation" href="../concepts/http-status-codes-errors">
    Understand error responses
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="../concepts/rate-limits-throttling">
    Learn about API limits
  </Card>

  <Card title="REST Endpoints" icon="route" href="../concepts/rest-endpoints-urls">
    View all available endpoints
  </Card>
</CardGroup>