---
title: "Categories API"
url: "https://adaptocms.com/docs/categories-api/"
source: adaptocms.com
---

# Categories API

Categories provide a hierarchical taxonomy for organizing articles. They support nesting (subcategories), translations, and article associations.

## Endpoints Overview

Method

Endpoint

Description

`GET`

`/v1/categories`

List categories (paginated)

`GET`

`/v1/categories/{category_id}`

Get category by ID

`GET`

`/v1/categories/by-slug/{slug}`

Get category by slug

`GET`

`/v1/categories/{category_id}/subcategories`

Get subcategories

`GET`

`/v1/categories/{category_id}/articles`

Get article IDs in category

`GET`

`/v1/categories/{category_id}/translations`

Get translations of category

* * *

## List Categories

```
GET /v1/categories
```

Returns a paginated list of categories.

### Query Parameters

Parameter

Type

Required

Description

`parent_id`

string

No

Filter by parent category ID (get only children of a specific category)

`language`

string

No

Filter by language code

`keyword`

string

No

Search in name and description

`field`

string

No

Sort field

`order`

string

No

Sort order: `asc` or `desc`

`page`

integer

No

Page number (default: 1)

`limit`

integer

No

Items per page (default: 20)

### Example Request

```
curl -X GET "https://public-api.adaptocms.com/v1/categories?language=en" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example Response

```
{
  "items": [
    {
      "id": "cat-001",
      "name": "Tutorials",
      "slug": "tutorials",
      "description": "Step-by-step guides and how-tos",
      "parent_id": null,
      "language": "en",
      "created_at": "2026-01-10T08:00:00",
      "updated_at": "2026-01-10T08:00:00",
      "translation_of_id": null,
      "custom_fields": {},
      "file_urls": null
    },
    {
      "id": "cat-002",
      "name": "API Guides",
      "slug": "api-guides",
      "description": "Guides for working with the API",
      "parent_id": "cat-001",
      "language": "en",
      "created_at": "2026-01-12T10:00:00",
      "updated_at": "2026-01-12T10:00:00",
      "translation_of_id": null,
      "custom_fields": {},
      "file_urls": null
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 20,
  "pages": 1
}
```

* * *

## Get Category by ID

```
GET /v1/categories/{category_id}
```

### Path Parameters

Parameter

Type

Required

Description

`category_id`

string (UUID)

Yes

The unique identifier of the category

### Example Request

```
curl -X GET "https://public-api.adaptocms.com/v1/categories/cat-001" \
  -H "x-api-key: YOUR_API_KEY"
```

* * *

## Get Category by Slug

```
GET /v1/categories/by-slug/{slug}
```

### Path Parameters

Parameter

Type

Required

Description

`slug`

string

Yes

The URL-friendly slug of the category

### Example Request

```
curl -X GET "https://public-api.adaptocms.com/v1/categories/by-slug/tutorials" \
  -H "x-api-key: YOUR_API_KEY"
```

* * *

## Get Subcategories

```
GET /v1/categories/{category_id}/subcategories
```

Returns an array of `CategoryResponseModel` objects that are direct children of the specified category.

### Example Request

```
curl -X GET "https://public-api.adaptocms.com/v1/categories/cat-001/subcategories" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example Response

```
[
  {
    "id": "cat-002",
    "name": "API Guides",
    "slug": "api-guides",
    "description": "Guides for working with the API",
    "parent_id": "cat-001",
    "language": "en",
    ...
  }
]
```

* * *

## Get Articles in Category

```
GET /v1/categories/{category_id}/articles
```

Returns an array of **article IDs** (strings) associated with the category. Use these IDs to fetch full article details from the Articles API.

### Example Request

```
curl -X GET "https://public-api.adaptocms.com/v1/categories/cat-001/articles" \
  -H "x-api-key: YOUR_API_KEY"
```

### Example Response

```
["article-id-1", "article-id-2", "article-id-3"]
```

### Use Case: Category Page

```
// 1. Get article IDs for a category
const articleIds = await fetch(
  `${BASE_URL}/v1/categories/${categoryId}/articles`,
  { headers: { 'x-api-key': API_KEY } }
).then(r => r.json());

// 2. Fetch full articles (or use the articles list endpoint with category filter)
const articles = await fetch(
  `${BASE_URL}/v1/articles?category=${categoryId}&language=en`,
  { headers: { 'x-api-key': API_KEY } }
).then(r => r.json());
```

* * *

## Get Category Translations

```
GET /v1/categories/{category_id}/translations
```

Returns an array of `CategoryResponseModel` objects representing all translations of the specified category.

### Example Request

```
curl -X GET "https://public-api.adaptocms.com/v1/categories/cat-001/translations" \
  -H "x-api-key: YOUR_API_KEY"
```