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
GET	/v1/content-categories/{id}/posts	Publishable	List posts in a category
POST	/v1/content-categories/{id}/posts	Secret	Add posts to a category
DELETE	/v1/content-categories/{id}/posts/{post_id}	Secret	Remove a post from a category
PATCH	/v1/content-categories/{id}/posts/reorder	Secret	Reorder posts in a 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_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_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_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_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_YOUR_KEY"

Response 204

Empty body.

---

List posts in a category

GET /v1/content-categories/{id}/posts

Returns posts belonging to a content category, sorted by their position within the category.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1-250)
cursor	string	-	Pagination cursor from a previous response
type	string	-	Filter by post type: post, page

Request

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

Response 200

{
	"data": [
		{
			"id": "post_abc123",
			"type": "post",
			"title": "Getting Started with Hydra",
			"handle": "getting-started-with-hydra",
			"status": "published",
			"position": 0,
			"featured_image": {
				"id": "img_xyz789",
				"src": "https://cdn.hydrajs.dev/store_xxx/products/abc.webp",
				"alt": "Hero image"
			},
			"created_at": "2026-08-10T12:00:00.000Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 1
	}
}

---

Add posts to a category

POST /v1/content-categories/{id}/posts

Associates one or more posts with a content category. Posts already in the category are skipped. New posts are appended at the end.

Request body

Field	Type	Required	Description
post_ids	string[]	Yes	Array of post IDs to add (1-100 items)

Request

curl -X POST https://api.hydrajs.dev/v1/content-categories/ccat_abc123def456ghij/posts \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post_ids": ["post_abc123", "post_def456"]}'

Response 200

Returns the updated content category object (same shape as Get).

---

Remove a post from a category

DELETE /v1/content-categories/{id}/posts/{post_id}

Removes a post association from a content category. The post itself is not deleted.

Request

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

Response 204

Empty body.

---

Reorder posts in a category

PATCH /v1/content-categories/{id}/posts/reorder

Updates the display position of posts within a content category. All posts in the request body must already belong to the category.

Request body

Field	Type	Required	Description
posts	array	Yes	Array of {id, position} objects (1-250 items)

Each object in the posts array:

Field	Type	Description
id	string	Post ID
position	integer	New zero-based position

Request

curl -X PATCH https://api.hydrajs.dev/v1/content-categories/ccat_abc123def456ghij/posts/reorder \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {"id": "post_def456", "position": 0},
      {"id": "post_abc123", "position": 1}
    ]
  }'

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