Skip to main content

​
Overview

Category endpoints allow you to manage event categories programmatically. Categories organize your events and define their visual appearance (color, emoji) in notifications.
These endpoints use Hono.js server procedures and require authentication via session cookies (not Bearer tokens). They are primarily used by the PingPilot web dashboard.

​
Get Event Categories

Retrieve all event categories for the authenticated user. 
GET /api/category/getEventCategories

​
Response

​
categories
array
Array of category objects with event statistics.
​
categories[].id
string
Unique category identifier.
​
categories[].name
string
Category name (lowercase, alphanumeric with hyphens).
​
categories[].emoji
string
Emoji icon for the category.
​
categories[].color
number
Integer color code (e.g., 16711680 for red).
​
categories[].uniqueFieldCount
number
Number of unique field keys used in events this month.
​
categories[].eventsCount
number
Total events in this category for current month.
​
categories[].lastPing
string
ISO timestamp of most recent event, or null if no events.
​
categories[].createdAt
string
ISO timestamp when category was created.
​
categories[].updatedAt
string
ISO timestamp when category was last updated.

​
Example Response

{
  "categories": [
    {
      "id": "cat_clx1234567890",
      "name": "bug",
      "emoji": "🐛",
      "color": 16711680,
      "uniqueFieldCount": 5,
      "eventsCount": 23,
      "lastPing": "2026-03-06T10:30:00.000Z",
      "createdAt": "2026-03-01T00:00:00.000Z",
      "updatedAt": "2026-03-05T15:20:00.000Z"
    },
    {
      "id": "cat_clx0987654321",
      "name": "sale",
      "emoji": "💰",
      "color": 4294944000,
      "uniqueFieldCount": 3,
      "eventsCount": 15,
      "lastPing": "2026-03-06T09:15:00.000Z",
      "createdAt": "2026-03-01T00:00:00.000Z",
      "updatedAt": "2026-03-01T00:00:00.000Z"
    }
  ]
}

​
Create Event Category

Create a new event category. 
POST /api/categories

​
Request Body

​
name
string
required
Category name. Must be unique for your account.Validation:
  • Required field
  • Must contain only letters, numbers, or hyphens
  • Automatically converted to lowercase
Pattern: /^[a-zA-Z0-9-]+$/
​
color
string
required
Hex color code for the category.Validation:
  • Required field
  • Must be valid hex format: #RRGGBB
  • Case insensitive
Pattern: /^#[0-9A-F]{6}$/iExample: "#FF0000", "#00ff00"
​
emoji
string
Emoji icon for the category.Validation:
  • Must be a valid emoji character
  • Single emoji only
Example: "🐛", "💰", "🤔"

​
Request Example

{
  "name": "payment-failed",
  "color": "#FF6B6B",
  "emoji": "💳"
}

​
Response

​
message
string
Success or error message.
​
success
boolean
Whether the operation succeeded.
​
data
object
Created category object (on success).

​
Success Response

{
  "message": "Category created",
  "success": true,
  "data": {
    "id": "cat_clx1234567890",
    "name": "payment-failed",
    "color": 16737099,
    "emoji": "💳",
    "userId": "user_123",
    "createdAt": "2026-03-06T10:30:00.000Z",
    "updatedAt": "2026-03-06T10:30:00.000Z"
  }
}

​
Error Response

{
  "message": "Failed to create category",
  "success": false
}

​
Delete Category

Delete an event category and all its events. 
DELETE /api/categories
Deleting a category permanently removes all events in that category. This action cannot be undone.

​
Request Body

​
name
string
required
Name of the category to delete.

​
Request Example

{
  "name": "old-category"
}

​
Response

​
message
string
Success or error message.
​
success
boolean
Whether the operation succeeded.

​
Success Response

{
  "message": "Category deleted",
  "success": true
}

​
Error Response

{
  "message": "Category not found",
  "success": false
}

​
Poll Category

Check if a category has received any events. 
GET /api/category/getEventCategories/poll?name={categoryName}

​
Query Parameters

​
name
string
required
Category name to check.

​
Response

​
hasEvents
boolean
Whether the category has received any events.

​
Success Response

{
  "hasEvents": true
}

​
Error Response

Status Code: 404 Not Found 
{
  "message": "Category \"nonexistent\" not found"
}

​
Insert Quickstart Categories

Create default starter categories for new users. 
POST /api/categories/quickstart

​
Response

​
success
boolean
Whether the operation succeeded.
​
count
number
Number of categories created.

​
Success Response

Creates three default categories:
  • bug (🐛, red: #ff6b6b)
  • sale (💰, yellow: #ffeb3b)
  • question (🤔, purple: #6c5ce7)
{
  "success": true,
  "count": 3
}

​
Category Name Validation

Category names must follow these rules:
Valid characters: Letters (a-z, A-Z), numbers (0-9), hyphens (-)
Case: Automatically converted to lowercase
Length: At least 1 character
Uniqueness: Must be unique per user account

​
Valid Examples

  • bug
  • sale
  • user-signup
  • payment-failed
  • api-error-500

​
Invalid Examples

  • user signup (contains space)
  • payment_failed (contains underscore)
  • critical! (contains special character)
  • “ (empty string)

​
Plan Limits

The number of categories you can create is limited by your plan:
  • Free: 3 categories
  • Pro: 10 categories
  • Enterprise: 100 categories
Attempting to create more categories than your plan allows will fail.

Build docs developers (and LLMs) love

Get started for freeTalk to us