Categories

Categories organize your knowledge base articles into logical groups. Customers see public categories when browsing your help center.

The Category object

id string

Unique category identifier (UUID)

name string

Category display name

slug string

URL-safe slug (auto-generated from name)

description string

Category description

icon string

Lucide icon name, such as "rocket" or "credit-card" (https://lucide.dev/icons). A name that is not an icon is rejected with a 400.

color string

Color value

sortOrder integer

Display order (ascending)

isPublic boolean

Whether visible in the public knowledge base

createdAt datetime

When the category was created

updatedAt datetime

Last modification timestamp

Endpoints

GET List Categories POST Create Category PATCH Update Category DELETE Delete Category

GET /api/v1/teams/{teamId}/categories

List Categories

Retrieve all categories for a team, ordered by sort order then name.

Query Parameters

isPublic boolean

Filter to public categories only

Code Examples

bash

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/categories" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 List of categories

json

{
  "success": true,
  "data": [
    {
      "id": "7134fc12-0302-4e58-9466-a770035d5da9",
      "object": "category",
      "name": "Getting Started",
      "slug": "getting-started",
      "description": "Beginner guides and onboarding",
      "isPublic": true,
      "sortOrder": 0,
      "createdAt": "2025-12-10T14:30:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z",
    "pagination": {
      "total": 3,
      "page": 1,
      "pageSize": 3,
      "hasMore": false
    }
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

POST /api/v1/teams/{teamId}/categories

Create Category

Create a new article category. Slug is auto-generated from the name.

Requires a secret API key.

Request Body

name string required

Category display name

description string

Category description

icon string

Lucide icon name, such as "rocket" or "credit-card" (https://lucide.dev/icons). A name that is not an icon is rejected with a 400.

color string

Color value

sortOrder integer

Display order

Default: 0

isPublic boolean

Whether visible publicly

Default: false

Code Examples

bash

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/categories" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Getting Started", "isPublic": true }'

Responses

201 Category created

json

{
  "success": true,
  "data": {
    "id": "7134fc12-0302-4e58-9466-a770035d5da9",
    "object": "category",
    "name": "Getting Started",
    "slug": "getting-started",
    "description": null,
    "isPublic": false,
    "sortOrder": 0,
    "createdAt": "2025-12-10T14:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

409 Category with this slug already exists

json

{
  "success": false,
  "error": {
    "type": "conflict_error",
    "code": "CONFLICT",
    "message": "A category with slug \"getting-started\" already exists",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

PATCH /api/v1/teams/{teamId}/categories/{categoryId}

Update Category

Update one or more fields on an existing category. Only include the fields you want to change.

Requires a secret API key.

Path Parameters

categoryId string required

The category ID (UUID)

Request Body

name string

New name

description string

New description

icon string

Lucide icon name, such as "rocket" or "credit-card" (https://lucide.dev/icons). A name that is not an icon is rejected with a 400.

color string

New color

sortOrder integer

New sort order

isPublic boolean

New visibility

Code Examples

bash

curl -X PATCH "https://www.cstar.help/api/v1/teams/{teamId}/categories/{categoryId}" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated description", "isPublic": true }'

Responses

200 Updated category

json

{
  "success": true,
  "data": {
    "id": "7134fc12-0302-4e58-9466-a770035d5da9",
    "object": "category",
    "name": "Getting Started",
    "slug": "getting-started",
    "description": "Updated description",
    "isPublic": true,
    "updatedAt": "2025-12-10T16:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T16:00:00Z"
  }
}

404 Category not found

json

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Category not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

DELETE /api/v1/teams/{teamId}/categories/{categoryId}

Delete Category

Permanently delete a category. Articles in this category will become uncategorized.

Requires a secret API key. This is a destructive operation.

Path Parameters

categoryId string required

The category ID (UUID)

Code Examples

bash

curl -X DELETE "https://www.cstar.help/api/v1/teams/{teamId}/categories/{categoryId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Category deleted

json

{
  "success": true,
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Category not found

json

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Category not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}