Content Categories

Content categories organize blog posts into groups (e.g. “Engineering”, “Product Updates”, “Tutorials”). Each category has a title, handle (URL slug), optional description, and SEO metadata.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/content-categories	Publishable	List content categories
POST	/v1/content-categories	Secret	Create a content category
GET	/v1/content-categories/{id}	Publishable	Get a content category
PATCH	/v1/content-categories/{id}	Secret	Update a content category
DELETE	/v1/content-categories/{id}	Secret	Delete a content category

---

List content categories

GET /v1/content-categories

Returns a paginated list of content categories.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1-250)
cursor	string	-	Pagination cursor from a previous response
sort	string	created_at	Sort field
order	string	desc	Sort direction: asc, desc
search	string	-	Filter by title (max 200 chars)
expand	string	-	Include related data: post_count
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/content-categories?expand=post_count \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "ccat_abc123def456ghij",
			"title": "Engineering",
			"handle": "engineering",
			"description": "Technical articles and product updates.",
			"seo": {
				"title": "Engineering Blog",
				"description": "Read our latest engineering articles."
			},
			"position": 0,
			"post_count": 12,
			"created_at": "2026-08-01T10:00:00.000Z",
			"updated_at": "2026-08-15T14:00:00.000Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 3
	}
}

---

Create a content category

POST /v1/content-categories

Creates a new content category. The handle is auto-generated from the title if not provided.

Request body

Field	Type	Required	Description
title	string	Yes	Category title (1-255 chars)
handle	string	No	URL slug (auto-generated from title)
description	string	No	Category description (max 10,000 chars)
seo	object	No	SEO metadata with title and description

Request

curl -X POST https://api.hydrajs.dev/v1/content-categories \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Engineering",
    "description": "Technical articles and product updates."
  }'

Response 201

{
	"data": {
		"id": "ccat_abc123def456ghij",
		"title": "Engineering",
		"handle": "engineering",
		"description": "Technical articles and product updates.",
		"seo": { "title": null, "description": null },
		"position": 0,
		"post_count": 0,
		"created_at": "2026-08-01T10:00:00.000Z",
		"updated_at": "2026-08-01T10:00:00.000Z"
	}
}

---

Get a content category

GET /v1/content-categories/{id}

Retrieves a single content category by ID, including its post count.

Request

curl https://api.hydrajs.dev/v1/content-categories/ccat_abc123def456ghij \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "ccat_abc123def456ghij",
		"title": "Engineering",
		"handle": "engineering",
		"description": "Technical articles and product updates.",
		"seo": {
			"title": "Engineering Blog",
			"description": "Read our latest engineering articles."
		},
		"position": 0,
		"post_count": 12,
		"created_at": "2026-08-01T10:00:00.000Z",
		"updated_at": "2026-08-15T14:00:00.000Z"
	}
}

---

Update a content category

PATCH /v1/content-categories/{id}

Partially updates a content category. Only provided fields are modified.

Request body

Field	Type	Required	Description
title	string	No	Category title (1-255 chars)
handle	string	No	URL slug (1-255 chars)
description	string	No	Category description (max 10,000 chars)
seo	object	No	SEO metadata with title and description

Request

curl -X PATCH https://api.hydrajs.dev/v1/content-categories/ccat_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Tech Blog"}'

Response 200

{
	"data": {
		"id": "ccat_abc123def456ghij",
		"title": "Tech Blog",
		"handle": "engineering",
		"description": "Technical articles and product updates.",
		"seo": {
			"title": "Engineering Blog",
			"description": "Read our latest engineering articles."
		},
		"position": 0,
		"post_count": 12,
		"created_at": "2026-08-01T10:00:00.000Z",
		"updated_at": "2026-08-20T09:00:00.000Z"
	}
}

---

Delete a content category

DELETE /v1/content-categories/{id}

Permanently deletes a content category. Posts associated with this category are not deleted; only the category association is removed.

Request

curl -X DELETE https://api.hydrajs.dev/v1/content-categories/ccat_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

The content category object

Field	Type	Description
id	string	Unique ID (prefix: ccat_)
title	string	Category title
handle	string	URL slug (unique per store)
description	string	Category description
seo	object	SEO metadata (title, description)
position	integer	Display order
post_count	integer	Number of posts in this category (expanded)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp