Categories API

Categories help organize acronyms by department, function, or topic. Each category has a name, slug, and color. Definitions are assigned to categories.

GET /api/v1/categories

Returns all categories in your workspace with definition counts.

Query Parameters

None.

Response

{
  "success": true,
  "data": [
    {
      "id": "cat_001",
      "name": "Technology",
      "slug": "technology",
      "color": "#FF6B6B",
      "description": "Technical terms and acronyms",
      "definitionCount": 42,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-10T08:00:00Z"
    },
    {
      "id": "cat_002",
      "name": "Management",
      "slug": "management",
      "color": "#4ECDC4",
      "description": "Management frameworks and processes",
      "definitionCount": 18,
      "createdAt": "2024-01-10T09:30:00Z",
      "updatedAt": "2024-01-10T09:30:00Z"
    },
    {
      "id": "cat_003",
      "name": "Marketing",
      "slug": "marketing",
      "color": "#FFE66D",
      "description": null,
      "definitionCount": 12,
      "createdAt": "2024-01-12T11:15:00Z",
      "updatedAt": "2024-01-12T11:15:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique category ID (prefixed with `cat_`)
name	string	Display name
slug	string	URL-safe identifier (lowercase, hyphenated)
color	string	Hex color code for UI display
description	string \| null	Optional description
definitionCount	number	Number of definitions in this category
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 update timestamp

Example

curl https://engineering.define.wtf/api/v1/categories \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Create Category

POST /api/v1/categories

Creates a new category. If no color is provided, one is automatically assigned from the workspace's color palette.

Request Body

{
  "name": "Sales",
  "color": "#A78BFA",
  "description": "Sales processes and terminology"
}

Body Parameters

Field	Type	Required	Max Length	Description
name	string	Yes	100	Category name
color	string	No	—	Hex color code (e.g., `#FF6B6B`)
description	string	No	500	Optional description

Response

Returns 201 Created:

{
  "success": true,
  "data": {
    "id": "cat_004",
    "name": "Sales",
    "slug": "sales",
    "color": "#A78BFA",
    "description": "Sales processes and terminology",
    "definitionCount": 0,
    "createdAt": "2024-01-21T16:45:00Z",
    "updatedAt": "2024-01-21T16:45:00Z"
  }
}

Color Assignment

If you omit the color field, the API automatically selects an unused color from a vivid 16-color palette:

#FF6B6B (red), #4ECDC4 (teal), #FFE66D (yellow), #A78BFA (purple),
#FF8C42 (orange), #6BCB77 (green), #4D96FF (blue), #FF69B4 (pink),
#00CED1 (cyan), #FFD700 (gold), #20B2AA (light sea green), #FF4500 (orange-red),
#32CD32 (lime green), #9932CC (dark orchid), #FF1493 (deep pink), #00BFFF (deep sky blue)

The system tracks which colors are in use and picks the first available one. This ensures visual variety and consistency.

Permissions

category:manage required
Typically available to admins and owners

Examples

Create with custom color:

curl -X POST https://engineering.define.wtf/api/v1/categories \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#A78BFA",
    "description": "Sales processes and terminology"
  }'

Create with auto-assigned color:

curl -X POST https://engineering.define.wtf/api/v1/categories \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal"
  }'

Update Category

PATCH /api/v1/categories/{id}

Updates a category's name, color, or description.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Category ID (e.g., `cat_001`)

Request Body

{
  "name": "Technology & Innovation",
  "color": "#FF8C42",
  "description": "Updated description"
}

Body Parameters

Field	Type	Description
name	string	New category name
color	string	New hex color code
description	string	New description

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "id": "cat_001",
    "name": "Technology & Innovation",
    "slug": "technology-innovation",
    "color": "#FF8C42",
    "description": "Updated description",
    "definitionCount": 42,
    "updatedAt": "2024-01-21T17:00:00Z"
  }
}

Note on Slug

The slug is automatically regenerated from the name. Special characters are removed, spaces become hyphens:

"Technology & Innovation" → technology-innovation
"Sales / Marketing" → sales-marketing

Example

curl -X PATCH https://engineering.define.wtf/api/v1/categories/cat_001 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technology & Innovation",
    "color": "#FF8C42"
  }'

Delete Category

DELETE /api/v1/categories/{id}

Deletes a category. All definitions remain; only their category assignment is removed.

Parameters

Parameter	Type	Required	Description
id	string	Yes	Category ID

Response

Returns 204 No Content (no response body).

Example

curl -X DELETE https://engineering.define.wtf/api/v1/categories/cat_001 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Behavior

When a category is deleted:

Definitions previously in that category are unassigned
Acronyms still exist with their other categories intact
The category is removed from all definition/acronym listings

Category Fields Reference

Field	Type	Description
id	string	Unique identifier (prefixed `cat_`)
name	string	Display name (1-100 chars)
slug	string	URL-safe slug (derived from name)
color	string	Hex color code for UI
description	string \| null	Optional description
definitionCount	number	Number of definitions tagged with this category
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 update timestamp

Error Responses

Category not found (404):

{
  "success": false,
  "error": {
    "code": "CATEGORY_NOT_FOUND",
    "message": "Category not found"
  }
}

Duplicate category name (409):

{
  "success": false,
  "error": {
    "code": "DUPLICATE_CATEGORY",
    "message": "A category with this name already exists"
  }
}

Profanity detected (400):

{
  "success": false,
  "error": {
    "code": "PROFANITY_DETECTED",
    "message": "Content contains inappropriate language",
    "details": {
      "fields": ["name"]
    }
  }
}

Invalid color format (400):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "color": ["Invalid hex color code. Use format #RRGGBB"]
    }
  }
}

Insufficient permissions (403):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to manage categories"
  }
}

Using Categories

In Acronym Creation

When creating or updating an acronym, assign it to categories:

curl -X POST https://engineering.define.wtf/api/v1/acronyms \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "term": "API",
    "title": "Application Programming Interface",
    "categoryIds": ["cat_001", "cat_002"]
  }'

Filtering by Category

List acronyms in a specific category:

curl "https://engineering.define.wtf/api/v1/acronyms?category=technology" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Or search within a category:

curl "https://engineering.define.wtf/api/v1/search?q=framework&category=technology" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Categories

On this page