Categories & Tags API Reference

Organize and segment email aliases into categorized folders, apply color tokens, manage sort hierarchies, and automate alias migrations.

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/categories`	`GET`	`categories:read`	List all categories with live alias member counts and account quota limits.
`/v1/categories`	`POST`	`categories:write`	Create a new category with automated slug generation and theme color.
`/v1/categories/:id`	`GET`	`categories:read`	Retrieve single category details and metadata.
`/v1/categories/:id`	`PATCH`	`categories:write`	Update category name, color token, icon, sort order, or default designation.
`/v1/categories/:id`	`DELETE`	`categories:write`	Delete category and atomically migrate member aliases to the default category.
`/v1/categories/reorder`	`POST`	`categories:write`	Reorder category display hierarchy in a single atomic request.

Plan Quotas & Tier Limits#

Tier	Maximum Categories (`maxCategories`)	Behavior When Limit Reached
Free	5 categories	Returns HTTP `403 LIMIT_REACHED` (`"Maximum 5 categories allowed on your current plan."`).
Pro	15 categories	Returns HTTP `403 LIMIT_REACHED` (`"Maximum 15 categories allowed on your current plan."`).
Business	Unlimited (`-1`)	Unrestricted category creation (`maxCategories: -1`).

Category Taxonomy & Structure#

Categories allow organizing email aliases across departments, projects, clients, or security tiers:

MERMAID

flowchart TD    A["User Account"] --> B["Category: Finance (#10b981)"]    A --> C["Category: Security & DevOps (#6366f1)"]    A --> D["Category: General (Default)"]    B --> E["Alias: billing@..."]    B --> F["Alias: invoices@..."]    C --> G["Alias: alerts@..."]    D --> H["Alias: support@..."]

Key Attributes#

Identifier Format: Standard RFC 4122 UUIDs (e.g. b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d).
Color Tokens: Standard hex color strings (e.g. #10b981, #6366f1, #f59e0b) used for UI badge accents.
Icon Tokens: Lucide icon names (e.g. folder, credit-card, shield, shopping-bag, terminal).
Default Category: Every account has exactly one default category (is_default: true). When an alias is created without an explicit category_id, it is assigned to the default category.

GET /v1/categories

Retrieves all organizational categories created for the authenticated account, ordered by ascending sort_order, along with live alias count metrics and plan allowances.

Scope: categories:readRate Limit: 60 req/minIdempotent: Yes

Request Headers#

Header	Type	Required	Description
`Authorization`	`string`	Optional*	`Bearer afp_...`
`x-api-key`	`string`	Optional*	`afp_...` (*Provide either `Authorization` or `x-api-key`).
`Accept`	`string`	Yes	`application/json`

cURL Example#

Terminal

curl -X GET "https://api.aliasfleet.com/v1/categories" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "categories": [    {      "id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",      "name": "General",      "slug": "general",      "color": "#6366f1",      "icon": "folder",      "is_default": true,      "alias_count": 48    },    {      "id": "c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",      "name": "Finance & Banking",      "slug": "finance-banking",      "color": "#10b981",      "icon": "credit-card",      "is_default": false,      "alias_count": 12    }  ],  "maxCategories": 15}

Response Fields#

Field	Type	Description
`categories`	`array`	List of category objects belonging to the account.
`categories[].id`	`string (UUID)`	Unique category identifier.
`categories[].name`	`string`	Display name of the category.
`categories[].slug`	`string`	Normalized URL-safe slug.
`categories[].color`	`string`	Hex color code for UI rendering.
`categories[].icon`	`string`	Icon token identifier.
`categories[].is_default`	`boolean`	Whether this is the fallback category for new or unassigned aliases.
`categories[].alias_count`	`integer`	Total count of active aliases currently assigned to this category.
`maxCategories`	`integer`	Maximum number of categories allowed under the current account plan (`-1` indicates unlimited).

Create Category#

POST /v1/categories

Provisions a new category folder, generates a normalized slug, validates account plan quotas, and appends the category to the end of the sort sequence.

Scope: categories:writeRate Limit: 30 req/minIdempotent: No

Request Body Schema#

Field	Type	Required	Constraints	Description
`name`	`string`	Yes	1–50 characters	Category display name (e.g. `"Developer Tools"`).
`color`	`string`	Optional	Valid hex color	UI badge color (Default: `"#6366f1"`).
`icon`	`string`	Optional	Icon token	Lucide icon identifier (Default: `"folder"`).

cURL Example#

Terminal

curl -X POST "https://api.aliasfleet.com/v1/categories" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "name": "Developer Tools",    "color": "#8b5cf6",    "icon": "terminal"  }'

Response (`201 Created`)#

JSON

{  "success": true,  "category": {    "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",    "name": "Developer Tools",    "slug": "developer-tools",    "color": "#8b5cf6",    "icon": "terminal",    "is_default": false,    "alias_count": 0  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`VALIDATION_ERROR`	`"Invalid input"`	Name is missing or exceeds 50 characters.
`403`	`LIMIT_REACHED`	`"Maximum 5 categories allowed on your current plan."`	Account plan category limit reached.
`409`	`DUPLICATE_CATEGORY`	`"A category with this name already exists"`	A category with the same normalized slug already exists.

Get Category by ID#

GET /v1/categories/:id

Retrieves detailed metadata for a specific category.

Scope: categories:readRate Limit: 60 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string (UUID)`	Yes	Unique category identifier.

cURL Example#

Terminal

curl -X GET "https://api.aliasfleet.com/v1/categories/b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "category": {    "id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Finance & Banking",    "slug": "finance-banking",    "color": "#10b981",    "icon": "credit-card",    "sort_order": 1,    "is_default": false,    "created_at": "2026-08-01T10:00:00.000Z",    "updated_at": "2026-09-01T14:30:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`401`	`UNAUTHORIZED`	`"Unauthorized"`	Missing or invalid API key.
`403`	`INSUFFICIENT_SCOPES`	`"Forbidden: Insufficient scopes"`	Token lacks `categories:read`.
`404`	`NOT_FOUND`	`"Category not found"`	Category ID does not exist or belongs to another account.

Update Category#

PATCH /v1/categories/:id

Modifies category properties. When is_default is set to true, the previous default category is automatically designated as non-default within an atomic transaction.

Scope: categories:writeRate Limit: 30 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string (UUID)`	Yes	Unique category identifier.

Request Body Schema#

Field	Type	Required	Description
`name`	`string`	Optional	Updated category display name (1–50 chars). Also updates the slug.
`color`	`string`	Optional	Updated hex color code.
`icon`	`string`	Optional	Updated Lucide icon identifier.
`sort_order`	`integer`	Optional	Custom integer position for display ordering.
`is_default`	`boolean`	Optional	Designate this category as the account default.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/categories/c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "name": "Accounting & Treasury",    "color": "#059669"  }'

Response (`200 OK`)#

JSON

{  "category": {    "id": "c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Accounting & Treasury",    "slug": "accounting-treasury",    "color": "#059669",    "icon": "credit-card",    "sort_order": 1,    "is_default": false,    "created_at": "2026-08-01T10:00:00.000Z",    "updated_at": "2026-09-05T12:00:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`NO_UPDATES`	`"No fields to update"`	Request payload contains no recognized update fields.
`404`	`NOT_FOUND`	`"Category not found"`	Target category ID does not exist.
`409`	`DUPLICATE_CATEGORY`	`"A category with this name already exists"`	Updating the name creates a slug collision with another category.

Delete Category#

DELETE /v1/categories/:id

Deletes an existing category. All aliases currently assigned to this category are automatically migrated to your account's default category.

Warning

Default Category Protection: The default category (is_default: true) cannot be deleted. If you attempt to delete it, the API will reject the request with HTTP 400 CANNOT_DELETE_DEFAULT. Set another category as default before deletion.

Scope: categories:writeRate Limit: 30 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string (UUID)`	Yes	Unique category identifier.

cURL Example#

Terminal

curl -X DELETE "https://api.aliasfleet.com/v1/categories/c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (`200 OK`)#

JSON

{  "success": true,  "movedAliasesCount": 12}

Response Fields#

Field	Type	Description
`success`	`boolean`	Confirms successful removal of the category record.
`movedAliasesCount`	`integer`	Total number of aliases migrated to your default category.

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`CANNOT_DELETE_DEFAULT`	`"Cannot delete the default category. Set another category as default first."`	Attempted deletion of the active default category.
`404`	`NOT_FOUND`	`"Category not found"`	Target category ID does not exist.
`500`	`DEFAULT_CATEGORY_MISSING`	`"Default category not found"`	System was unable to resolve a fallback default category.

Reorder Categories#

POST /v1/categories/reorder

Atomically updates the sort sequence of all account categories based on the provided array of IDs.

Scope: categories:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema#

Field	Type	Required	Description
`categoryIds`	`string[]`	Yes	Array of category UUIDs in desired sequential order.

cURL Example#

Terminal

curl -X POST "https://api.aliasfleet.com/v1/categories/reorder" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "categoryIds": [      "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",      "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",      "c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"    ]  }'

Response (`200 OK`)#

JSON

{  "success": true}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`INVALID_CATEGORY_IDS`	`"Some category IDs are invalid or do not belong to you"`	One or more provided IDs do not belong to the authenticated account.
`401`	`UNAUTHORIZED`	`"Unauthorized"`	Missing or invalid authentication.
`403`	`INSUFFICIENT_SCOPES`	`"Forbidden: Insufficient scopes"`	Token lacks `categories:write`.

Frequently Asked Questions

When a category is deleted, all member aliases are automatically and atomically migrated to your account's default category. No aliases are orphaned or deleted.

No. The default category cannot be deleted. To delete a category that is currently set as default, you must first designate another category as the default.

Category slugs are automatically derived from the category name by converting characters to lowercase, replacing special characters with hyphens, and stripping leading or trailing hyphens.

Yes. Category slugs must be unique within your account. Attempting to create a category that produces an existing slug returns an HTTP 409 DUPLICATE_CATEGORY error.

Organize and segment email aliases into categorized folders, apply color tokens, manage sort hierarchies, and automate alias migrations.

Quick Reference#

Endpoint	Method	Required Scope	Description
`/v1/categories`	`GET`	`categories:read`	List all categories with live alias member counts and account quota limits.
`/v1/categories`	`POST`	`categories:write`	Create a new category with automated slug generation and theme color.
`/v1/categories/:id`	`GET`	`categories:read`	Retrieve single category details and metadata.
`/v1/categories/:id`	`PATCH`	`categories:write`	Update category name, color token, icon, sort order, or default designation.
`/v1/categories/:id`	`DELETE`	`categories:write`	Delete category and atomically migrate member aliases to the default category.
`/v1/categories/reorder`	`POST`	`categories:write`	Reorder category display hierarchy in a single atomic request.

Plan Quotas & Tier Limits#

Tier	Maximum Categories (`maxCategories`)	Behavior When Limit Reached
Free	5 categories	Returns HTTP `403 LIMIT_REACHED` (`"Maximum 5 categories allowed on your current plan."`).
Pro	15 categories	Returns HTTP `403 LIMIT_REACHED` (`"Maximum 15 categories allowed on your current plan."`).
Business	Unlimited (`-1`)	Unrestricted category creation (`maxCategories: -1`).

Category Taxonomy & Structure#

Categories allow organizing email aliases across departments, projects, clients, or security tiers:

MERMAID

flowchart TD    A["User Account"] --> B["Category: Finance (#10b981)"]    A --> C["Category: Security & DevOps (#6366f1)"]    A --> D["Category: General (Default)"]    B --> E["Alias: billing@..."]    B --> F["Alias: invoices@..."]    C --> G["Alias: alerts@..."]    D --> H["Alias: support@..."]

Key Attributes#

Identifier Format: Standard RFC 4122 UUIDs (e.g. b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d).
Color Tokens: Standard hex color strings (e.g. #10b981, #6366f1, #f59e0b) used for UI badge accents.
Icon Tokens: Lucide icon names (e.g. folder, credit-card, shield, shopping-bag, terminal).
Default Category: Every account has exactly one default category (is_default: true). When an alias is created without an explicit category_id, it is assigned to the default category.

GET /v1/categories

Retrieves all organizational categories created for the authenticated account, ordered by ascending sort_order, along with live alias count metrics and plan allowances.

Scope: categories:readRate Limit: 60 req/minIdempotent: Yes

Request Headers#

Header	Type	Required	Description
`Authorization`	`string`	Optional*	`Bearer afp_...`
`x-api-key`	`string`	Optional*	`afp_...` (*Provide either `Authorization` or `x-api-key`).
`Accept`	`string`	Yes	`application/json`

cURL Example#

Terminal

curl -X GET "https://api.aliasfleet.com/v1/categories" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "categories": [    {      "id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",      "name": "General",      "slug": "general",      "color": "#6366f1",      "icon": "folder",      "is_default": true,      "alias_count": 48    },    {      "id": "c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",      "name": "Finance & Banking",      "slug": "finance-banking",      "color": "#10b981",      "icon": "credit-card",      "is_default": false,      "alias_count": 12    }  ],  "maxCategories": 15}

Response Fields#

Field	Type	Description
`categories`	`array`	List of category objects belonging to the account.
`categories[].id`	`string (UUID)`	Unique category identifier.
`categories[].name`	`string`	Display name of the category.
`categories[].slug`	`string`	Normalized URL-safe slug.
`categories[].color`	`string`	Hex color code for UI rendering.
`categories[].icon`	`string`	Icon token identifier.
`categories[].is_default`	`boolean`	Whether this is the fallback category for new or unassigned aliases.
`categories[].alias_count`	`integer`	Total count of active aliases currently assigned to this category.
`maxCategories`	`integer`	Maximum number of categories allowed under the current account plan (`-1` indicates unlimited).

Create Category#

POST /v1/categories

Provisions a new category folder, generates a normalized slug, validates account plan quotas, and appends the category to the end of the sort sequence.

Scope: categories:writeRate Limit: 30 req/minIdempotent: No

Request Body Schema#

Field	Type	Required	Constraints	Description
`name`	`string`	Yes	1–50 characters	Category display name (e.g. `"Developer Tools"`).
`color`	`string`	Optional	Valid hex color	UI badge color (Default: `"#6366f1"`).
`icon`	`string`	Optional	Icon token	Lucide icon identifier (Default: `"folder"`).

cURL Example#

Terminal

curl -X POST "https://api.aliasfleet.com/v1/categories" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "name": "Developer Tools",    "color": "#8b5cf6",    "icon": "terminal"  }'

Response (`201 Created`)#

JSON

{  "success": true,  "category": {    "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",    "name": "Developer Tools",    "slug": "developer-tools",    "color": "#8b5cf6",    "icon": "terminal",    "is_default": false,    "alias_count": 0  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`VALIDATION_ERROR`	`"Invalid input"`	Name is missing or exceeds 50 characters.
`403`	`LIMIT_REACHED`	`"Maximum 5 categories allowed on your current plan."`	Account plan category limit reached.
`409`	`DUPLICATE_CATEGORY`	`"A category with this name already exists"`	A category with the same normalized slug already exists.

Get Category by ID#

GET /v1/categories/:id

Retrieves detailed metadata for a specific category.

Scope: categories:readRate Limit: 60 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string (UUID)`	Yes	Unique category identifier.

cURL Example#

Terminal

curl -X GET "https://api.aliasfleet.com/v1/categories/b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Accept: application/json"

Response (`200 OK`)#

JSON

{  "category": {    "id": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Finance & Banking",    "slug": "finance-banking",    "color": "#10b981",    "icon": "credit-card",    "sort_order": 1,    "is_default": false,    "created_at": "2026-08-01T10:00:00.000Z",    "updated_at": "2026-09-01T14:30:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`401`	`UNAUTHORIZED`	`"Unauthorized"`	Missing or invalid API key.
`403`	`INSUFFICIENT_SCOPES`	`"Forbidden: Insufficient scopes"`	Token lacks `categories:read`.
`404`	`NOT_FOUND`	`"Category not found"`	Category ID does not exist or belongs to another account.

Update Category#

PATCH /v1/categories/:id

Modifies category properties. When is_default is set to true, the previous default category is automatically designated as non-default within an atomic transaction.

Scope: categories:writeRate Limit: 30 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string (UUID)`	Yes	Unique category identifier.

Request Body Schema#

Field	Type	Required	Description
`name`	`string`	Optional	Updated category display name (1–50 chars). Also updates the slug.
`color`	`string`	Optional	Updated hex color code.
`icon`	`string`	Optional	Updated Lucide icon identifier.
`sort_order`	`integer`	Optional	Custom integer position for display ordering.
`is_default`	`boolean`	Optional	Designate this category as the account default.

cURL Example#

Terminal

curl -X PATCH "https://api.aliasfleet.com/v1/categories/c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "name": "Accounting & Treasury",    "color": "#059669"  }'

Response (`200 OK`)#

JSON

{  "category": {    "id": "c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",    "user_id": "d3b07384-d113-4674-bc50-a88981298418",    "name": "Accounting & Treasury",    "slug": "accounting-treasury",    "color": "#059669",    "icon": "credit-card",    "sort_order": 1,    "is_default": false,    "created_at": "2026-08-01T10:00:00.000Z",    "updated_at": "2026-09-05T12:00:00.000Z"  }}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`NO_UPDATES`	`"No fields to update"`	Request payload contains no recognized update fields.
`404`	`NOT_FOUND`	`"Category not found"`	Target category ID does not exist.
`409`	`DUPLICATE_CATEGORY`	`"A category with this name already exists"`	Updating the name creates a slug collision with another category.

Delete Category#

DELETE /v1/categories/:id

Deletes an existing category. All aliases currently assigned to this category are automatically migrated to your account's default category.

Warning

Scope: categories:writeRate Limit: 30 req/minIdempotent: Yes

Path Parameters#

Parameter	Type	Required	Description
`id`	`string (UUID)`	Yes	Unique category identifier.

cURL Example#

Terminal

curl -X DELETE "https://api.aliasfleet.com/v1/categories/c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (`200 OK`)#

JSON

{  "success": true,  "movedAliasesCount": 12}

Response Fields#

Field	Type	Description
`success`	`boolean`	Confirms successful removal of the category record.
`movedAliasesCount`	`integer`	Total number of aliases migrated to your default category.

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`CANNOT_DELETE_DEFAULT`	`"Cannot delete the default category. Set another category as default first."`	Attempted deletion of the active default category.
`404`	`NOT_FOUND`	`"Category not found"`	Target category ID does not exist.
`500`	`DEFAULT_CATEGORY_MISSING`	`"Default category not found"`	System was unable to resolve a fallback default category.

Reorder Categories#

POST /v1/categories/reorder

Atomically updates the sort sequence of all account categories based on the provided array of IDs.

Scope: categories:writeRate Limit: 30 req/minIdempotent: Yes

Request Body Schema#

Field	Type	Required	Description
`categoryIds`	`string[]`	Yes	Array of category UUIDs in desired sequential order.

cURL Example#

Terminal

curl -X POST "https://api.aliasfleet.com/v1/categories/reorder" \  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \  -H "Content-Type: application/json" \  -d '{    "categoryIds": [      "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",      "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",      "c2b3a4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e"    ]  }'

Response (`200 OK`)#

JSON

{  "success": true}

Error Responses#

Status Code	Code	Error Message	Reason
`400`	`INVALID_CATEGORY_IDS`	`"Some category IDs are invalid or do not belong to you"`	One or more provided IDs do not belong to the authenticated account.
`401`	`UNAUTHORIZED`	`"Unauthorized"`	Missing or invalid authentication.
`403`	`INSUFFICIENT_SCOPES`	`"Forbidden: Insufficient scopes"`	Token lacks `categories:write`.

Quick Reference#

Plan Quotas & Tier Limits#

Category Taxonomy & Structure#

Key Attributes#

List Categories#

Request Headers#

cURL Example#

Response (200 OK)#

Response Fields#

Create Category#

Request Body Schema#

cURL Example#

Response (201 Created)#

Error Responses#

Get Category by ID#

Path Parameters#

cURL Example#

Response (200 OK)#

Error Responses#

Update Category#

Path Parameters#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Delete Category#

Path Parameters#

cURL Example#

Response (200 OK)#

Response Fields#

Error Responses#

Reorder Categories#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Frequently Asked Questions

What happens to aliases when a category is deleted?

Can I delete my account's default category?

How are category slugs generated?

Are category names required to be unique?

Was this article helpful?

Related in Developer API

Identity & Token Introspection API

Aliases API

Alias Destinations & Batch Operations API

Domains API

Destinations API

Still need help?

Quick Reference#

Plan Quotas & Tier Limits#

Category Taxonomy & Structure#

Key Attributes#

List Categories#

Request Headers#

cURL Example#

Response (200 OK)#

Response Fields#

Create Category#

Request Body Schema#

cURL Example#

Response (201 Created)#

Error Responses#

Get Category by ID#

Path Parameters#

cURL Example#

Response (200 OK)#

Error Responses#

Update Category#

Path Parameters#

Request Body Schema#

cURL Example#

Response (200 OK)#

Error Responses#

Delete Category#

Path Parameters#

cURL Example#

Response (200 OK)#

Response Fields#

Error Responses#

Response (`200 OK`)#

Response (`201 Created`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`201 Created`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#

Response (`200 OK`)#