listTopCategories

List categories (professions) - Paginated enumeration of TOP-level member categories. Read-only.

Lean by default: each row keeps profession_id, name, filename. Strips desc, keywords, image, icon, sort_order, lead_price, revision_timestamp. Pass include_category_schema=1 to restore all category metadata.

Top Categories are the highest level of the 3-tier member classification (e.g., "Restaurants", "Dentists"). Each record's profession_id is what populates users_data.profession_id on member records. Backed by BD's list_professions table.

Use when: populating a category dropdown, generating a site map, or discovering the profession_id of an existing category before assigning members to it. Returns ALL top-level categories. For sub-categories under a specific top, use listSubCategories with a profession_id filter.

Permission note - platform gap: this endpoint (/api/v2/list_professions/*) is NOT in BD's public Swagger spec, so the admin's API key permissions UI does NOT auto-generate a toggle for it. New keys default to DENY on this path even if the admin enables the "Categories (Professions)" toggle - that UI toggle gates the Swagger-documented /api/v2/category/* endpoints (a DIFFERENT legacy table). On a 403 here: the fix is to MANUALLY INSERT a row into bd_api_key_permissions for endpoint_path='/api/v2/list_professions/get' (and the singular /api/v2/list_professions/get/{profession_id} for getTopCategory). This is a platform-level gap worth reporting to BD dev team. Do NOT substitute /api/v2/category/* as a fallback - it reads a different, possibly-empty table and returns inconsistent data.

Pagination: cursor-based (limit, page). See Rule: Pagination for full cursor/cap/stop semantics.

Filter/sort: property+property_value+property_operator, order_column+order_type. See Rule: Filter operators for the verified-working operator set, silent-drop detection, and derived-field unfilterability.

See also: getTopCategory (single by ID), listSubCategories (sub-categories filtered by profession_id), createTopCategory (add new).

Returns: { status: "success", total, current_page, total_pages, next_page, prev_page, message: [...records] }. Each record has profession_id, name, desc, filename, keywords, icon, sort_order, lead_price, image, revision_timestamp.

Member Category Hierarchy (3 levels):

BD classifies members through a 3-level taxonomy - AI agents MUST understand all three to correctly create, assign, and query member categories:

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 createTopCategory / createSubCategory instead (BD's table-name → tool-name mapping is documented in Rule: Table to endpoint).