Categories API

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

Endpoints Overview

Method	Endpoint	Description
`GET`	`/public/categories`	List categories (paginated)
`GET`	`/public/categories/{category_id}`	Get category by ID
`GET`	`/public/categories/by-slug/{slug}`	Get category by slug
`GET`	`/public/categories/{category_id}/subcategories`	Get subcategories
`GET`	`/public/categories/{category_id}/articles`	Get article IDs in category
`GET`	`/public/categories/{category_id}/translations`	Get translations of category

List Categories

GET /public/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://api.adaptocms.com/public/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 /public/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://api.adaptocms.com/public/categories/cat-001" \
  -H "x-api-key: YOUR_API_KEY"

Get Category by Slug

GET /public/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://api.adaptocms.com/public/categories/by-slug/tutorials" \
  -H "x-api-key: YOUR_API_KEY"

Get Subcategories

GET /public/categories/{category_id}/subcategories

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

Example Request

curl -X GET "https://api.adaptocms.com/public/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 /public/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://api.adaptocms.com/public/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}/public/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}/public/articles?category=${categoryId}&language=en`,
  { headers: { 'x-api-key': API_KEY } }
).then(r => r.json());

Get Category Translations

GET /public/categories/{category_id}/translations

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

Example Request

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