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

Icon identifier

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

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

Responses

200 List of categories

{
  "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

{
  "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

{
  "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

{
  "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

Icon identifier

color string

Color value

sortOrder integer

Display order

Default: 0

isPublic boolean

Whether visible publicly

Default: false

Code Examples

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

New icon

color string

New color

sortOrder integer

New sort order

isPublic boolean

New visibility

Code Examples

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

Responses

200 Category deleted

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

404 Category not found

{
  "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

{
  "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

{
  "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

{
  "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"
  }
}