Skip to main content

​
Overview

The Categories API lets you manage the colour-coded category labels that group your documents and tasks. Each category has a name, an emoji, and a colour, and is scoped to a single user. All endpoints are authenticated. Include a valid Auth0 access token in the Authorization header: 
Authorization: Bearer <ACCESS_TOKEN>
The API base URL is: 
https://adminest-backend.delightfulpebble-f95388de.eastus.azurecontainerapps.io

​
The Category object

FieldTypeNotes
_idstringMongoDB ObjectId for the category
userIdstringThe owning user. Inferred from the bearer token on create.
namestringDisplay name, up to 60 characters. Must be unique within a user.
emojistring | nullA single emoji (e.g. "🏥"). May be null for “no emoji”.
colorstring | nullA hex colour (#RRGGBB) used to tint the pill background. May be null to use the default neutral tone.
isSystembooleantrue for seed categories Adminest creates on signup. System categories can be renamed and restyled, but not deleted.
documentCountnumberRead-only. The number of documents currently tagged with this category.
taskCountnumberRead-only. The number of tasks currently tagged.
createdAtstringISO 8601 timestamp.
updatedAtstringISO 8601 timestamp.

​
Example

{
  "_id": "65f1c0a4f1a2b3c4d5e6f7a8",
  "userId": "65f1bff4f1a2b3c4d5e6f700",
  "name": "Insurance",
  "emoji": "🏥",
  "color": "#10b981",
  "isSystem": true,
  "documentCount": 9,
  "taskCount": 3,
  "createdAt": "2026-02-01T08:14:22.041Z",
  "updatedAt": "2026-05-12T19:03:08.918Z"
}
The emoji and color fields are new in V2. Categories created before V2 may return null for both — clients should treat that as “use the default neutral tint” and “no emoji”.

​
Endpoints

​
List categories

GET /api/categories
Returns every category for the authenticated user, including their documentCount and taskCount. 
curl -X GET https://adminest-backend.../api/categories \
  -H "Authorization: Bearer $TOKEN"
Response — 200 OK 
[
  {
    "_id": "65f1c0a4f1a2b3c4d5e6f7a8",
    "name": "Insurance",
    "emoji": "🏥",
    "color": "#10b981",
    "isSystem": true,
    "documentCount": 9,
    "taskCount": 3,
    "createdAt": "2026-02-01T08:14:22.041Z",
    "updatedAt": "2026-05-12T19:03:08.918Z"
  },
  {
    "_id": "65f1c0a4f1a2b3c4d5e6f7a9",
    "name": "Utilities",
    "emoji": "⚡",
    "color": "#f59e0b",
    "isSystem": true,
    "documentCount": 12,
    "taskCount": 2,
    "createdAt": "2026-02-01T08:14:22.041Z",
    "updatedAt": "2026-04-20T11:24:08.918Z"
  }
]

​
Create a category

POST /api/categories
Creates a new category for the authenticated user. name is required; emoji and color are optional. Request body 
{
  "name": "Pet",
  "emoji": "🐾",
  "color": "#db2777"
}
FieldTypeRequiredValidation
namestringyes1–60 chars; unique per user
emojistringnoA single emoji grapheme
colorstringnoHex colour #RRGGBB (lowercase or uppercase)
curl -X POST https://adminest-backend.../api/categories \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pet","emoji":"🐾","color":"#db2777"}'
Response — 201 Created 
{
  "_id": "65f1c0a4f1a2b3c4d5e6f7b1",
  "userId": "65f1bff4f1a2b3c4d5e6f700",
  "name": "Pet",
  "emoji": "🐾",
  "color": "#db2777",
  "isSystem": false,
  "documentCount": 0,
  "taskCount": 0,
  "createdAt": "2026-05-24T03:18:01.211Z",
  "updatedAt": "2026-05-24T03:18:01.211Z"
}
Errors
StatusWhen
400 Bad Requestname missing or longer than 60 chars; invalid color format; multiple emojis in emoji.
401 UnauthorizedMissing or invalid bearer token.
409 ConflictA category with this name already exists for the user.

​
Update a category

PUT /api/categories/:id
Updates the name, emoji, or colour of an existing category. This is the new endpoint introduced in V2 — previously you could only create or delete. You can update any combination of fields. Fields you don’t send are left unchanged. Request body 
{
  "name": "Pets",
  "emoji": "🐶",
  "color": "#7c3aed"
}
FieldTypeNotes
namestringOptional. 1–60 chars; must remain unique for the user.
emojistring | nullOptional. Send null to remove the emoji.
colorstring | nullOptional. Send null to use the default tint. Hex #RRGGBB.
curl -X PUT https://adminest-backend.../api/categories/65f1c0a4f1a2b3c4d5e6f7b1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pets","emoji":"🐶","color":"#7c3aed"}'
Response — 200 OK 
{
  "_id": "65f1c0a4f1a2b3c4d5e6f7b1",
  "userId": "65f1bff4f1a2b3c4d5e6f700",
  "name": "Pets",
  "emoji": "🐶",
  "color": "#7c3aed",
  "isSystem": false,
  "documentCount": 0,
  "taskCount": 0,
  "createdAt": "2026-05-24T03:18:01.211Z",
  "updatedAt": "2026-05-24T03:19:44.001Z"
}
Errors
StatusWhen
400 Bad RequestInvalid color, multiple emojis in emoji, or empty name.
401 UnauthorizedMissing or invalid bearer token.
403 ForbiddenAttempt to rename or restyle a system category in a forbidden way (e.g. unsetting required fields).
404 Not FoundThe category doesn’t exist or doesn’t belong to the authenticated user.
409 ConflictAnother category with that name already exists for the user.
System categories (created automatically when you signed up) can be renamed, recoloured, and re-emojied via this endpoint, but cannot be deleted.

​
Delete a category

DELETE /api/categories/:id
Removes a user-created category. Any documents or tasks that were tagged with it are un-tagged automatically. 
curl -X DELETE https://adminest-backend.../api/categories/65f1c0a4f1a2b3c4d5e6f7b1 \
  -H "Authorization: Bearer $TOKEN"
Response — 200 OK 
{
  "success": true,
  "deletedId": "65f1c0a4f1a2b3c4d5e6f7b1"
}
Errors
StatusWhen
401 UnauthorizedMissing or invalid bearer token.
403 ForbiddenThe category is a system category (isSystem: true). System categories cannot be deleted.
404 Not FoundThe category doesn’t exist or doesn’t belong to the authenticated user.

​
Suggest categories for a document

POST /api/categories/suggest
Returns AI-ranked category suggestions for a document, based on its content and the user’s existing categories. Suggestions are advisory — the client decides whether to apply them. Request body 
{
  "documentData": {
    "title": "AA Insurance — home and contents renewal",
    "summary": "Annual renewal notice for home and contents policy…",
    "type": "insurance"
  }
}
Response — 200 OK 
[
  { "categoryId": "65f1c0a4f1a2b3c4d5e6f7a8", "name": "Insurance", "score": 0.94 },
  { "categoryId": "65f1c0a4f1a2b3c4d5e6f7c2", "name": "Property", "score": 0.61 }
]
AI-suggested categories are not enabled for every account yet. When the feature is off, this endpoint returns an empty array.

​
Field validation reference

​
color

Adminest validates the colour as a hex string in the #RRGGBB form. Both uppercase and lowercase digits are accepted. 
✅  #08B7F0
✅  #10b981
❌  #08B7F  (too short)
❌  rgb(8, 183, 240)  (not hex)
❌  blue  (not hex)
If you send null (or omit the field on create), Adminest uses a neutral grey tint when rendering the category.

​
emoji

The emoji field accepts a single emoji grapheme, including emoji that are technically multiple codepoints (e.g. "👨‍👩‍👧"). Plain text is rejected. 
✅  "🏥"
✅  "👨‍👩‍👧"
❌  "Insurance"      (not an emoji)
❌  "🏥🛡️"          (two emojis)
Send null (or omit on create) for “no emoji”.

Documents

Apply categories from the UI

Categories guide

User-facing guide to managing categories