List Categories

GET/api/v1/content/categories

Overview

Returns all blog categories for the resolved client site. Categories support a hierarchical structure via parent_id, allowing nested category trees (e.g., Tutorials > API Guides).

Authentication

info

No authentication required - Client is resolved from the X-Content-Domain header, which the Cloudflare Worker sets automatically based on the request domain.

Headers

Header	Type	Required	Description
X-Content-Domain	string	Yes	The domain used to resolve the client tenant. Automatically set by the CF Worker; set manually for external frontend integrations.

Response

categoriesarray

Array of category objects

categories[].idstring (UUID)

Unique category identifier

categories[].namestring

Category display name

categories[].slugstring

URL-friendly slug

categories[].descriptionstring | null

Optional category description

categories[].parent_idstring (UUID) | null

Parent category ID for hierarchical nesting, or null for top-level categories

categories[].sort_orderinteger

Sort order within the parent level

categories[].childrenarray

Nested child categories (same shape, recursive)

totalinteger

Total number of categories

Example Request

cURL

curl -s "https://spideriq.ai/api/v1/content/categories" \
  -H "X-Content-Domain: your-domain.com"

Python

import requests

resp = requests.get(
    "https://spideriq.ai/api/v1/content/categories",
    headers={"X-Content-Domain": "your-domain.com"}
)
data = resp.json()

for cat in data["categories"]:
    print(f"{cat['name']} ({cat['slug']})")
    for child in cat.get("children", []):
        print(f"  - {child['name']}")

JavaScript

const resp = await fetch(
  "https://spideriq.ai/api/v1/content/categories",
  { headers: { "X-Content-Domain": "your-domain.com" } }
);
const data = await resp.json();

data.categories.forEach(cat => {
  console.log(`${cat.name} (${cat.slug})`);
  cat.children?.forEach(child => {
    console.log(`  - ${child.name}`);
  });
});

Example Response

{
  "categories": [
    {
      "id": "cat-001-uuid",
      "name": "Tutorials",
      "slug": "tutorials",
      "description": "Step-by-step guides and how-tos",
      "parent_id": null,
      "sort_order": 0,
      "children": [
        {
          "id": "cat-002-uuid",
          "name": "API Guides",
          "slug": "api-guides",
          "description": "Guides for using the SpiderIQ API",
          "parent_id": "cat-001-uuid",
          "sort_order": 0,
          "children": []
        }
      ]
    },
    {
      "id": "cat-003-uuid",
      "name": "Product Updates",
      "slug": "product-updates",
      "description": "Latest features and improvements",
      "parent_id": null,
      "sort_order": 1,
      "children": []
    }
  ],
  "total": 3
}

Status Codes

Status Code	Meaning	Description
200	OK	Categories returned successfully

Related Endpoints

📋

List Posts

List posts (filter by category)

tags

List Tags

List all tags with post counts

👥

List Authors

List active authors

🔎

Search Posts

Search across posts