Developer documentation

Categories API

Retrieve the categories in your ContioReach workspace.

Use it to build category navigation, and to resolve a category slug into its name and post count before requesting the posts themselves.

Endpoint

GEThttps://cms-api.contioreach.com/v1/categories

curl

curl "https://cms-api.contioreach.com/v1/categories" \
  -H "X-API-Key: YOUR_API_KEY"

Query parameters

Parameter	Type	Description
page	number	Page of results to return. Starts at 1.
limit	number	Categories per page.
id	string	Return the single category matching this id.
slug	string	Return the single category matching this slug.

Response

GET /v1/categories?limit=2

{
  "success": true,
  "data": [
    {
      "id": "2eb739a5-bb01-4544-b509-ab9133ea0637",
      "name": "Blogging",
      "slug": "blogging",
      "postCount": 12
    },
    {
      "id": "3fcf8b61-41d7-4d05-8aed-46f8205d4b7e",
      "name": "Content Marketing",
      "slug": "content-marketing",
      "postCount": 19
    }
  ],
  "meta": {
    "page": 1,
    "limit": 2,
    "total": 5,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Filtering by slug still returns an array. Take the first entry.

Category fields

Field	Type	Description
id	string	Unique identifier.
name	string	Display name.
slug	string	URL-safe identifier for your category route.
postCount	number	Number of published posts in the category.

Examples

Build the category navigation

JavaScript

const res = await fetch(
  "https://cms-api.contioreach.com/v1/categories",
  { headers: { "X-API-Key": process.env.CMS_API_KEY } }
);

const { data: categories } = await res.json();

Resolve a category page

Fetch the category for its name, then request its posts from the Posts API using the same slug:

JavaScript

const categoryRes = await fetch(
  `https://cms-api.contioreach.com/v1/categories?slug=${slug}`,
  { headers: { "X-API-Key": process.env.CMS_API_KEY } }
);

const category = (await categoryRes.json()).data[0];

if (!category) notFound();

const postsRes = await fetch(
  `https://cms-api.contioreach.com/v1/blogs?category=${slug}&limit=12&minimal=true`,
  { headers: { "X-API-Key": process.env.CMS_API_KEY } }
);

const { data: posts, meta } = await postsRes.json();

Errors

Status	Code	Meaning
401	INVALID_API_KEY	The API key is missing, incorrect, or inactive.

A slug that matches nothing returns 200 with an empty data array rather than a 404, so check the array length before rendering.

PreviousPosts NextTags