createTopCategory

Create a category - Create a new TOP-level member category. Writes live data.

Use createTopCategory or createSubCategory only for a single category that needs desc, keywords, icon, sort_order, lead_price, image, master_id, or a filename other than the default slug set at create time. For every other category create, use createCategoryTree.

A Top Category is the highest level of the 3-tier member classification (e.g., "Restaurants"). It populates the profession_id field on user records. Backed by BD's list_professions table.

Use when: adding one top category that needs desc, keywords, icon, sort_order, lead_price, image, or a filename other than the default slug set at create time. To auto-create a top category while creating a member, pass profession_name to createUser instead.

Required: name, filename.

Pre-check before create: BD does NOT enforce uniqueness on filename. Two top categories with the same slug -> which one resolves at /filename is undefined. Do a server-side filter-find: listTopCategories property=filename property_value=<proposed> property_operator==. Zero rows = slug free; >=1 row = taken. Do NOT paginate unfiltered lists - filtered lookup is one tiny response. If taken: reuse via updateTopCategory, OR ask the user, OR pick an alternate filename and re-check. Wrapper safety net: on a missed pre-check, the wrapper auto-suffixes filename on collision (-1...-20) and surfaces the suffix in the response. Pre-checking still preferred — auto-suffix surprises the caller in URL-sensitive workflows.

Parameter guidance:

• name - human-readable (e.g. "Restaurants", "Dentists")

• filename - URL-slug form (e.g. "restaurants") used in public member profile URLs. The default slug is the name lower-cased and hyphenated, with any character outside the Latin set percent-encoded.

• desc, keywords, icon, sort_order, lead_price, image - all optional

See also: listTopCategories (list all), getTopCategory (by ID), createSubCategory (add a sub-category under this top).

Writes live data: changes are immediately visible on the public site.

Returns: { status: "success", message: {...createdRecord} } including the new profession_id. Use that value to populate users_data.profession_id on member records.

Common workflow - full 3-tier setup ("create Restaurants -> Sushi -> assign Alice"):

1. createCategoryTree with groups=[{ top_category: "Restaurants", sub_categories: ["Sushi"] }] -> returns profession_id (e.g. 42); read the new sub's service_id (e.g. 17) from listSubCategories

2. Assign Alice: updateUser with user_id=<Alice>, profession_id=42, services="17" (simple), OR createMemberSubCategoryLink with user_id=<Alice>, service_id=17, avg_price=..., specialty=1 (with per-link metadata)

How a member gets classified on their public profile:

• users_data.profession_id -> points at a single Top Category (the member's primary classification; shown in URL slug)

• users_data.services -> CSV of Sub Category IDs the member is tagged with (multiple allowed; simpler than the join table)

• rel_services rows (Member ↔ Sub Category links) -> used when you need per-link metadata like avg_price, specialty, num_completed. Optional; most sites use just the CSV field.

Sub-sub-categories: createSubCategory with master_id=<parent service_id> creates a Sub Category nested under another Sub Category (a "sub-sub"). master_id=0 (default) means the Sub Category sits directly under a Top Category (the profession_id).

There is NO createProfession or createService tool in this MCP — those are BD's internal table names. Use createCategoryTree, or createTopCategory / createSubCategory when a single category needs create-time field control (BD's table-name → tool-name mapping is documented in Rule: Table to endpoint).