Categories API - Adminest

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

Field	Type	Notes
`_id`	string	MongoDB ObjectId for the category
`userId`	string	The owning user. Inferred from the bearer token on create.
`name`	string	Display name, up to 60 characters. Must be unique within a user.
`emoji`	string \| null	A single emoji (e.g. `"🏥"`). May be `null` for “no emoji”.
`color`	string \| null	A hex colour (`#RRGGBB`) used to tint the pill background. May be `null` to use the default neutral tone.
`isSystem`	boolean	`true` for seed categories Adminest creates on signup. System categories can be renamed and restyled, but not deleted.
`documentCount`	number	Read-only. The number of documents currently tagged with this category.
`taskCount`	number	Read-only. The number of tasks currently tagged.
`createdAt`	string	ISO 8601 timestamp.
`updatedAt`	string	ISO 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

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"

const res = await fetch('https://adminest-backend.../api/categories', {
  headers: { Authorization: `Bearer ${token}` },
});
const categories = await res.json();

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

Field	Type	Required	Validation
`name`	string	yes	1–60 chars; unique per user
`emoji`	string	no	A single emoji grapheme
`color`	string	no	Hex 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"}'

const res = await fetch('https://adminest-backend.../api/categories', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Pet', emoji: '🐾', color: '#db2777' }),
});
const category = await res.json();

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

Status	When
`400 Bad Request`	`name` missing or longer than 60 chars; invalid `color` format; multiple emojis in `emoji`.
`401 Unauthorized`	Missing or invalid bearer token.
`409 Conflict`	A 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"
}

Field	Type	Notes
`name`	string	Optional. 1–60 chars; must remain unique for the user.
`emoji`	string \| null	Optional. Send `null` to remove the emoji.
`color`	string \| null	Optional. 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"}'

const res = await fetch(
  `https://adminest-backend.../api/categories/${id}`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Pets', emoji: '🐶', color: '#7c3aed' }),
  }
);
const updated = await res.json();

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

Status	When
`400 Bad Request`	Invalid `color`, multiple emojis in `emoji`, or empty `name`.
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	Attempt to rename or restyle a system category in a forbidden way (e.g. unsetting required fields).
`404 Not Found`	The category doesn’t exist or doesn’t belong to the authenticated user.
`409 Conflict`	Another 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

Status	When
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	The category is a system category (`isSystem: true`). System categories cannot be deleted.
`404 Not Found`	The 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

​Overview

​The Category object

​Example

​Endpoints

​List categories

​Create a category

​Update a category

​Delete a category

​Suggest categories for a document

​Field validation reference

​color

​emoji

​Related

Documents

Categories guide

Overview

The Category object

Example

Endpoints

List categories

Create a category

Update a category

Delete a category

Suggest categories for a document

Field validation reference

`color`

`emoji`

Related