Categories
Categories tools exposed over the SuperBooks MCP API.
The categories domain exposes 4 tools, 1 of which is destructive.
Destructive tools are hidden from tools/list unless the credential holds
apis.all and the team has enabled destructive AI tools. See
Authentication.
Tools
categories_create
Scope tier: write
Create a new transaction category for the current team. Name is required; all other fields are optional. The slug is derived from the name (lowercase, non-alphanumeric -> underscore, capped at 64 chars). Slugs must be unique per team — creating a category with a name that slugifies to an existing slug will throw a unique-constraint error. To nest under a parent, pass parent_id (the UUID id of an existing category). Returns the created row.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Human-readable category name (e.g., 'Office Supplies'). The slug is auto-generated from this — pick something stable. |
color | string (nullable) | no | Optional hex color for UI display (e.g., '#FF0000'). Pass null or omit if not needed. |
description | string (nullable) | no | Optional free-text description of what this category covers (helps the LLM auto-classify transactions). |
parent_id | string (uuid, nullable) | no | Optional UUID id of a parent category to nest under. Pass null or omit for a top-level category. Use categories_list to find existing category ids. |
tax_rate | number (nullable) | no | Optional tax rate as a percentage (e.g., 7.5 for 7.5%). Stored with 2-decimal precision. |
tax_type | string (nullable) | no | Optional tax type code (e.g., 'GST', 'VAT', 'sales_tax'). |
tax_reporting_code | string (nullable) | no | Optional reporting/jurisdiction code for the tax authority's tax line. |
excluded | boolean | no | If true, transactions in this category are excluded from financial reports (e.g., transfers between own accounts). Defaults to false. |
categories_delete
Scope tier: destructive · Destructive — requires the two-gate check
Permanently delete a transaction category. DESTRUCTIVE. REFUSES if the category is a system category (system: true). REFUSES if any transactions still reference the category (by slug) — re-categorize or delete those transactions first, then retry. Side-effects on success: any saved enrichment rules that reference this category are also deleted. Child categories are NOT auto-deleted and will keep pointing at the removed parent — re-nest or delete the children first if that matters. Returns deleted: false if the category was not found OR was refused; an error is thrown for refusals so the caller can distinguish. Confirm with the user before calling.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Category id (UUID) to delete. This action is permanent. |
categories_list
Scope tier: read
List all transaction categories for the current team. Returns a FLAT array (not hierarchical) — each row includes parent_id so the caller can reconstruct the parent/child tree if needed. System categories (system: true) are included; they cannot be updated or deleted. Ordered by system DESC, name ASC. No pagination — the full category catalog is typically small.
No parameters.
categories_update
Scope tier: write
Update one transaction category. Only the fields you pass are modified; omit a field to leave it untouched. REFUSES to update a system category (system: true). REFUSES to change parent_id on a category that has children — re-nest the children first. The slug is NOT updatable (it is part of the composite primary key); to rename, create a new category and migrate transactions. Returns updated: true on success.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Category id (UUID) to update. Use categories_list to find it. |
name | string | no | New human-readable name. The slug does NOT change when name changes. |
color | string (nullable) | no | Hex color for UI display. Pass null to clear. |
description | string (nullable) | no | Free-text description. Pass null to clear. |
parent_id | string (uuid, nullable) | no | Parent category UUID id. Pass null to make top-level. Refused if this category already has children. |
tax_rate | number (nullable) | no | Tax rate percentage (e.g., 7.5 for 7.5%). Pass null to clear. |
tax_type | string (nullable) | no | Tax type code (e.g., 'GST', 'VAT'). Pass null to clear. |
tax_reporting_code | string (nullable) | no | Reporting/jurisdiction code. Pass null to clear. |
excluded | boolean (nullable) | no | If true, this category is excluded from financial reports. Pass null to revert to default (false). |