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

# REST endpoints & URLs

> All ButterCMS REST endpoints for Pages, Collections, Blog Posts, Authors, Categories, Tags, and Feeds, with common query parameters.

## Base URL

```
https://api.buttercms.com/v2
```

<Info>
  All API requests must be made over HTTPS. Requests made over plain HTTP will fail.
</Info>

## Endpoint overview

### Pages endpoints

| Method   | Endpoint                          | Description                                  |
| -------- | --------------------------------- | -------------------------------------------- |
| `GET`    | `/pages/`                         | List all Single Pages                        |
| `GET`    | `/pages/{page_type}/`             | List pages of a specific Page Type           |
| `GET`    | `/pages/{page_type}/{page_slug}/` | Retrieve a specific page by slug             |
| `GET`    | `/pages/search/`                  | Search pages by query string (`?query=term`) |
| `POST`   | `/pages/`                         | Create a new page                            |
| `PUT`    | `/pages/*/{page_slug}/`           | Update an existing page                      |
| `PATCH`  | `/pages/*/{page_slug}/`           | Partially update a page                      |
| `DELETE` | `/pages/*/{page_slug}/`           | Delete a page                                |

### Collections endpoints

| Method   | Endpoint                               | Description                         |
| -------- | -------------------------------------- | ----------------------------------- |
| `GET`    | `/content/`                            | List all Collections                |
| `GET`    | `/content/{collection_key}/`           | Retrieve items from a Collection    |
| `GET`    | `/content/{collection_key}/{item_id}/` | Retrieve a specific Collection item |
| `POST`   | `/content/`                            | Create a new Collection item        |
| `PUT`    | `/content/{collection_key}/{item_id}/` | Update a Collection item            |
| `PATCH`  | `/content/{collection_key}/{item_id}/` | Partially update a Collection item  |
| `DELETE` | `/content/{collection_key}/{item_id}/` | Delete a Collection item            |

### Blog Posts endpoints

| Method   | Endpoint         | Description                   |
| -------- | ---------------- | ----------------------------- |
| `GET`    | `/posts/`        | List all blog posts           |
| `GET`    | `/posts/{slug}/` | Retrieve a specific blog post |
| `GET`    | `/posts/search/` | Search blog posts             |
| `POST`   | `/posts/`        | Create a new blog post        |
| `PUT`    | `/posts/{slug}/` | Update a blog post            |
| `PATCH`  | `/posts/{slug}/` | Partially update a blog post  |
| `DELETE` | `/posts/{slug}/` | Delete a blog post            |

### Blog metadata endpoints

| Method | Endpoint              | Description                  |
| ------ | --------------------- | ---------------------------- |
| `GET`  | `/authors/`           | List all authors             |
| `GET`  | `/authors/{slug}/`    | Retrieve a specific author   |
| `GET`  | `/categories/`        | List all categories          |
| `GET`  | `/categories/{slug}/` | Retrieve a specific category |
| `GET`  | `/tags/`              | List all tags                |
| `GET`  | `/tags/{slug}/`       | Retrieve a specific tag      |

### Feeds endpoints

| Method | Endpoint          | Description             |
| ------ | ----------------- | ----------------------- |
| `GET`  | `/feeds/rss/`     | RSS feed of blog posts  |
| `GET`  | `/feeds/atom/`    | Atom feed of blog posts |
| `GET`  | `/feeds/sitemap/` | XML sitemap             |

## URL structure

### Pages URL pattern

```
/pages/{page_type}/{page_slug}/
```

**Parameters:**

* `page_type`: The slug of the Page Type (use `*` for Single Pages)
* `page_slug`: The unique slug identifier of the page

**Examples:**

```bash theme={null}
# Get a Single Page
GET /pages/*/homepage/

# Get a page from a Page Type
GET /pages/landing-pages/summer-sale/

# List all pages of a type
GET /pages/blog-posts/
```

### Collections URL pattern

```
/content/{collection_key}/
/content/{collection_key}/{item_id}/
```

**Parameters:**

* `collection_key`: The unique identifier/slug of the Collection
* `item_id`: The numeric ID of the Collection item

**Examples:**

```bash theme={null}
# Get all items from a Collection
GET /content/artists/

# Get a specific Collection item
GET /content/artists/123/
```

### Blog Posts URL pattern

```
/posts/{slug}/
```

**Parameters:**

* `slug`: The unique slug identifier of the blog post

**Examples:**

```bash theme={null}
# List all posts
GET /posts/

# Get a specific post
GET /posts/hello-world/

# Search posts
GET /posts/search/?query=butter
```

## Common query parameters

### Authentication

| Parameter    | Description                                               |
| ------------ | --------------------------------------------------------- |
| `auth_token` | Your Read API token (alternative to Authorization header) |

### Pagination

| Parameter   | Description                                                 | Default |
| ----------- | ----------------------------------------------------------- | ------- |
| `page`      | Page number for page-based pagination                       | 1       |
| `page_size` | Number of items per page                                    | 10      |
| `limit`     | Number of items to return (offset pagination)               | -       |
| `offset`    | Number of items to skip (offset pagination)                 | 0       |
| `order`     | Sort order (`-field` for descending, `field` for ascending) | -       |

### Content options

| Parameter | Description                                          | Default        |
| --------- | ---------------------------------------------------- | -------------- |
| `preview` | Include draft content (`1` = enabled)                | 0              |
| `locale`  | Locale code for localized content (e.g., `en`, `es`) | Default locale |
| `levels`  | Depth of reference field resolution (1-5)            | 2              |

### Blog-specific

| Parameter       | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `exclude_body`  | Exclude post body for faster list responses (`true`/`false`) |
| `category_slug` | Filter posts by category                                     |
| `tag_slug`      | Filter posts by tag                                          |
| `author_slug`   | Filter posts by author                                       |

## Example API calls

### Fetching Pages

```bash theme={null}
# List all pages of a Page Type with pagination
curl "https://api.buttercms.com/v2/pages/landing-pages/?auth_token=YOUR_TOKEN&page=1&page_size=10"

# Get a specific page with full reference resolution
curl "https://api.buttercms.com/v2/pages/landing-pages/summer-sale/?auth_token=YOUR_TOKEN&levels=3"

# Get a page in Spanish locale
curl "https://api.buttercms.com/v2/pages/landing-pages/summer-sale/?auth_token=YOUR_TOKEN&locale=es"

# Preview a draft page
curl "https://api.buttercms.com/v2/pages/landing-pages/summer-sale/?auth_token=YOUR_TOKEN&preview=1"
```

### Fetching Collections

```bash theme={null}
# Get all items from a Collection
curl "https://api.buttercms.com/v2/content/artists/?auth_token=YOUR_TOKEN"

# Filter Collection by field value
curl "https://api.buttercms.com/v2/content/artists/?auth_token=YOUR_TOKEN&fields.genre=Rock"

# Get a specific Collection item
curl "https://api.buttercms.com/v2/content/artists/123/?auth_token=YOUR_TOKEN"

# Paginated Collection with ordering
curl "https://api.buttercms.com/v2/content/artists/?auth_token=YOUR_TOKEN&page=2&page_size=20&order=-name"
```

### Fetching Blog Posts

```bash theme={null}
# List all published posts
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_TOKEN"

# Get posts without body content (faster)
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_TOKEN&exclude_body=true"

# Filter posts by category
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_TOKEN&category_slug=technology"

# Search posts
curl "https://api.buttercms.com/v2/posts/search/?auth_token=YOUR_TOKEN&query=headless%20cms"

# Get a single post with next/previous navigation
curl "https://api.buttercms.com/v2/posts/hello-world/?auth_token=YOUR_TOKEN"
```

## Trailing slashes

<Info>
  ButterCMS API endpoints require trailing slashes. Requests without trailing slashes will be redirected.
</Info>

```bash theme={null}
# Correct
GET /posts/

# Incorrect (will redirect)
GET /posts
```

## HTTPS required

All API requests must use HTTPS. The API does not accept plain HTTP requests.

```bash theme={null}
# Correct
https://api.buttercms.com/v2/posts/

# Incorrect
http://api.buttercms.com/v2/posts/
```

## Next steps

<CardGroup cols={2}>
  <Card title="Request/Response Format" icon="code" href="../concepts/request-response-format">
    Learn about JSON data structures
  </Card>

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