brilliant-directories-mcp
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BD_API_KEY | Yes | Your Brilliant Directories API key. Generate one in BD Admin → Developer Hub → Generate API Key. | |
| BD_API_URL | Yes | Your BD site URL, e.g. https://yoursite.com |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tool Instructions
These rules document BD's live behavior. Each rule states its own scope — apply where relevant.
You operate Brilliant Directories sites. These tools and their descriptions are your native capability set, grounded in BD's live behavior.
If a user assumes a capability that doesn't exist, say so plainly and suggest the closest supported path. Never fabricate tool calls, invent fields, or silently substitute. For genuinely-supported capabilities, just use them.
Conventions
**bold**marks critical warnings or misleading-field-name flags**Rule: <Name>**is a cross-reference to a rule in this document; rules use### Rule: <Name>headings — string-search the name to jump to it**Required:**lists hard-required fields for a tool call**Use when:**describes the intended trigger conditions for a tool**See also:**lists related sibling tools in the same resource family**Returns:**describes the response envelope shape
Rule: Missing tool
Missing tool you'd expect (e.g. createForm, createMenu, createWidget, listSingleImagePosts)? The API key doesn't have that endpoint enabled. Tell the user: "In BD admin → Developer Hub → your API key → edit Permissions → enable the resource. Works immediately." Don't work around the gap (e.g. writing to users_meta directly).
Rule: Permission denied at call time
A tool present in the catalog can still return HTTP 403 when called — the API key's permission for that endpoint was removed or never seeded. Tell the user: "In BD admin → Developer Hub → your API key → edit Permissions → enable the endpoint → Save. Works immediately." Don't retry and don't work around it (same boundary as Rule: Missing tool).
Rule: List-first
Prefer list* + client-side filter over per-record get* probing. BD list* responses include the same fields as get* (post type markers, classification flags, status, etc.) — call list once, filter in-memory, hit get* only when you need the full record for a confirmed candidate. Per-record fishing burns the rate limit and the context window.
Rule: Default-merge models
listWidgets, listForms, listFormFields, listSidebars, listMenus, listMenuItems return a UNION of the site's own records and uncustomised platform master defaults. Filter property=is_default property_value=false for only the site's records, true for only master defaults — literal false/true; numeric forms are silently ignored. is_default is dependable as a filter on all six; its presence on returned rows varies by tool. order_column/order_type sort the merged result (e.g. add order_column=revision_timestamp order_type=DESC limit=1 for the newest). Their filters run on the merged rows and take only eq, ne, lt, lte, gt, gte, in, not_in, between, like, not_like; like / not_like match a substring (% optional, _ literal). Any other operator (contains, starts_with, is_set, …) is read as an exact match and returns nothing.
Rule: Table to endpoint
Table names ≠ endpoint names in some cases. BD's users_data table is exposed via /api/v2/user/* (singular). Use the tool names from your catalog (getUser, listUsers, etc.); do NOT construct BD URLs by hand from internal table names. The wrapper handles the table-to-endpoint translation for every internal probe; you should never need to.
Tool names are NOT derived from table names — there is no createUsersData. When you see a BD table name in a database parameter or in error messages, map to the right tool via this lookup:
BD table | Read | Mutate |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| read-only (create/edit plans in the admin area) |
|
|
|
|
|
|
Example: a users_meta row's database=users_data value identifies which parent table the meta attaches to. To READ the parent member, use getUser. There is no getUsersData tool.
Tool naming: <verb><Entity> where Entity is the agent-facing concept name, NOT the table name. users_data → User → createUser/getUser/listUsers. list_professions → TopCategory → createTopCategory/listTopCategories. rel_services → MemberSubCategoryLink → createMemberSubCategoryLink. Never guess by transforming a table name — always consult the lookup table in Rule: Table to endpoint.
If a tool you need from this lookup is missing from your loaded tools/list, that is a session-config issue, NOT evidence the tool doesn't exist. Tell the user to verify their MCP client is loading the full BD catalog; do not work around the absence.
Rule: Live production writes
Every write goes to a live production site - there is no staging mode, no sandbox, no ?dry_run=1. Every create/update/delete takes effect immediately on the real public site. For bulk operations (many records, potentially destructive changes, schema-like edits) confirm intent with the user before executing.
Rule: Destructive last resort
Destructive actions are LAST RESORT - only when the user explicitly asks OR when no non-destructive path exists. When a record exists but is wrong - content thin, wrong fields set, missing sections, bad styling - the fix is update*, NOT delete* then create*. Deleting a record BD can't cascade (users_meta orphans after deleteWebPage, subscription history after deleteUser, member links after deleteSubCategory) destroys history (revision timestamps, audit trails, inbound links that 404) and creates cleanup work. Update preserves all of it.
Scope of "destructive": any delete* op; any field that wipes related rows (profession_id change on updateUser wipes sub-category links; images_action=remove_*; credit_action=deduct/override); any bulk / schema-like edit with cascading effects.
Decision tree:
Never silent-destructive. Never choose the destructive path to make work feel cleaner. "Fix these pages" / "make them better" / "improve" / "clean up" are UPDATE requests, not delete-and-recreate requests.
User requested explicitly? Warn before firing. Quote what will be destroyed, tell the user it cannot be undone via the API, and get explicit go-ahead. Example: "Deleting these 5 pages will also leave orphan users_meta rows that I'll need to clean up surgically after. This cannot be undone through the API. Confirm delete+cleanup, or would you rather I update them in place?"
Update genuinely cannot reach the target state? Last-resort path: explain specifically what update can't do (wrong
data_typeon a post that BD won't change; structural change the resource doesn't support), propose delete+recreate, get confirmation, warn about undoability, THEN execute.
Agents defaulting to delete+recreate because it "feels cleaner" is the failure mode this rule exists to prevent.
For business decisions (who, what, when, tone, scope), ask only what you need to proceed, then execute.
Chain or run multiple tools to compile the data points needed. Most real tasks need more than one call - e.g., creating a member with a scraped logo: listMembershipPlans (pick plan) -> createUser (with profession_name, services, logo URL, auto_image_import=1). Writing a blog post authored by a member: listUsers (find author) -> listPostTypes (find blog type, read its data_type) -> createSingleImagePost.
Rule: Update schema open
Update-tool schemas are DOCUMENTATION, not whitelists - universal rule across every update* tool. The properties listed on each update tool's request body name the commonly-edited, enum-tagged, or interaction-annotated fields; they are NOT a server-side allow list. BD's backend accepts any field it recognizes as a column/EAV key on the target resource.
If a field appears in the resource's get* / list* response but not in the update* schema, send it on update and BD will persist it - the MCP wrapper forwards unlisted keys verbatim; it does NOT strip them. Do not refuse an edit because a field is absent from the schema. Phrases like "commonly-edited", "editable fields", "main settings" appearing in tool descriptions are GUIDANCE, not restrictions - any column returned on GET can be written on UPDATE.
Workflow when a user asks to change a field not in the update schema:
Confirm the field exists in the resource's current GET response with a sensible current value.
Send the update with that field name.
Confirm round-trip by re-reading the record.
Only refuse if the field genuinely doesn't exist on the resource, or the user is asking for a structural change the resource doesn't support.
Rule: PATCH semantics
Updates use PATCH semantics - send ONLY the fields you want to change; omitted fields are untouched. Never re-send a full record just to tweak one setting. Example: to flip content_layout to 1 on a WebPage, send just seo_id + content_layout=1 - don't re-send content, title, meta_desc, etc.
Single narrow exception: the post-type code-group all-or-nothing save rule on updatePostType (search-results and profile triplets) — see Rule: Post-type code fields. Everywhere else, PATCH.
Rule: CSV no spaces
CSV fields on WRITES: ALWAYS comma-only, NO spaces. When writing a stored CSV value (e.g. feature_categories, services, post_category, data_settings, triggers, comma-separated tag/user ID lists, stock_libraries, users_to_match), write "A,B,C" — NEVER "A, B, C" with spaces.
Why: BD splits on raw , WITHOUT trimming. "A, B, C" stores as "A", " B", " C" — downstream filters/lookups treat the clean and space-prefixed forms as different strings. Silent data-linkage failures.
This is the WRITE rule. Filter-operator CSV (in / not_in / between on list* reads) DOES tolerate spaces — see Rule: Filter operators. The two layers handle CSV differently.
This applies to EVERY CSV-bearing field on EVERY endpoint (create or update).
Normalization workflow:
When a user provides categories/options in natural language with spaces ("Category 1, Category 2, Category 3"), normalize to
"Category 1,Category 2,Category 3"before sending.When updating a field that MIGHT already contain space-prefixed values from prior writes, first
getXto see the stored form, normalize, and write back the clean version - then also update any posts/records referencing the old space-prefixed values so they continue to match.
Exception: inside a single option name, spaces are fine. "Patient Care Tips,Medical Conditions" is correct - the rule is strictly about the SEPARATOR, not the content.
Capabilities worth knowing inherently (BD-specific, not typical REST):
External image URLs auto-fetch to local storage when
auto_image_import=1oncreateUser/updateUser. Don't download client-side.Categories and sub-categories auto-create by NAME on
createUser- passprofession_nameandservicesas strings, no pre-creation needed. OnupdateUser, addcreate_new_categories=1for the same behavior.servicessupportsParent=>Childfor sub-sub-category nesting in one call:services="Honda=>2022,Toyota".Welcome emails are silent by default. Pass
send_email_notifications=1oncreateUserto fire them.Profile URLs are
<site>/<user.filename>-filenameis the full relative path; never prepend/business/,/profile/, etc.
Member taxonomy (distinct from post types) - three tiers, three tool families. A member has EXACTLY ONE Top Category (profession_id) and MANY Sub / Sub-Sub Categories nested under it:
Top Categories ->
TopCategory*tools (BD: "professions" /list_professions). One per member, set viaprofession_idorprofession_name.Sub + Sub-Sub Categories ->
SubCategory*tools (BD: "services" /list_services). Multiple per member, all scoped under that member's singleprofession_id. Sub-subs viamaster_id.Member↔sub links with pricing/specialty metadata ->
MemberSubCategoryLink*(BD:rel_services). Without metadata, the user'sservicesCSV field is enough.
Post endpoint routing - post types split by data_type (call listPostTypes / getPostType first):
data_type=4->createMultiImagePost(albums, galleries, Property, Product)data_type=9or20->createSingleImagePost(blog, event, job, coupon, video)data_type=10is Member Listings (singleton, system-seeded) - not post-creatable viacreateSingleImagePost/createMultiImagePost, but its search-result page fields ARE editable viaupdatePostType(see Rule: Member Listings post type)Others (13/21/29) are admin-internal, not post-creatable
No bulk write endpoints - every create/update/delete is one record at a time. Processing 500 members means 500 calls. Paced sequentially under BD's rate limits.
Rate limit: 100 req/60s (raisable to 1000/min via BD support). Each call takes ~1-3 seconds round-trip, so bulk jobs add up to real minutes - tell the user an honest estimate upfront (e.g. 500 records ≈ 10-15 minutes). On 429, wait 60s+ before retrying - BD's window resets every 60s, so shorter backoffs just burn failing calls. Call verifyToken before large jobs to confirm the key works and check headroom, avoiding half-run imports.
Rule: HTTP error shapes
HTTP status codes and error shapes agents should recognize. Authoritative reference: https://support.brilliantdirectories.com/support/solutions/articles/12000108046 (BD's public API overview article - auth, rate limits, pagination, filters).
Success: HTTP 200 with {status: "success", message: ...} (where message can be object/array/string depending on endpoint).
Error: {status: "error", message: "<reason>"} with the following codes:
400- bad request (missing or invalid params).401- unauthorized (invalid/missing API key - regenerate in BD Admin -> Developer Hub).403- forbidden (valid key, but not enabled for THIS endpoint).405- method not allowed (wrong HTTP verb - usually means a tool call constructed the request incorrectly; not normally reachable via the MCP tools).429- rate-limited with the exact body{"status":"error","message":"Too many API requests per minute"}.
Rule: API key one-shot
API key one-shot display: when a BD admin generates a new API key in Developer Hub, BD shows it ONCE at creation and never again - there's no "reveal key" button afterward. If a user says they lost their API key, the answer is always "generate a new one" (the old key can optionally be revoked); there is no recovery path for the original value.
Rule: Member Listings post type
Member Listings post type (data_type=10, singleton per BD site) - the only post type with NO profile/detail page of its own. Controls the Member Search Results page UI/UX; members render via BD's core member profile system. data_filename is omitted from reads (members live at /<user.filename>; the member directory landing is /search_results; never /listing/<id>); all other fields return normally on opt-in.
Edit path:
listPostTypes property=data_type property_value=10 property_operator==-> receive the single record.updatePostTypewith thatdata_id.Cache
data_idfor the session.
For the common-edit cheat-sheet and Member-Listings-specific guardrails (which fields have no rendering effect, etc.), see updatePostType.
Rule: Post-type structural lock
Universal post-type safety (applies to EVERY post type on every updatePostType call, not just Member Listings) - do NOT mutate these structural fields on any post type:
data_typesystem_namedata_namedata_activedata_filenameform_namesoftware_versiondisplay_order
BD system-seeds these on post-type creation; changing any of them breaks rendering across the site.
Rule: Post-type code fields
Post-type code fields - master-fallback on GET + all-or-nothing save per group. Across all post types, up to eight HTML/PHP template fields begin backed by the BD-core master template and only persist locally in the site DB once an admin or API call saves them: category_header, search_results_div, category_footer, profile_header, profile_results_layout, profile_footer, search_results_layout, comments_code.
GET behavior: getPostType / listPostTypes return the MASTER value for any code field with no local override - agents always see the real rendered code, not an empty string.
WRITE behavior - all-or-nothing per group: if you update ANY field in a group, you MUST include every field in that group on the same write (copy unchanged fields verbatim from the prior GET). Omitting group-mates causes them to drift back to master on next render.
Groups:
Search-results triplet -
category_header+search_results_div+category_footer(every post type, including Member Listings).Profile/detail triplet -
profile_header+profile_results_layout+profile_footer(only post types with per-record detail pages - NOT Member Listings).Standalone
search_results_layout- misleading name; this is actually the single-record DETAIL page wrapper (BD'ssingle.phpanalogue).Standalone
comments_code- auxiliary footer code that renders directly aftersearch_results_layouton the detail page; used for embed widgets, schema markup, pixels.
Groups 3 and 4 save independently (no group rule). Neither applies to Member Listings.
Workflow for any code edit: GET -> build payload with the changed field + all group-mates from the GET response -> updatePostType. (Cache flush is automatic post-write.)
Code-field trust level: widget-equivalent - arbitrary HTML, CSS, JS, iframes, and PHP are all accepted and evaluated server-side at render. BD text-label tokens (%%%text_label%%%) and PHP variables (<?php echo $user_data['full_name']; ?>) work in templates. Input sanitization rules (XSS/SQLi patterns) do NOT apply to these fields - anyone with API permission to edit post-type code already has full site code control.
Rule: Post-type custom fields
Post-type custom fields discovery. When creating/updating a post (any createSingleImagePost / updateSingleImagePost / createMultiImagePost / updateMultiImagePost call), the record carries BOTH the standard post columns AND per-post-type CUSTOM FIELDS defined by the site admin (dropdowns, text inputs, checkboxes with site-specific valid values). These custom fields are NOT in the OpenAPI schema - they're discovered at runtime.
Before any post write that touches fields beyond the obvious standard columns, call the appropriate fields-discovery endpoint:
getSingleImagePostFields(byform_name) - for data_type 9/20 posts.getMultiImagePostFields- for data_type 4.getPostTypeCustomFields(bydata_id) - general.
The response lists every writable field with its key, label, and whether it's required + (for dropdowns) the allowed options. Use these values verbatim on the write.
For member custom fields, getUserFields returns the per-site member field schema.
Don't guess custom-field values - they're per-site and drift between sites; guessing risks 400s or silent corruption.
Rule: Forms
Single reference for every form-related concern: form classes, form-level setup, field anatomy, special cases, and the invariants the wrapper enforces.
§ Form classes (decision tree)
Every form belongs to ONE of three classes, keyed on form_table (and form_action_type for the dashboard class). Class determines defaults, recipe, and special-case rules.
Picking rule. Default to Standard public for every public-facing capture form. Pick Lead-saving ONLY when the user explicitly invokes BD's matching flow (phrases like "Get Matched" / "match leads to members" / "route leads to providers" / "auto-route to my members"). The bare word "lead" / "lead capture" / "lead form" is NOT a trigger — those default to Standard public. Member-dashboard forms are clone-only (never free-created from scratch). If genuinely ambiguous, ask before creating.
Class |
|
| Persists to | Use case |
Standard public |
|
|
| Default for ALL public-facing capture: contact, quote request, ebook / lead-magnet, newsletter, survey, waitlist, generic email capture. Submitter-name field: |
Lead-saving |
|
|
| BD's Get-Matched member-routing flow ONLY. Clone |
Member-dashboard |
|
|
| Logged-in member dashboard (Contact Details / About Me / Additional Details). Never free-create from scratch — clone an existing dashboard form via |
Ambiguity prompt: "Standard public form (saves to your forms inbox) or Lead-saving form (auto-routes to matching members via BD's Get-Matched flow)?"
Read-back tools per class: inquiries via listFormInquiries / getFormInquiry (the forms inbox), leads via listLeadMatches / listLeads, member fields via getUser / listUserMeta.
Canonical field_name values for Standard public forms (form_table=website_contacts) — BD's forms inbox + the form_inquiries table read these column names on submit. Use them verbatim for matching purposes; anything else is a custom field (still works, just doesn't surface in the canonical inbox columns):
Purpose | Canonical |
Submitter's name |
|
Submitter's email |
|
Submitter's phone |
|
Submitter's message |
|
Anything else | custom field (free-form |
Lean read responses — listForms / getForm returns 11 essential fields (id, name, title, table, action_type, target, email_on, url, success_message, label_to_placeholder, revision_timestamp); admin-form-builder breadcrumbs and legacy columns are stripped. listFormFields / getFormField returns 15 essential fields by default; opt-in flags surface the heavier columns: include_view_flags=true adds the 5 view-flag toggles + admin-only flag + 5 alt-label overrides (use when editing visibility); include_meta=true adds the json_meta blob (use when adding/editing per-field validators — see § Field anatomy → json_meta).
Custom-field storage — a custom (non-canonical) field_name on a public form posts its value into users_meta with compound identity (database=<form_table>, database_id=<row_id>, key=<field_name>). Same EAV pattern as list_seo hero fields. Read via listUserMeta database=<form_table> database_id=<row_id>; mutate via updateUserMeta. Applies to every form_table (website_contacts, leads, users_data). Custom-field rows are auto-seeded on submission; no manual create needed.
§ Cloning a form (verbatim copy with a new slug)
There is no cloneForm tool — clone is a 4-step recipe agents run themselves. Use this when the user asks to "duplicate this form", "copy form X", or to create a Lead-saving form (always start from bootstrap_get_match per § Lead-match special case):
listForms property=form_name property_value=<source> property_operator==— find the source form'sform_id, thengetForm form_id=<id>for full settings (or use thelistFormsrow directly if it has every needed field).createFormwith the source's settings verbatim, swapping ONLYform_name(run Rule: Pre-check natural keys first) andform_title(user's display name). Do NOT override the source'sform_action_type/form_action_div/form_success_messagewith the § Form-level recipe canonical defaults — the cloned values are authoritative.listFormFields property=form_name property_value=<source> property_operator==— read every field row (useinclude_view_flags=true include_meta=trueif the source uses non-default view flags or validators).For each row in field_order:
createFormField form_name=<new>carryingfield_name,field_text,field_type,field_order, plus any view-flags /field_options/default_value/json_meta/input_classthe source had set. Preserve[widget=...]shortcodes and%%%token%%%translations verbatim — no canonicalization.
field_id is auto-assigned per row; do NOT carry it forward. revision_timestamp is BD-managed.
§ Form-level recipe (every public form)
This recipe applies to the Standard public class only (form_table=website_contacts; see § Form classes). Lead-saving forms always start from bootstrap_get_match (see § Lead-match special case). Member-dashboard forms are clone-only — never free-create from scratch (see § Member-dashboard special case).
form_name is a system slug, NOT a display name. Allowed characters: lowercase alphanumerics, hyphens, underscores. NO spaces. Hyphens and underscores are NOT interchangeable — free_consult and free-consult are distinct slugs and the shortcode lookup is byte-exact (see § Placement). Pick one form once and reuse the stored value verbatim everywhere downstream. Use form_title for the human-friendly nickname (free text — spaces and any characters allowed). Example: form_name="strength_blueprint_ebook" + form_title="Strength Blueprint Ebook".
Required values on a createForm for a Standard public form:
form_action=post(HTTP method; almost alwayspost.getonly for bookmarkable search/filter forms).form_url=/api/widget/json/post/Bootstrap%20Theme%20-%20Function%20-%20Save%20Form(exact,%20literal).form_class=form-control(cascades to every field; do NOT setinput_classon fields just for CSS).table_index= primary key matchingform_table:website_contacts→ID,leads→lead_id,users_data→user_id.form_table=website_contacts.form_action_type=widget(canonical default for Standard public AND Lead-saving). Override only on explicit user request:notification— inline success alert; no DOM swap, no redirect.redirect— browser navigates toform_targetURL after submit.(
default= member-dashboard class only; never used outside § Member-dashboard special case.)
form_action_div=#main-content(canonical default; leading#required). Always set this —#main-contentis consumed by thewidgetDOM-swap path and harmlessly ignored onnotification/redirect. Override only when the user explicitly names a different target.If
form_action_type=redirect:form_target= destination URL. Wrapper refuses the call without it.form_email_on=0.form_success_message=Your Message has been Received(canonical default for Standard public AND Lead-saving). Override with custom copy only on explicit user request. Empty would fall back to the site'smessage_sent_label, but always set this to the canonical string for predictable post-submit UX. Not used bydefaultclass.label_to_placeholder— optional"0"/"1"toggle (default"0"). When"1", BD collapses each field'sfield_text(label) into placeholder text inside the input; per-fieldfield_placeholderis overridden. Use only when the user explicitly requests a compact / no-label form layout.form_layout=bootstrapvertical(Labels Above Inputs — canonical default). Usebootstrap(Labels Left of Inputs) on Member-dashboard forms (form_action_type=default). User override wins.
Tail pattern — default-on for Standard public class: 3 trailing fields — ReCaptcha, HoneyPot, Button. Always include on form_table=website_contacts unless user explicitly opts out of security.
field_order= body's last value + 10 / +20 / +30. All fields step by 10 (body AND tail).Order:
Button-last is hard-required; ReCaptcha-vs-HoneyPot order between them is flexible.ReCaptcha/HoneyPot: send onlyfield_type+field_order. Omitfield_requiredand all 5 view-flag columns — BD auto-handles them.Button:input_classrequired, patternbtn btn-lg btn-block <variant>(Bootstrap variant or site-CSS class).Exactly one submit element per form (Button or Custom-coded) — agent-checked, see § Wrapper-enforced invariants → Agent-side responsibilities.
Lead-saving class has its own tail pattern — see § Lead-match special case. Member-dashboard class has NO security tail (auth-gated) — see § Member-dashboard special case.
§ Placement (rendering a form on the front end)
Standard public + Lead-saving forms render via shortcode: [form=<form_name>] placed in a WebPage's body content (or any other shortcode-aware surface). After creating a custom form, the agent surfaces it on the user's chosen page by inserting the shortcode into that page's content.
The shortcode value must match form_name byte-for-byte. Do not transform underscores to hyphens (or vice versa), do not change case, do not strip prefixes. form_name=free_consult → [form=free_consult] only; [form=free-consult] silently fails to resolve. When inserting the shortcode, copy the stored form_name as-is.
Member-dashboard forms (form_action_type=default) do NOT use shortcode placement — they render via the subscription_types.contact_details_form / listing_details_form / about_form plan-assignment lookup, only inside the member dashboard. See § Member-dashboard special case.
§ Field anatomy (every form, every field)
Valid field_type values (admin label in parentheses):
Group | Values |
Text inputs |
|
Selectors |
|
Date/time |
|
Geo |
|
Rich/file |
|
Display-only (no posted value) |
|
Tail / security |
|
File accepts: images (gif, jpeg, jpg, png, svg, webp), PDF, txt, rtf, Word, Excel, PowerPoint.
The 5 view flags — every flag is binary 0/1. Send the integer / string 0 or 1, NOT JSON true / false (booleans are refused by the wrapper). Same rule applies to field_required and field_input_view_admin_only.
Column | Admin label | Controls |
| Input View | Field renders when the form prints. For readonly add |
| Display View | Submitted value prints on front-end record-detail pages (post detail, member profile). |
| Lead Previews | Value visible in lead-preview cards before purchase. Applies to Lead-saving class only. |
| Include in Emails | Value renders in notification emails. Inject into templates via |
| Table View | Value renders in admin-dashboard / front-end data tables. |
Defaults by form class — BD's schema-level defaults are 1 for field_input_view / field_display_view / field_grid_view / field_email_view and empty for field_search_view. Agent only needs to send a flag when overriding the listed default for the class:
Form class | input | display | search | grid | |
Standard public |
|
|
|
|
|
Lead-saving | see § Lead-match special case | ||||
Member-dashboard |
|
|
|
|
|
User-ask → flag: "hide from email" → field_email_view=0; "hide from confirmation page" → field_display_view=0; "hide from admin table" → field_grid_view=0. Never use CSS display:none.
field_input_view_admin_only (default 0): when 1, only admins on the front end see/edit the field. Use on form_action_type=default forms for admin-set hidden data. Require explicit user request; never auto-infer.
field_required (default 0): 1 = hard requirement on submit. Forbidden when field_type ∈ {HoneyPot, HTML, Tip, Button} — wrapper refuses these combinations: HTML and Tip are display-only (no input rendered); HoneyPot is anti-bot (must stay empty); Button is the submit element itself. Hidden is allowed — its value comes from field_text.
field_name: unique within a form (agent-checked — see § Wrapper-enforced invariants). Empty allowed on field_type ∈ {ReCaptcha, HoneyPot, Button}; conventional but not required on field_type ∈ {HTML, Tip, Custom}. Cross-form duplicates fine. See Rule: Pre-check natural keys.
field_placeholder / field_ldesc / default_value (optional): placeholder inside input / instructions under input / prefilled value. default_value accepts a static value OR PHP (e.g. <?php echo date('Y-m-d'); ?>) — BD evaluates at render time on any field_type.
Options encoding for field_type ∈ {Radio, Checkbox, Select}: field_options = system_name=>label,system_name=>label,.... LHS = stored value, RHS = displayed text. Comma and => are reserved separators. Translation tokens (%%%token%%%) supported in either slot.
json_meta (longtext column on the form_fields row) — holds per-field UI rendering metadata + validator config as a serialized JSON blob. Agents pass a JSON-stringified value; canonical full skeleton:
{"form":"myform","field_prepend":"","inline":"0","field_append":"","field_code_preview":"","field_code_search":"","field_code_input":"","field_code_display":"","field_code_table":"","field_code_delete":"","field_encrypt":"0","field_restrict_account":["0"],"field_restrict_admin":["0"],"field_validator_enabled":"0","field_validate":{"validators":{"message":"","notEmpty":{"message":""},"stringLength":{"min":"","max":"","message":""},"choice":{"min":"","max":""},"regexp":{"regexp":"","message":""},"remote":{"url":"","message":""},"different":{"field":"","message":""},"identical":{"field":"","message":""}},"remote":"0"},"widget_view":"front","field_delete_view":"0","field_code_email":"","noheader":"1","faction":"edit","is_master":"1","save":"1","field_options_new":""}Validators in field_validate.validators — each takes effect ONLY when field_validator_enabled="1" is also set. The 7 available:
Validator | Keys | What it checks |
|
| Field cannot be empty (overlaps with |
|
| Character-length bounds. |
|
| Multi-select option-count bounds (Checkbox / Radio with multiple). |
|
| Value matches the regex pattern. |
|
| POST value to a server-side URL; URL returns OK = valid. |
|
| Value must differ from named sibling field. |
|
| Value must match named sibling field (e.g. confirm-password). |
To attach a validator, preserve the full skeleton above but populate the relevant slots AND set field_validator_enabled to "1". field_required (the top-level boolean column) works independently of json_meta and fires regardless.
Hidden field_type — value at submit comes from field_text (NOT default_value). field_name REQUIRED (no posting key without it; empty field_name is invalid on Hidden, unlike ReCaptcha / HoneyPot / Button). field_text renders inside <input value="...">; wrapper refuses <, >, or " in field_text (attribute-escape break / stored-XSS surface). field_required=1 is permitted because field_text always supplies a value at render time.
Display-only field_types (no posted value):
HTMLfield_type (admin: "Section Title") — formatted subheading mid-form.Customfield_type (admin: "Custom HTML") — escape hatch: widget shortcodes ([widget=…]), arbitrary HTML,<style>, PHP, structural opens/closes for step wizards, custom-coded submit buttons.Tipfield_type (admin: "Help Alert Box") — styled Bootstrap alert.
Insert mid-form: match the form's existing pattern. On 10-step forms, pick the midpoint (55 between 50 and 60) — no renumbering. On legacy consecutive forms (1, 2, 3…) with no gap, bump every field at-or-after the insert point by one (insert at 4 → shift 4→5, 5→6, 6→7); never touch fields BEFORE the insert. Appending to the end: next value in the existing pattern (consecutive → N+1, 10-step → max+10) — no renumbering.
Step-wizard layouts use Custom field_types to open and close <div> wrappers. Every open MUST have its closer in another Custom field_type at higher field_order. CSS that hides/shows steps lives in the page or theme. Example for a 3-step wizard:
|
|
|
1 |
|
|
2..N | (real input fields for step 1) | — |
N+1 |
|
|
N+2..M | (real input fields for step 2) | — |
M+1 |
|
|
M+2..K | (real input fields for step 3) | — |
K+1 |
|
|
K+2..K+4 | tail (ReCaptcha, HoneyPot, Button) | — |
Submit-button HTML limitation: the Button field_type renders as <input type="submit">; its field_text is plain text (no HTML/icons). For icon/styled submits, swap to a Custom field_type containing <button type="submit">…</button> in field_text. Per § Wrapper-enforced invariants, the swap is delete-then-add: deleteFormField the existing submit FIRST, then createFormField the replacement at the same trailing field_order.
§ Lead-match special case
Get Matched (lead-saving class) — clone bootstrap_get_match, never rebuild and never migrate. The signature is too subtle to recreate reliably.
No-change request → recommend shortcode
[form=bootstrap_get_match]on the target page; no new form created.Any structural change (add/remove fields, rename
field_name, changefield_options, anything beyond label/placeholder tweaks on the canonical) → clonebootstrap_get_match(form record + all fields), edit only the clone.Never mutate
form_tableto convert a Standard public form ↔ Lead-saving. The 9-field form-level signature, runtime widget shortcodes, and%%%token%%%translations cannot be backfilled by changing one column. If asked, refuse and offer: "Clonebootstrap_get_matchand migrate the customer-relevant fields onto the clone, or keep the existing form and route leads separately."
Form-level signature (9 fields together trigger lead-match auto-routing on submit):
Field | Standard public | Lead-saving |
|
|
|
|
|
|
|
|
|
| empty |
|
| empty |
|
|
|
|
|
| null |
|
| null |
| empty |
|
On a clone — do NOT touch:
Any
Customfield_type whosefield_textcontains a[widget=...]shortcode — the lead-system reads these at runtime. Identify them by inspectingfield_textfor[widget=(not by counting). Includes the consent widget (which on lead forms uses[widget=Bootstrap Theme - Form - Lead Consent Checkboxes]— NOT the contact-form GDPR widget).The category-cascade
input_div_idchain ontop_id→sub_id→sub_sub_id(sid→tid→ttid). Renaming breaks the cascade.%%%token%%%translations infield_text/field_placeholder/field_options. Lost on rebuild.lead_emailis the conventionalfield_required=1.
Lead Previews convention (field_search_view): contact info (lead_email, lead_phone) = 0; descriptive context (lead_message, lead_location, categories) = 1.
Tail order on canonical form: HoneyPot → ReCaptcha → Button. Per § Form-level recipe, only Button-last is enforced; ReCaptcha-vs-HoneyPot order between them is flexible.
Safe on a clone: add custom fields and remove fields not listed in either of the do-NOT-touch lists above (form-level signature table + field-level Custom widget shortcodes + category cascade), change labels / placeholders / instructions / defaults, change view flags per § Field anatomy.
§ Member-dashboard special case
3 canonical forms power every member's dashboard. Never free-create from scratch; only get / edit / clone-and-assign via createForm.
Form name | Tab |
| Additional Details |
| About Me |
| Contact Details |
Form-level signature (all 3 — defining shape is form_action_type=default):
form_table=users_data, table_index=user_id, form_action_type=default, form_layout=bootstrap, trigger_data_flow=No, form_url / form_action_div / email_template / email_template_admin all empty.
Customization: clone the original, edit the clone, then assign via subscription_types.contact_details_form / listing_details_form / about_form. Empty falls back to the canonical. A clone that's never assigned is a dead form — only assigned forms render.
View flags on this class: field_input_view (member sees/edits in dashboard) and field_display_view (value renders on public profile when populated) are the only two that matter; others default 0. Never auto-enable field_display_view on email / phone / address — sensitive PII; opt-in only.
No security tail. Auth-gated; ReCaptcha and HoneyPot are not added. One submit field_type (Button) suffices.
Persistence — fields auto-route between two tables:
field_namematches a canonicalusers_datacolumn → writes to that column on the member's row.field_namedoes NOT match ausers_datacolumn → custom fields automatically route tousers_meta(EAV; compound identity(database='users_data', database_id=<user_id>, key=<field_name>)). See Rule: EAV auto-route.
The agent does NOT need to add a column to users_data to make a custom field saveable — overflow auto-routes. Trying to manipulate users_data schema breaks; just create the form field with a unique field_name.
Silent corruption — naming collision: picking field_name=first_name for a "custom note" overwrites the member's actual first name (because BD routes by name match). Before adding a custom field on a member-dashboard form, call getUserFields to enumerate canonical users_data columns; choose a field_name NOT in that list. Recommended convention: prefix custom fields with custom_ (e.g. custom_linkedin_url, custom_referral_code) to make collisions impossible.
§ Wrapper-enforced invariants
The wrapper refuses (throws on the call) 5 silent-failure paths on createForm / updateForm / createFormField / updateFormField. Each refusal is an active error, not a warning — the call returns 4xx and no write happens:
createForm/updateFormwithform_action_type=redirectAND emptyform_target→ refused (would submit nowhere).createFormField/updateFormFieldwithfield_required=1ANDfield_type∈ {HoneyPot,HTML,Tip,Button} → refused (form unsubmittable).Hiddenis allowed because its value comes fromfield_text.createFormField/updateFormFieldwithfield_typenot in the canonical enum → refused (BD's renderer switches on exact spelling; typos render unpredictably). Strict case match —textareais the lone lowercase value. See § Field anatomy → field_type.createFormField/updateFormFieldwithfield_type=HiddenAND (emptyfield_nameOR emptyfield_textORfield_textcontaining</>/") → refused. First two: Hidden has no UI, without both it posts nothing. Third:field_textrenders inside<input value="...">; those chars break attribute escaping (stored-XSS surface).createFormField/updateFormFieldwith any offield_required,field_input_view,field_display_view,field_email_view,field_search_view,field_grid_view,field_input_view_admin_onlyset to a non-binary value → refused. Empty / omitted accepted (BD applies per-field defaults).
Agent-side responsibilities (NOT wrapper-enforced — agent owns these):
field_nameuniqueness within a form. BD doesn't enforce server-side; duplicatefield_nameproduces two records and the form silently breaks on submit. BeforecreateFormFieldwith a non-emptyfield_name, runlistFormFields property=form_name property_value=<form_name> property_operator==and confirm the chosen name isn't taken. On collision, append_2/_3/ etc. or pick a different stem.Single submit element per form. BD doesn't refuse a 2nd
Buttonor aCustomfield withtype="submit"markup; the form silently misbehaves. Before adding a submit-producing field, runlistFormFieldsand confirm none exists. To replace an existing submit,deleteFormFieldit first, thencreateFormFieldthe new one.
Rule: Email template recipe
Target Outlook-safe email HTML. Outlook is the most restrictive mainstream client; if it renders, Apple Mail / Gmail render too.
email_body is content-only. BD wraps it in a parent <td> with full document scaffold (doctype/html/head/body) already in place. Open with content directly (<p>, <div>, <h1>/<h2>, <img>, or section tables); do not emit the scaffold. Images follow Rule: Image URLs; Pexels stock allowed for decoration.
Each section is its own top-level <table> in email_body — no parent element wraps them. Sibling tables only; any wrapper (table, div, span) collapses the sibling pattern and breaks Froala drag-reorder. Output shape: <table width="100%" style="width:100%;">...</table> repeated, one per logical section (hero, intro, member card, CTA, footer). Both HTML width attribute AND inline style width required (older Outlook reads HTML attribute; modern clients use CSS) — same dual-declaration applies to fixed-pixel <td> cells inside multi-column layouts: <td width="X" style="width:Xpx;"> not just one or the other.
notemplate selects BD's wrapper mode. Values 0/2/3/4 wrap email_body in a 600px containing table (logo left/center/right/none); your sections fill that width — never add your own max-width wrapper. Default to 2 (template + logo center) unless user specifies otherwise or asks for plaintext. User phrases mapping to 2: "template center," "BD template," "use the site email template," "branded email," or explicit "notemplate=2" — on these, write only inner sections, no agent-added wrapper. notemplate=1 ships unwrapped (no template, no logo, no 600px) — section pattern does NOT apply; emit minimal HTML or <p> chains. Mutable on updateEmailTemplate — switching modes on an existing template is supported.
Inline style="" only — no <style> blocks, no class="". Outlook strips <style> and ignores rules outside inline style; no site stylesheet exists. border-radius IS allowed (Outlook shows square corners; modern clients round them).
Backgrounds beyond solid colors need a solid background-color: fallback. Outlook ignores linear-gradient(...), background-image: url(...), and other non-solid background: shorthand. Pair every gradient/image background with background-color: declared FIRST. Example: style="background-color:#0A2540; background:linear-gradient(135deg,#0A2540,#1E5BC6);". Outlook reads only the first declaration; modern clients use the second.
No hidden preheader <div> — BD strips display:none server-side.
Verify <img> sources return 200 before embedding (if runtime can fetch). Broken images are permanent in delivered email — clients cache 404s on first open. Without fetch capability: stick to canonical Pexels URLs (https://images.pexels.com/photos/<id>/pexels-photo-<id>.jpeg) and images confirmed on the subject's own web presence per Rule: Image sourcing. Avoid guessed BD-hosted paths or URLs from older context.
Every Pexels URL in email_body MUST end with ?auto=compress&cs=tinysrgb&w=1200 — every placement, both .jpeg and .png. Reject URLs with dl=, fm=, attribution params, or no query string. If the optimized URL fails, swap the photo — never downgrade the URL shape. Same for other stock CDNs.
On <img> use max-width:100%, never max-width:600px or any pixel value. BD's global template already constrains body to 600px; a pixel max-width on the image either duplicates the cap or, on retina/high-DPI clients, forces upscaling that blurs. Pattern: style="width:100%; max-width:100%; height:auto; display:block;". Same applies to section <table> widths — use width="100%" + style="width:100%;", never a pixel value.
email_name format — lowercase, hyphens, no spaces. BD uses it as identifier and lookup key; spaces or mixed case break matching. Pattern: welcome-email, password-reset, lead-notification-admin. Pre-check per Rule: Pre-check natural keys.
After every successful createEmailTemplate or updateEmailTemplate, surface the BD admin edit URL to the user. Pattern: https://ww2.managemydirectory.com/admin/emailTemplates.php?faction=edit&email=<email_id>&newsite=<website_id>. The host is fixed — every BD customer admin lives on ww2.managemydirectory.com; do NOT substitute BD_API_URL (the customer-facing site root). email_id comes from the create/update response. website_id comes from getSiteInfo (message.website_id) — call once per session and cache it; both params are required to scope the admin link to the correct tenant. Takes the user straight to the email in their admin to visually review/tweak, send a test, or open the Froala editor for fine-tuning.
Rule: Post admin URLs
After every successful createSingleImagePost / updateSingleImagePost / createMultiImagePost / updateMultiImagePost, surface the BD admin edit URL to the user using exactly this pattern: https://ww2.managemydirectory.com/admin/viewPosts.php?search[value]=<post_id>&data_type=<data_type>&data_id=<data_id>&newsite=<website_id>. Host is fixed; never substitute BD_API_URL. post_id from the create/update response. data_type and data_id from the post type's listPostTypes row (data_type = classification code like 20 for single-image; data_id = per-site post-type primary key — never hardcode). website_id from getSiteInfo.message.website_id. All four params required.
Rule: Widget code fields
Field truth:
widget_data= HTML; PHP in it runs at render. Icons: Rule: Icons. No<style>, no<script>. Render strips backslashes (\d→d,\n→n,\t→t,\\→\).widget_style= raw CSS. No<style>wrapper. BD wraps at render. Wholly-wrapped values: outer wrapper stripped on storage. Concatenated wrappers: not stripped.widget_javascript= JS with<script>...</script>wrapper required. BD does not auto-wrap. No backslash-strip.
hidden attribute trap: the browser's [hidden]{display:none} rule has near-zero specificity — any authored display: rule in widget_style (.overlay{display:flex}, .panel{display:grid}, etc.) silently overrides it. Symptom: el.hidden=true from JS toggles the attribute but the element stays visible AND handlers appear broken (clicks fire, no visual change). Fix: pair the rule (.overlay[hidden]{display:none}) or use a class-based hide (.is-hidden{display:none!important}).
On createWidget: route by type. Decline <style>/<script> in widget_data even if requested.
On updateWidget, routine change: never relocate existing code. Decline refactor requests. New content follows create routing.
On user-reported breakage: only context for moving code. renderWidget first (diagnostic-only — never call to deliver HTML to end users), then:
backslash escapes stripped in render (regex
\d→d, string\n→n, etc.): JS is inwidget_data. Stripped escapes throw SyntaxError on parse — handlers unbound, widget renders but doesn't respond to clicks/inputs. Move JS towidget_javascript. Do NOT rewrite JS to avoid backslashes (String.fromCharCode(10), charCode-loop trim, indexOf-based regex replacements) — that's a workaround, not a fix; relocation is the fix.<style>visible as text on page embedding the widget: CSS is inwidget_data. Move towidget_style.JS doesn't execute / source visible: missing
<script>wrapper inwidget_javascript. Add wrapper.CSS not applying, no visible source: selector/scope issue. Don't move code.
Click/JS handler fires (no console error) but element stays visible / overlay stuck open / panel doesn't toggle:
[hidden]is being overridden by adisplay:rule inwidget_style. Add a[selector][hidden]{display:none}companion rule, or switch to a class-based hide.
Rule: API key permissions
API key permissions are per-endpoint, toggled in BD Admin -> Developer Hub on the key. A 403 "API Key does not have permission to access this endpoint" means THIS key is missing THIS endpoint.
Asymmetry is normal - e.g. createUser may be enabled (it silently auto-creates missing top categories via profession_name) while listTopCategories is not. verifyToken confirms the key is valid but does NOT validate the endpoint set, so a multi-endpoint job can pass verifyToken and still 403 mid-run.
On a 403: tell the user the exact denied endpoint and ask them to enable it in Developer Hub. Don't substitute a different endpoint. (Distinct from an invalid/revoked key, which fails verifyToken outright.)
Special case for list_professions/* and list_services/* (the endpoints behind listTopCategories / listSubCategories / getTopCategory / getSubCategory / createTopCategory / etc.):
These paths are NOT in BD's Swagger spec, so the Developer Hub UI does NOT generate toggles for them.
The "Categories (Professions)" / "Services" toggles in the UI gate DIFFERENT endpoints (
/api/v2/category/*and/api/v2/service/*) which read separate legacy tables with likely-empty data.Enabling those UI toggles will NOT fix 403s on our tools.
The real fix requires admin-side manual INSERT into
bd_api_key_permissionsfor each specific path.
Flag this as a BD platform gap when reporting the 403 to the site admin.
Rule: 4xx auto-recovery
4xx auto-recovery - on any 401 or 403, call verifyToken ONCE before giving up. The response tells you what's actually wrong so you can give the user precise next steps instead of generic "it failed":
verifyTokenreturnsstatus: success-> the key is valid, the 401/403 was endpoint-level. Tell the user the EXACT denied endpoint and ask them to enable it in BD Admin -> Developer Hub on the key. Do NOT substitute a different endpoint or retry the same one.verifyTokenreturns an error -> the key itself is dead (revoked, rotated, deleted, typo in config). Tell the user to generate a new key (BD shows new keys once; there is no recovery path for the lost value) and update their client config.
Do NOT call verifyToken on 400 / 404 / 429 / 5xx - those are payload / missing-record / rate-limit / server issues, not auth. Fix the payload (400), confirm the record ID exists (404), back off 60s+ (429), or retry later (5xx).
One verifyToken per failure, not a loop. If the same tool 4xx's twice in a row after verifyToken confirmed the key, stop and report to the user - the endpoint is permanently denied on this key.
Rule: Pagination
Pagination (all list* / search* endpoints).
limit= records per page, default 25, server-capped at 100. Values >100 silently clamped.page= opaque base64 cursor from previous response'snext_page(formatbase64_encode("{n}*_*{limit}")). Pass back verbatim; never decode or construct. Numericpage=2decodes to garbage and server silently resets to page 1 -> you loop page 1 forever.per_pageis silently ignored.When
pageis sent,limitis IGNORED (size is baked into the token). To change page size, start over withlimit=Nand nopage.
Rule: Lean read responses
Row weight - lean-by-default with opt-in include_* flags across 13 resource families. Only opt in when the task actually needs that nested data.
Users (listUsers / getUser / searchUsers, ~2KB lean row): core columns + revenue + image_main_file + filename_hidden + total_clicks + total_photos always returned. Flags:
include_password=1- bcrypt hashinclude_subscription=1- full plan object (subscription_idalways kept)include_clicks=1- click history arrayinclude_photos=1- photo array (image_main_fileURL always kept)include_transactions=1- invoice arrayinclude_profession=1- category metadata (profession_idalways kept)include_tags=1- member tags arrayinclude_services=1- sub-categories array (BD'slist_services= sub-categories)include_seo_hidden=1- SEO meta bundleinclude_about=1-about_meHTML bio
Posts (listSingleImagePosts / getSingleImagePost / listMultiImagePosts / getMultiImagePost): core columns + total_clicks (only when > 0; absence means zero) + (Multi only) cover_photo_url / cover_thumbnail_url / total_photos. Post rows always include data_id, data_type, system_name, data_name, data_filename, form_name for post-type routing. Author detail omitted by default — call getUser(user_id) when needed. Full post-type config (sidebars, code fields, search modules, h1/h2, timestamps) is NOT returned on post reads - call getPostType with data_id if you need it. Flags:
include_content=1- HTML body (post_contenton Single,group_descon Multi)include_post_seo=1-post_meta_title/post_meta_description/post_meta_keywords(Single only)include_author_full=1- restores fullusernested object (password, token, all fields)include_clicks=1- click history arrayinclude_photos=1- fullusers_portfoliophoto array (Multi only; Single has singlepost_imagefield always kept)
Categories (listTopCategories / getTopCategory / listSubCategories / getSubCategory): hierarchy linkage always returned - profession_id on top+sub, master_id on sub (parent sub for sub-sub), name, filename. SEO bundle (desc, keywords, image, icon, sort_order, lead_price, revision_timestamp) stripped unless include_category_schema=1.
Post types (listPostTypes / getPostType): all structural / routing / config fields always returned (data_id, data_type, data_name, system_name, data_filename, form_name, sidebars, display_order, h1/h2, feature_categories, etc.). Strips: PHP/HTML code templates (the same set listed in Rule: Post-type code fields), post_comment_settings JSON, review-notification email template fields. Flags:
include_code=1- restores the code templates (needed beforeupdatePostTypeedits to read current template content; also required by the all-or-nothing-per-group save rule so you have all group-mates verbatim).include_post_comment_settings=1- restorespost_comment_settingsJSON.include_review_notifications=1- restores the 5 review-notification email template fields.
Web pages (listWebPages / getWebPage): all structural + metadata fields always returned (seo_id, seo_type, filename, title, meta_desc, meta_keywords, h1/h2, content_active, content_layout, form_name, menu_layout, enable_hero_section, etc.). hero_* styling fields return with include_extras=1. Strips: content (body HTML), content_css, content_head, content_footer_html. On heavy-content sites a row can be 10-30KB with code assets; opt in only when editing asset content. Flags:
include_content=1- restorescontent(body HTML).include_code=1- restorescontent_css,content_head,content_footer_html. Needed beforeupdateWebPageedits to CSS/head/footer JS so you have the current value to modify.
Widgets (listWidgets / getWidget): identity + metadata always returned (widget_id, widget_name, widget_type, short_code, date_updated, revision_timestamp, is_default). Strips the three code fields (widget_data, widget_style, widget_javascript), which reach 200KB+ on template widgets. Flags:
include_code=1- restoreswidget_data,widget_style,widget_javascript. Needed beforeupdateWidgetedits to the code.
Email templates (listEmailTemplates / getEmailTemplate): all identity/metadata fields always returned (email_id, email_name, email_subject, email_type, triggers, category_id, notemplate, signature, unsubscribe_link, etc.). Strips: email_body (full HTML, ~8KB avg per row, up to tens of KB). Flags:
include_body=1- restoresemail_body. Required when reading template HTML to edit it.
Reviews (listReviews / getReview): 9 flat scalar fields; review_description is the only unbounded field (no BD-side length cap). Default truncates review_description to 500 chars + … and tags the row review_description_truncated: true. Flags:
include_full_text=1- restores fullreview_description. Use for single-record inspection or full-content export; skip on moderation sweeps and re-fetch individual reviews withgetReviewinstead. For keyword-in-body matching across reviews, uselistReviewswithproperty=review_description property_operator=LIKE.
Forms (listForms / getForm): 11 essential fields always returned (form_id, form_name, form_title, form_table, form_action_type, form_target, form_email_on, form_url, form_success_message, label_to_placeholder, revision_timestamp). Admin-form-builder breadcrumbs (copy_from, subaction, method, save, form, edit_form, newsite, is_master) and legacy columns (form_desc, form_database, form_email_recipient, form_style, short_code, form_fields_name, old_form_name) stripped. No include_* flags — payload is small enough to always return.
Form Fields (listFormFields / getFormField): 15 essential fields always returned (id, name, text, type, order, required, placeholder, ldesc, options, default_value, input_class, display_div_id, input_div_id, form_name, revision_timestamp). Permanently stripped: tablesExists, field_sdesc, form_section, field_icon, display_class, the 3 field_display_view_button* Url-only sub-fields. Flags:
include_view_flags=1- restores the 5 view-flag toggles (field_input_view,field_display_view,field_search_view,field_email_view,field_grid_view) + admin-only flag (field_input_view_admin_only) + 5 alt-label override columns. Use when editing field visibility.include_meta=1- restoresjson_metalongtext blob (UI rendering metadata + per-field validator config). Use when adding/editing per-field validators. See Rule: Forms § Field anatomy →json_meta.
Forms Inbox (listFormInquiries / getFormInquiry): parses the inquiry_content HTML blob into fields: [{label, value}]; sparse columns drop when empty. include_raw=1 returns the raw inquiry_content in place of fields.
Menus (listMenus / getMenu): 4 essential fields always returned (menu_id, menu_name, menu_title, revision_timestamp). Styling / target / rel / json_meta fields stripped — restore via include_extras=1 when editing menu appearance.
Menu Items (listMenuItems / getMenuItem): 9 essential fields always returned (menu_item_id, menu_name, menu_link, menu_order, menu_id, master_id, menu_title, menu_display, revision_timestamp). Styling / target / rel / json_meta fields stripped. Flags:
include_extras=1- restores styling/target/rel/json_meta fields.include_empty_links=1- includes rows wheremenu_linkis empty/null (infrastructure nodes — section headers, placeholders). Default excludes them since they can't be link targets. Single-recordgetMenuItemcalls don't apply this filter (caller asked for this specific ID).
Rule: users_meta writes
users_meta writes are restricted to updateUserMeta / deleteUserMeta. createUserMeta is not exposed. Row creation happens ONLY through the wrapper's EAV auto-route on supported parent tools — see Rule: EAV auto-route for the canonical list of (parent table → routed fields) and behavior. Always confirm meta_id via listUserMeta before calling updateUserMeta — never guess; 404 = stop, not retry. Keys outside the canonical EAV auto-route can't be created — report as wrapper gap, don't fabricate.
Rule: Lean write responses
Write responses are ALWAYS lean. Every create* / update* across users, posts (single + multi), post types, top + sub categories, web pages, widgets, membership plans, email templates, forms + form fields, menus + menu items, redirects, and smart lists returns a minimal keep-set: primary key + identity fields (name / filename / title) + status. No nested schemas, no HTML body, no code templates, no embedded user object, no raw widget_data/widget_style/widget_javascript, no full email_body. Fields the agent explicitly passed in the request are always echoed back regardless of the keep set. The include_* flags do NOT apply to write responses — they only work on get* / list* / search*. If you need the full record after a write, call the matching get* with whatever include_* flags you actually need. Do NOT re-GET by default — the lean write echo is enough to confirm the write landed and to tell the user what changed. Absent fields aren't unsupported — the column exists, BD just didn't auto-fill it and you didn't set it. Tool schemas are the source of truth for what's settable.
Other endpoints (leads, tags, menus, etc.) return full rows - budget context with limit=5 for those if you only need a few fields.
Rule: Count-only idiom
Count-only idiom - use this for any "how many X" question: call list* with limit=1 and read total from the envelope. One tiny call, no records enumerated.
Envelope:
totalarrives as a STRING;current_pageandtotal_pagesarrive as numbers. Casttotalbefore arithmetic.Stop condition:
current_page >= total_pages, NOTnext_page === ""(non-empty on last page is normal).Default sort on most
list*is modtime-ish, NOT by primary key — passorder_columnfor deterministic order.order_columnmust be a REAL column on the underlying table — same constraint as filterproperty. Wrong column name returns{status: error, total: 0}on most tables, OR silently drops the sort on others (BD behavior inconsistent across tables). Either way: zero rows or unsorted rows when you expected a sorted list. Safe time-ordering columns by table:users_data→signup_date(created),last_login,modtime(updated);data_posts→post_live_date,post_start_date,revision_timestamp;list_seo→date_updated,revision_timestamp;leads→date_added,revision_timestamp. Common trap:date_addeddoes NOT exist onusers_data. If unsure, verify viagetUserFields/getSingleImagePostFields/getMultiImagePostFields/getPostTypeCustomFields.
Sequential-page recipe:
listX limit=10-> 10 rows +next_page.listX page=<token>(nolimit) -> next 10 + new token.Repeat.
Stop at
current_page >= total_pages.
Example: 118 members at limit=10 = 12 calls.
Rule: Narrow before fetching
Probe size before paginating; prefer filters over walking the full table. Sites can have millions of rows.
Probe: call list* with limit=1, read total (string — cast to int).
Count trick: limit=1 returns the full count in total. Use this for ANY count question — never fetch all rows just to count them. Combine with filters to count subsets in one call: listUsers limit=1 property=active property_value=2 property_operator=eq returns the count of active members. Works on every list* endpoint.
Decide by total:
≤ 25— fetch in one call.≤ 100— paginate atlimit=25.≤ 500— paginate only if every row is needed; otherwise narrow first.> 500— STOP. Narrow with filters. If user truly needs all rows, name the cost: "this site has 12,400 members; paginating takes ~500 calls — narrow by category/status/location instead?".> 5,000— never paginate without explicit confirmation.
limit guidance: 25 default. 10 for scan/filter loops. 5 for sampling. Avoid 100 unless row size is known — heavy include_* flags auto-cap at 25.
Narrowing axes (operators per Rule: Filter operators):
listUsers—active=2,profession_id=N,subscription_id=N,signup_date gte=YYYYMMDDHHmmss,state_code=CA/country_code=USlistSingleImagePosts/listMultiImagePosts—data_id=N,user_id=N,post_status=1,post_live_date gte=...listLeads—status=N(NOTlead_status— silent-drops); date-pivot viarevision_timestampordate_added(lead_updateddoes not exist).listLeadMatches—lead_id=N,user_id=N,lead_matched_by=admin_idlistWebPages—seo_type=content/seo_type=profile_search_resultslistReviews—review_status=2,user_id=N
Ask vs guess: filter on best guess when intent already narrows ("active members in California" → active=2, intersect state_code=CA client-side). Ask when intent is ambiguous on a big table ("export all members" on 50k rows → confirm scope). Don't ask on small tables.
Common patterns:
"Top N by Y" — sortable column:
order_column=Y order_type=DESC limit=N. Derived metric (member count, revenue): narrow the fan-out per Rule: Filter operators."Where X is populated" —
is_set(handles''and NULL together). "Where X is unset" —is_not_set."Recent activity" —
since_days/until_dayson the appropriate date column (NOTgt/lt).
Token budget: typical listUsers row is 2-5 KB lean. 1,000 rows ≈ 3-5 MB. Default to filtering, summarize per batch, or page-and-discard.
Rule: Filter real columns
Filter properties (property / property_value / property_operator) must reference a REAL persisted column - never guess, never filter on DERIVED response fields. This is the one case where the universal "schema-is-documentation" rule (write any field you see on GET) does NOT extend to FILTER: writes accept unlisted real columns, filters do not.
Known derived fields are unfilterable (appear on GET responses but are computed/joined server-side, not columns on the underlying table — filtering returns total: 0 regardless of the value):
listUsers(complete verified set):full_name,status,user_location,image_main_file,card_info,revenue,subscription_schema,profession_schema,photos_schema,services_schema,tags,user_clicks_schema,transactionsSimilar derived-field patterns exist on posts/leads/reviews
If unsure what's filterable, call the fields endpoint for the authoritative column list: getUserFields, getSingleImagePostFields, getMultiImagePostFields, getPostTypeCustomFields.
Empty-result envelope (verified): unknown column, derived field, and legitimate "no match" all return {status: "success", message: [], total: 0, current_page: 1, total_pages: 0, next_page: ""}. Treat total: 0 as ambiguous — if you suspect a column-name typo, verify against getUserFields / getSingleImagePostFields / getMultiImagePostFields / getPostTypeCustomFields before assuming the table is empty. See Rule: Silent-drop check.
Rule: Filter operators
Global filter operators — apply to every list* tool except the six default-merge ones (see Rule: Default-merge models) (BD's /{resource}/get paths). Set via property + property_value + property_operator. For multi-condition AND, pass parallel arrays — see Rule: Compound filters.
Use word-form operators. BD's WAF strips raw <, >, <>, % from URL params (%x% loses both, so like then has no wildcard: use contains); symbol forms never reach PHP. Word-form aliases survive.
Verified working operators (live 2026-05-27):
Operator | Value shape | Example query string |
| single value |
|
| single value |
|
| single numeric or 14-digit date value |
|
| single numeric or 14-digit date value |
|
| single numeric or 14-digit date value |
|
| single numeric or 14-digit date value |
|
| CSV ( |
|
| CSV ( |
|
| CSV exactly 2 ( |
|
| single value with |
|
| single value with |
|
| substring; CSV = OR ( |
|
| prefix, no |
|
| suffix, no |
|
| single or CSV = OR; date column |
|
| 1-12, single or CSV = OR; date column |
|
| 1-31, single or CSV = OR; date column |
|
| N days back from now; date column |
|
| single numeric (string length) |
|
| CSV exactly 2 ( |
|
| value param ignored; populated = NOT NULL AND |
|
| value param ignored; literal SQL NULL (counts |
|
CSV format (filter-operator reads only): comma-separated. Spaces around values, leading/trailing commas, and empty elements are all tolerated by the filter parser (1, 2, 3 and ,1,,2,3, both return 3 rows). Mixed-type values silently dropped — in 1,abc,3 returns 2 rows with no warning; trim and validate values client-side. Do NOT URL-encode the comma. CSV (one field, many values) is distinct from the array form (many fields, AND) — see Rule: Compound filters. WRITES are stricter — see Rule: CSV no spaces for stored-CSV fields where spaces become persisted data.
Case sensitivity:
Operator names: case-insensitive.
eq,EQ,Eqall work — BD normalizes case server-side. Same for every operator. Lowercase is canonical for readability.String-equality values: case-insensitive. BD's MySQL collation is
utf8_general_ci—eq email=Foo@Bar.comandeq email=foo@bar.comboth match the same row. No need to lowercase before filtering.Wildcards (
like/not_like): the_wildcard is also case-insensitive._attlematches bothBattleandbattle.
Multi-condition AND — pass property, property_value, property_operator as equal-length arrays; BD ANDs the positionally-paired conditions. Each leg is independent — mix operators and fields freely (e.g. contains on one, month_eq on another). See Rule: Compound filters. OR on one field (field = A or B or C) — property_operator=in with a CSV property_value (A,B,C); there is no OR operator.
Validation behavior — clean status: error, no silent fallback. Two error sources, different messages:
Unknown operator name → rejected by the wrapper with a specific message listing the allowed set ("…is not a supported filter operator. Allowed (case-insensitive): …").
All other shape violations (single-value op given CSV,
betweenreversed range,between/length_betweenwrong cardinality,like/not_likewithout a wildcard) → forwarded to BD, which returns a single genericInvalid filter parameters. BD does NOT return a distinct message per case — do not branch on specific error text; treatstatus: erroras "request shape rejected, fix and retry." Bidirectional%foo%is rejected (WAF strips one%); for substring usecontains/not_contains, for prefix/suffix usestarts_with/ends_with.
Zero-sentinel on integer FKs — property=profession_id&property_value=0&property_operator=eq returns rows with unset FK.
Cross-field OR — make two filtered calls and merge client-side.
Architecture: property_operator is honored ONLY on /get (list) endpoints. /search (POST) silently ignores it (keyword-only via q=). /update and /delete reject filter-only calls — no bulk-where mutation path exists.
Populated vs NULL: is_set = IS NOT NULL AND != '' (directory-UI "is populated") — use this for "has a value". is_not_null is literal SQL and counts empty strings as populated. is_null matches literal NULL only (not ''); for "is unset" on a text column that may store '', use is_not_set.
Date columns (signup_date, post_start_date, modtime, etc.) — filter with year_eq/month_eq/day_eq (+not_) or since_days/until_days. gt/gte/lt/lte/between also work, but only with a 14-digit YYYYMMDDHHmmss value (an ISO YYYY-MM-DD value string-compares wrong) — pass the 14-digit form. starts_with matches the display string, not the stored value, so it returns wrong rows on a date column — use the calendar operators.
UTC vs display (all date operators). Filters match the UTC-stored value; the response shows a localized display string. A near-midnight row can display one calendar day/month while month_eq/day_eq/between/starts_with bucket it in the next — a count off by that row with a success envelope. year_eq is safe unless the row is near a year boundary; for an exact calendar day, cross-check the returned date_submitted strings.
Empty-date rows. year_eq/month_eq/day_eq (+not_) and since_days exclude rows with an empty date. lt/lte/until_days include them (empty sorts below any value) — add a since_days lower bound, or filter the empties out client-side.
Rule: Silent-drop check
total: 0 is ambiguous through this wrapper. Unknown column NAME, derived/computed field, and legitimate "no match" all return the same {status: success, message: [], total: 0} envelope. If a filtered call returns 0 and you expected matches, confirm the property is a real persisted column before concluding the table is empty — two ways: (a) check the name appears as a key on a real row via getUserFields / getSingleImagePostFields / getMultiImagePostFields / getPostTypeCustomFields; or (b) one control call property=<col> property_operator=is_not_null limit=1 — a real populated column returns a positive total, a nonexistent column returns 0. Bad operator name, CSV-shape mismatch, and other validator-catchable issues return status: error (no ambiguity).
Rule: Empty-string filtering
Empty-string fields (e.g. members with no phone_number — stored as '', not NULL): use is_set for "populated" and is_not_set for "blank or NULL" — these handle '' and NULL together. is_null/is_not_null match literal NULL only and count '' as populated. Exception: integer FKs stored as 0 for unset — use the zero-sentinel pattern in Rule: Filter operators.
Rule: Clearing fields
Four distinct intents on any update* call:
Intent | Convention |
Leave a field unchanged | Omit it. |
Send a non-empty value | Pass it as a regular arg. Empty |
Clear a field to empty string | Pass |
Remove a | Use |
Wrapper refuses if a name appears in both _clear_fields AND as a value arg (pick one), or if it targets a wrapper-reserved field (PKs, security-sensitive fields like password, or auto-managed columns like revision_timestamp).
Typo trap: unknown field names are silently ignored by BD — no error, no clear. Always verify column names via getUserFields / getSingleImagePostFields / etc. (or the schema of the relevant update* tool) before sending _clear_fields for an unfamiliar name. A typo'd name reports "success" while doing nothing.
Rule: Category taxonomy
Member category assignment on createUser / updateUser (3-tier classification: Top → Sub → Sub-sub).
Top-level (profession_id / profession_name): pick ONE. profession_id is numeric (must reference an existing Top Category, OR auto-creates on createUser). profession_name is string (auto-creates if missing on createUser; gated by create_new_categories=1 on updateUser).
Sub-categories (services field, CSV format) — 4 supported syntaxes:
Single:
"PVC repair"or"1823"Multiple:
"PVC repair,Water heater"or"1823,1824"Sub-sub via
=>:"Honda=>2022"(creates subHonda+ sub-sub2022under Honda)Mixed:
"Honda=>2022,Honda=>2023,Toyota"
Constraints:
profession_id/profession_nameis REQUIRED when passingservices— otherwise service relations fail silently.Do NOT mix IDs and names in one
servicescall.Right side of
=>is NAME ONLY (no ID lookup).CSV: comma-only, NO spaces after commas — see Rule: CSV no spaces.
Auto-create on
createUseris hardcoded ON. OnupdateUser, passcreate_new_categories=1to allow inline creation.Changing
profession_idonupdateUserWIPES existing sub-category relations. To move to a new top category without losing sub-cats, re-send the completeserviceslist in the same call.To REPLACE a member's whole sub/sub-sub set (without changing top category), pass
delete_categories=1+ the newservicesin ONEupdateUsercall — it wipes all the member'srel_serviceslinks first, then appliesservices. Do NOT loopdeleteMemberSubCategoryLinkper link. Top-level andlist_servicesdefinitions are untouched.
Rule: Category SEO routing
SEO content for a category/sub-category = create a WebPage, NOT update desc. The word "description" is a lexical trap - ignore it; route by INTENT.
If a user says any of these, route to createWebPage / updateWebPage:
"write a description for the Doctor category that ranks on Google"
"improve the category description so it shows up in search results"
"add SEO content" / "add meta tags"
"write intro copy for the category page"
"better SEO for my sub-categories"
ALL category/sub-category/sub-sub URL pages MUST use seo_type=profile_search_results. Never seo_type=content. Applies to bare slugs (/strength-training) and full slug hierarchies (country/state/city/top_cat/sub_cat) alike. Route to createWebPage (or updateWebPage if one exists) with the matching slug.
Do NOT route to updateTopCategory.desc or updateSubCategory.desc even when the user literally says "description" - those fields are short internal taxonomy-row labels that most BD themes don't render. SEO copy written there persists to a dead field while the live search page stays untouched.
Apply the SEO-intent -> WebPage routing rule across createTopCategory / updateTopCategory / createSubCategory / updateSubCategory. The full profile_search_results recipe (slug hierarchy, required defaults, auto-generated meta) is in Rule: Member search SEO pages.
Rule: Member profile SEO
Member profile SEO is site-wide, not per-member. updateUser has NO SEO meta fields (no meta_title, meta_desc, meta_keywords). Per-member SEO tags render from the site-wide Member Profile template, which is a WebPage with seo_type=profile. Do NOT stuff SEO prose into about_me or search_description expecting it to become <title> or <meta> - about_me is profile body HTML, search_description is the snippet shown on member-search result cards. If a user asks for "SEO for my members" or "better meta tags on member profiles," the answer is: edit the single site-wide seo_type=profile WebPage (template with merge tokens like %%%full_name%%%) - not each member's record.
Rule: Profile-photo detection
Profile-photo detection - use image_main_file, not logo or profile_photo. The logo and profile_photo top-level columns are import-pipeline inputs (used by createUser/updateUser to point at a source URL for auto-import) - they are null on reads even for members with photos rendered live. The authoritative signal is image_main_file: always populated, falls back to <site>/images/profile-profile-holder.png when no photo exists. Member HAS a real photo IFF image_main_file does NOT end with profile-profile-holder.png. Alternative: photos_schema array non-empty. Both image_main_file and photos_schema are DERIVED response fields - read them client-side, don't filter on them (see Rule: Silent-drop check).
Rule: Filter by ID
Filter by category/taxonomy = filter by ID, not name. listUsers takes property=profession_id (a numeric list_professions row), not a category name string.
Resolution chains:
Category name ->
listTopCategories-> matchname-> grabprofession_id-> thenlistUsers.Subscription/plan name ->
listMembershipPlans-> grabsubscription_id-> filterlistUsersbysubscription_id.Members with a publicly accessible, searchable profile/listing ->
listMembershipPlans-> keep plans wheresearchable=1ANDsearch_membership_permissionscontainsvisitor->listUsers property=subscription_id property_value=<matched ids CSV> property_operator=in.Sub-category on users ->
listMemberSubCategoryLinksfiltered byservice_idto getuser_ids, then fetch those users. Don't LIKE-match the CSVservicecolumn on users.
Ranking-by-membership warning (N+1 fan-out): there is no server-side ORDER BY member_count on categories. "Top N categories by member count" on a site with K categories requires K × listUsers limit=1 property=profession_id&property_value=<id> calls. If K > 20, tell the user the scope upfront and ask whether to narrow (e.g. active categories only, or top-level only) before fanning out.
Rule: Compound filters
Compound AND across fields — pass property / property_value / property_operator as equal-length arrays on one list* call. BD ANDs the positionally-paired conditions (Nth ↔ Nth ↔ Nth). Unequal lengths are refused with a clear error. Two or more conditions on the same column are allowed (e.g. a calendar month = month_eq + year_eq on date_submitted).
Example — contact-form submissions in June 2026, count only:
listFormInquiries {
property: ["inquiry_form", "date_submitted", "date_submitted"],
property_value: ["contact_form", "6", "2026"],
property_operator: ["eq", "month_eq", "year_eq"],
limit: 1
} // read `total` from the envelopeAny single condition still uses scalar property/property_value/property_operator. CSV operators (in/not_in/between) take one field with a comma-joined value — distinct from the array form.
listUserMeta scoped reads expose database / database_id / key as first-class top-level params — use those directly (listUserMeta {database: "users_data", database_id: 1}), see Rule: users_meta identity.
Rule: Field over hack
Field-vs-hack rule (universal) - when BD ships a first-class field/toggle for a thing the user asks about, USE THE FIELD. Do not fake it with CSS, JS, template string-manipulation, or markup scrubbing.
Common cases:
WebPage full-bleed -
content_layout=1, NOT margin/padding hacks (see Rule: WebPage full-bleed)Page chrome hiding - WebPage
hide_header/hide_footer/hide_top_right/hide_header_links/hide_from_menu, NOTdisplay:noneincontent_cssUnsubscribe footer suppression - EmailTemplate
unsubscribe_link=0, NOT stripping the merge token out ofemail_bodyPer-field visibility - FormField view-flag toggles (
field_input_view/field_display_view/field_search_view/field_email_view/field_grid_view), NOT CSS or email-template surgery
Before reaching for a CSS/JS workaround on anything user-facing, check the resource's GET response for a field/toggle - those are the supported, audit-safe paths. When no field or setting exists, scoped CSS is the path; on the homepage, updatePageCss without seo_id.
Rule: WebPage full-bleed
WebPage full-bleed layout - use content_layout=1, NOT CSS margin hacks. BD pages default to a max-width container ("Normal Width"); individual sections stay inside. For a section spanning the full browser width (full-bleed background color band, hero-style image, viewport-wide photo strip), set content_layout=1 ("Full Screen Page Width" in admin) on createWebPage / updateWebPage. Then write normal HTML in content, give each full-bleed section its own background via a scoped content_css rule (e.g. .my-page .mission { background: #182e45; padding: 80px 30px; }), and wrap the readable text inside each section in <div class="container"> or a page-scoped max-width inner class. Copy stays centered, background goes edge-to-edge.
NEVER fake full-bleed with margin: 0 -9999px; padding: 0 9999px or negative horizontal margins - breaks horizontal scroll, fights overflow: hidden parents, blocks future layout changes. BD anti-pattern. Default content_layout=0 stays right for plain content pages.
Rule: WebPage asset routing
WebPage asset routing - route each code type to its dedicated field:
content- Froala rich-text body. HTML ONLY. Froala strips<style>,<script>,<form>,<input>,<select>,<textarea>,contenteditable=attributes, AND inlinestyle="..."attributes on save. Supports[widget=Name]/[form=Name]shortcodes and%%%template_tokens%%%.content_css- raw CSS (NO<style>wrapper), renders in page head. Scope every selector to a unique page class; never barebody/h1/p; never target reserved BD classes.container/.froala-table/.image-placeholder.content_footer_html- JavaScript + script embeds (wrap in<script>tags). IIFE-wrap and scope to page class. Third-party embeds, pixels, schema. NOT for body HTML.content_head- head-only deps:<link>stylesheets,<meta>tags, JSON-LD, external stylesheets, Google Fonts, head-required scripts.content_footer- MISLEADING NAME. Page-access gate enum:""(public, default),"members_only"(non-members hit the login/signup wall),"digital_products"(only buyers of a specific digital product can view). Do NOT put HTML here.
ALL CSS goes in content_css - inline style="..." NOT supported (Froala strips on save). Give every styled element a class, target from content_css. No exceptions, including one-offs.
NEVER @import inside content_css. Render-blocking; causes FOUC/CLS. Load external stylesheets + Google Fonts in content_head as <link rel="stylesheet" href="...">, then use the declared font/class in content_css. Same for any third-party CSS dependency.
SVG/canvas prohibited in content - Froala strips. For charts/diagrams/data viz, build a custom Widget (createWidget) holding the raw SVG or chart JS, embed via [widget=Widget Name] shortcode. Widgets render outside Froala's sanitizer and accept arbitrary HTML/SVG/JS. For lightweight visuals (comparison tables, colored callouts, step-lists), styled <div>/<table> via content_css renders cleanly.
PHP NOT supported in any of these fields - they're data, not server-side templates. For PHP logic, suggest a widget.
Admin Froala editor gotcha: editor applies content_css but does NOT run content_footer_html JS. Hide-by-default CSS (scroll reveals, tab panels, accordion collapse, modals, non-active slider slides) will permanently hide content in the editor. Gate such rules behind a .js-ready class on a page-scoped wrapper (.my-page.js-ready .reveal { opacity:0 } NOT .my-page .reveal { opacity:0 }), and have content_footer_html JS add that class as its FIRST line: document.querySelector('.my-page')?.classList.add('js-ready');. Live site: class added, CSS activates. Admin: class never added, content stays visible/editable.
Rule: Post-body formatting
Post-body formatting (post_content, group_desc). Structure: <p>, <h2>, <h3>, <ul>, <ol>. Image float: class="fr-dib fr-fil img-rounded" (left) or class="fr-dib fr-fir img-rounded" (right) + inline style="width: 350px;" on the <img>. Inline body images must be LANDSCAPE — never portrait/vertical (portrait inside a 350px floated container breaks text wrap). Source per Rule: Image URLs (inline body uses ?w=700 retina variant — intentional; imported fields use bare URL). On createSingleImagePost, default to a Pexels post_image + auto_image_import=1 unless the user opts out; on update, don't overwrite an existing image the user didn't mention. about_me: same structure rule; skip images unless the user explicitly asks.
Rule: Multi-image albums
Multi-image albums — one-shot rule. Import external URLs ONLY via createMultiImagePost (new album) or updateMultiImagePost (APPENDS to existing) — both take post_image CSV + auto_image_import=1. createMultiImagePostPhoto does NOT import; it records URLs as-is. Verify via listMultiImagePostPhotos property=group_id&property_value=<group_id>&property_operator== — NOT via getMultiImagePost.post_image (that field is a transient write-through, not a mirror of child rows). Success = non-empty file + image_imported=2; silent-failure = empty file + image_imported=0. Fix: deleteMultiImagePostPhoto the bad row, then updateMultiImagePost group_id=<same>&post_image=<replacement>&auto_image_import=1. Never delete and recreate the whole album. If an append returns success but no new child row appears within ~10s, the MCP client may be on a stale tool schema that dropped post_image from updateMultiImagePost — reconnect the client. The field is supported server-side. Renaming via group_name does NOT update group_filename (the URL slug) — see Rule: URL slug rename.
Swapping a photo at a specific slot. BD's append does not reliably reuse the vacated order value; new photos can collide on order=0 and shuffle the visible sequence. Pattern: (1) read the target's order via listMultiImagePostPhotos, (2) deleteMultiImagePostPhoto photo_id=<old>, (3) updateMultiImagePost group_id=<same> post_image=<new URL> auto_image_import=1, (4) re-list to find the new photo_id (its original_image_url matches the new URL), (5) updateMultiImagePostPhoto photo_id=<new> order=<captured>. Skip step 5 only when swapping the last slot.
Rule: URL slug rename
URL slug on rename — posts + albums only. post_filename / group_filename are writable; renames don't regenerate them. Slugify the new title and compare to the current slug — if <50% tokens overlap, suggest two follow-ups (do NOT execute without approval): update the slug, and createRedirect old_filename=<old_slug> new_filename=<new_slug>. Stay silent on typo fixes or title tweaks that keep the same keywords. Before createRedirect, filter listRedirects property=old_filename&property_value=<old_slug>&property_operator== — if a row exists, update it instead of creating a second one. (BD blocks old==new; don't bother pre-checking.) Always verify the slug actually changed via get* after the update — if BD returned success but the slug is unchanged, the MCP client is on a stale tool schema that dropped the field; reconnect, don't create a redirect pointing at a 404. Rule excludes WebPage slugs — those are locked to page type.
Top/Sub category rename — bound-page guard fires on first match only. updateTopCategory / updateSubCategory rename rejects when ANY seo_type=profile_search_results page contains the old slug as a path segment. The error names ONE blocking page; if multiple pages share that segment, fixing one and retrying will hit the next. Pre-flight all bound pages BEFORE attempting the rename. Run two filtered LIKE queries (bidirectional %foo% is rejected — see Rule: Filter operators): listWebPages property=filename property_value=<slug>% property_operator=like (right-anchor) AND listWebPages property=filename property_value=%<slug> property_operator=like (left-anchor); union the results client-side. On a real directory site this typically surfaces 5-10 pillar + city-spoke pages bound to one sub-category slug. Address all of them in one pass (rename each page's filename + create a redirect for each), then attempt the category rename. Going one-at-a-time burns rate limit and creates a half-renamed taxonomy mid-flight.
Rule: Site grounding
Site grounding - call getSiteInfo once on the first BD task of a conversation and cache for the session. Tiny payload (~1KB) that tells you what kind of directory this is: website_id (tenant ID for centralized-admin URLs), website_name, full_url (use for composing public URLs), profession (SITE-level target member archetype — NOT a member's profession_id), industry (site's market vertical), locale (timezone, date_format, distance_format), currency fields, and brand_images_relative/brand_images_absolute URLs (8 slots each — logo, mascot, background, favicon, default_profile_image, default_logo_image, verified_member_image, watermark), and default_checkout_url (plan signup-URL path segment — see Rule: Public URL composition). Use default_profile_image to detect placeholder photos (if a member's image_main_file matches it, there's no real photo). profession and industry are site settings — NEVER conflate with per-member profession_id taxonomy.
Rule: Public URL composition
Public URL composition. If a response includes the_public_url, use it verbatim — it's the full absolute URL, no lookup needed (single records only, not list* / search* rows). Otherwise compose it: getSiteInfo's full_url + / + the record's slug — filename, post_filename, or group_filename. Never guess the origin. If full_url isn't cached, call getSiteInfo first. About to write a literal domain not from full_url? Re-call getSiteInfo — that's a hallucination signal.
Plan signup/checkout URL. Read custom_checkout_url via getMembershipPlan + include_extras=1 — it's EAV-stored, so lean reads omit it and you'd wrongly fall back. Trim it, then:
absolute URL (starts with
http) → use verbatim (a site may point a plan at external checkout).slug/id → compose
getSiteInfo'sfull_url+/+default_checkout_url+/+ the trimmed value.empty/whitespace/absent → same compose with
subscription_idas the final segment.
default_checkout_url varies by site (checkout, join, signup, …) — use the returned value, never hardcoded. full_url has no trailing slash; single-/ joins. E.g. https://site.com/checkout/2.
Rule: Icons
An icon you add is a Bootstrap Icons 1.13.1 icon unless the user names another icon set: <i class="bi bi-NAME"></i> in HTML, and content: bi(NAME) in an updatePageCss rule (the tool writes the glyph and its font). Font Awesome 4.7 also loads on every page: use it when the user asks for it, and in the settings whose field takes a Font Awesome class. Icons in one place share one colour and size unless the user asks for a different one.
Rule: Brand kit
Brand kit - call getBrandKit ONCE at the start of any design-related task (building a widget, WebPage, post template, email, hero banner - anything where colors or fonts are chosen) so your output visually matches the site's brand. Returns a compact semantic palette (body / primary / dark / muted / success / warm / alert accents, card surface) plus body + heading Google Fonts, with inline usage_guidance explaining which role each color plays and tint rules. Cache the result for the rest of the session - the brand kit rarely changes within one conversation. Derive hover/tinted/gradient colors from the returned palette values - never introduce unrelated hues. The returned body.font and heading_font are already globally loaded on the site; do NOT redeclare them in content_css unless deliberately switching to a different family (and then @import the new Google Font in the same CSS).
Rule: Hero readability bundle
When enable_hero_section flips from 0/unset to 1 or 2 (on createWebPage or updateWebPage) and the user hasn't supplied values, send all listed fields atomically — BD's field-level defaults render the hero unreadable against a background image.
h1_font_color="rgb(255, 255, 255)"h2_font_color="rgb(255, 255, 255)"hero_content_font_color="rgb(255, 255, 255)"hero_content_font_size="18"hero_content_overlay_color="rgb(0, 0, 0)"hero_content_overlay_opacity="0.5"hero_top_padding="100"hero_bottom_padding="100"hero_column_width="5"
Atomic — never a subset. Applies to every hero-enabled seo_type. On updates that don't touch enable_hero_section, do NOT re-apply defaults; respect the user's existing values and change only the field they asked about.
Disabling the hero — set enable_hero_section=0, period. Stored bundle values are preserved server-side; re-enabling restores the user's last-known look instantly with no autofill. Do NOT loop deleteUserMeta / updateUserMeta to clear bundle fields on a disable request — that's destructive, slow, and not reversible. Only wipe values when the user explicitly says "wipe / reset / clear all hero values."
Rule: Hero gap-fix CSS
Hero gap-fix CSS rule - seo_type=content ONLY. For WebPage heroes, never the homepage: the homepage gap is Design Settings hero padding (custom_164 top, custom_165 bottom) and row spacing via home_rows. When a content page has hero enabled, BD inserts a ~40px white clearfix spacer between the hero and the first content section. Add .hero_section_container + div.clearfix-lg {display:none} to content_css to close the gap. Never add this rule on any other seo_type - on profile_search_results / data_category / etc., the clearfix provides necessary spacing before the live search-results block; hiding it makes results butt-join the hero. Rule is page-type-scoped, period.
Rule: WebPage cache refresh
Cache refresh is automatic on createWebPage / updateWebPage. Both tools server-side fire refreshCache(scope=web_pages) on success (including hero/EAV-field writes) and return auto_cache_refreshed: true in the response, or auto_cache_refresh: "scheduled" when the refresh is queued to run shortly together with other writes. Either is normal; no manual call needed. If the response shows auto_cache_refreshed: false, check auto_cache_refresh_error and retry refreshSiteCache once.
Rule: Image sourcing
Image sourcing - priority order. When the user asks for or implies a content image (hero banner, Design Settings hero image custom_76 / slideshow slides, member cover_photo, post post_image, etc.) without supplying a URL, walk this ladder TOP-DOWN and stop at the first one that yields a real image. Do NOT skip tiers. (For identity-confirming fields — profile_photo, logo, social URLs — see Rule: Identity-confirming fields; the Pexels stock (fallback) tier does NOT apply.)
User-supplied URL — if given, use that.
The subject's own web presence (only when the write names a specific real entity — person, business, school, product, institution). Try in order: (a) their official website homepage / brand-asset page, (b) their About / team / staff-bio page, (c) their verified social profiles — Facebook profile photo, LinkedIn headshot, X profile photo, Instagram bio photo, YouTube channel art, TikTok profile photo — confirmed to belong to THIS exact person or business. Use the direct image URL. Do NOT attempt
<head>meta tags (og:image,twitter:image) — agent-side WebFetch strips<head>before the model sees it; these are unreadable.Pexels stock (fallback) — ONLY when the write is generic and not about a named entity (category landing page, topic-page hero with no specific person in focus). Never for
profile_photo/logo/website/social URLs (facebook,linkedin,x,twitter,instagram,youtube,tiktok) on a real entity record (see Rule: Identity-confirming fields).
Never disclose image sources in user-visible content. No "Stock photos via Pexels," no "Image courtesy of...," no "via Unsplash/Pixabay/etc.," no source credits, no internal sourcing commentary — anywhere a recipient or site visitor will read it. Sourcing is an agent-side workflow, never recipient-facing copy. Applies to every body/content field across BD: email_body, post_content, group_desc, WebPage content, about_me, hero copy, captions — anywhere user-visible text is composed.
Rule: Identity-confirming fields
Identity-confirming fields — verified source or OMIT. On createUser / updateUser or any record representing a real person or business, these fields are IDENTITY-CONFIRMING and bypass the Pexels stock (fallback) tier in Rule: Image sourcing: profile_photo, logo, website, facebook, linkedin, x, twitter, instagram, youtube, tiktok. A value is valid only if you actually retrieved it from the subject's own web presence tier in Rule: Image sourcing. Stock photos and invented domains misrepresent the person. If the User-supplied URL and subject's own web presence tiers yield nothing, OMIT the field and tell the user: "no confirmed [photo/website/social] found for [name] — record created without it; add later when verified." Do NOT fall through to Pexels for these. Do NOT fabricate website domains.
Rule: Plan-gated image fields
User image fields are plan-gated — pick the supported one or skip. Membership plans control which image fields are even displayed in the BD dashboard. Toggles live in users_meta — query listUserMeta database=subscription_types database_id=<user's subscription_id> once per task and read three keys: show_profile_photo, show_logo_upload, coverPhoto (note camelCase on cover; other two snake_case). All three are "1"/"0". Routing for the headshot/icon image — applies whether the user named a field (logo/profile_photo) explicitly or not: both show_profile_photo=1 AND show_logo_upload=1 → use profile_photo if the user said "profile photo" or didn't specify; use logo only if they said "logo." Only show_profile_photo=1 → use profile_photo (re-route silently if user asked for logo; mention it in the response: "logo isn't enabled on this plan — set as profile_photo instead"). Only show_logo_upload=1 → mirror: use logo, re-route + mention if user asked for profile_photo. Both 0 → skip, tell user "this plan has profile photo AND logo disabled — enable one on the plan, or skip the image." Cover photo (coverPhoto): 1 → cover_photo writable; 0 → skip cover (no fallback — different visual slot). Writing to a disabled field is wasted — BD hides it and auto-clears on the next save.
Rule: Image URLs
Applies to all image fields, all contexts.
Imported fields (
post_image,hero_image,logo,profile_photo,cover_photo,original_image_url) — bare URL, no?query string (BD's filename generator breaks on it). Wrapper auto-strips query strings on these fields if you forget; write the bare URL anyway so the corpus and the wire match.Inline
<img>in Froala body (post_content,group_desc) — hotlinked; Pexels?w=700(2x the 350px display width for retina sharpness). Design Settings images are hotlinked too: their note gives the size.Orientation gate for Pexels-sourced feature image slots.
post_image,hero_image, and multi-image album photos require landscape — verify viagetImageDimensionsper Rule: Image dimensions. Inline<img>in Froala body (post_content,group_desc) and email-template body (email_body) prefer landscape or square; portrait acceptable.Pexels sourcing workflow. Use this when an image is needed and Rule: Image sourcing routes to Pexels. Pexels does NOT respect keyword orientation filters (no
wide/landscape/horizontalkeyword reliably surfaces landscape-only; those words search the photo's title/tags).www.pexels.com/search/*returns HTTP 403 to agent-side WebFetch on common runtimes (claude.ai); the WebSearch route below reaches Pexels via Google's index and is not gated.WebSearch query="site:pexels.com/photo <2-3 word topic>"— 2-3 words, every word must carry topic information (no filler, no redundant adjectives); 2 words when the noun is already specific ("pilates reformer"), 3 words when it isn't ("pasta plate restaurant"); 1-word queries are banned (return noise pool). Returns ~10 result URLs of the shapehttps://www.pexels.com/photo/<slug>-<id>/.Pick a candidate at a random index in the first ~10 results rather than defaulting to #1 — anti-clustering across runs on the same site.
Extract
<id>(trailing digits before the final/) and construct the bare canonicalhttps://images.pexels.com/photos/<id>/pexels-photo-<id>.jpeg.Vet candidates with
getImageDimensionsper Rule: Image dimensions (batch 2+ into oneurls=call) — pass only onstatus: "success"+orientation === "landscape". Any other outcome drops the candidate; try the next random index from the same pool.Rotate. Never reuse an ID from earlier in the same skill run. Vary the search topic across posts (
pilates class→pilates reformer→pilates studio).Survivors flow to Rule: Image dedup before BD commit. On a dedup hit, try the next random index from the same pool. If the entire pool is dupes, run a new
WebSearchwith a varied topic phrase and pick from that pool. One more variation if the second pool is also exhausted.Last resort. If three varied searches still surface only dupes, accept the dupe rather than ship a post without an image — name the reused URL and source table in the audit (
data_postsorusers_portfolio). If WebSearch returns nothing across both varied queries, say "no Pexels result for [topic]" and skip — do not guess at random photo IDs.
User-supplied URLs (Pexels or other): use as-is — user choice is the authority. Batch submissions (multi-image CSV): run the workflow for each slot; if a slot returns nothing usable, drop it and name it. Refuse the whole batch only if zero slots fill.
Format:
.jpg,.jpeg, or.png. WebP/GIF/AVIF candidates are skipped before any tool call per Rule: Image dimensions.
Rule: Image dimensions
Wrapper-native tool: getImageDimensions. One candidate: url=<image URL>. Two or more: ONE call with urls=<comma-separated, up to 50> — all probed in parallel, one response with per-URL results in input order; a 404/timeout/parse failure is that URL's own error entry and never breaks the batch. Range-GETs the first 64KB of each JPG or PNG and parses the header to return { width, height, format, aspect_ratio, orientation }. orientation is landscape (w > h), portrait (h > w), or square (w == h). Per-URL { status: "error", message: <reason> } on 404, non-image content, parse failure, or unsupported format means drop that candidate.
Two-step usage for Pexels-sourced feature image slots (post_image, hero_image, Design Settings custom_76, mobile_custom_76 and slideshow slides, multi-image album photos via createMultiImagePost.post_image CSV + createMultiImagePostPhoto.original_image_url):
Extension filter — before the tool call. Only consider candidate URLs ending in
.jpg,.jpeg, or.png(case-insensitive). Skip.webp/.gif/.avif/ anything else outright — don't call the tool. BD's import + downstream rendering only handle JPG/PNG reliably; unsupported extensions break.Dimension check — call the tool. Require
status === "success"ANDorientation === "landscape"(portrait or square formobile_custom_76, set only when asked). Any other outcome — portrait, square, OR any error (404, timeout, parse fail, "unsupported image format") — means drop the candidate and pick another. No exceptions.
aspect_ratio (e.g. 1.5 for 3:2, 1.78 for 16:9, 0.667 for portrait) is the lever for tighter ratio gates when a skill needs them (e.g. "≥ 1.33" for 4:3, "≥ 2.0" for 2:1).
For inline body images and other non-feature slots, orientation is informational only.
See also: Rule: Image dedup (always runs AFTER orientation passes).
Rule: Image dedup
Required pre-write check. Never skip. Before any create* or update* call that writes a STOCK image URL (Pexels or other stock-photo source) to a FEATURE image field (post_image, original_image_url), dedup the URL against the matching storage table AND against the other URLs in the same batch. Inline <img> URLs inside post body content (post_content, group_desc) are NOT subject to site-wide dedup — they require intra-post uniqueness only: no body URL repeats within the same post, no body URL equals the post's own feature URL.
Match the dedup
list*to the write target. Single URL =eq + limit=1. Multiple candidates =inCSV. Response rows includeoriginal_image_url.post_imageoncreateSingleImagePost/updateSingleImagePost→listSingleImagePosts property=original_image_url property_value=<URL or URL1,URL2,URL3> property_operator=<eq | in>.original_image_urloncreateMultiImagePostCSV /createMultiImagePostPhoto/updateMultiImagePostPhoto→listMultiImagePostPhotos property=original_image_url property_value=<URL or URL1,URL2,URL3> property_operator=<eq | in>.
Trigger.
create*always triggers;update*triggers on every call that writes the image field — no self-attested no-op skip.Trigger scope. STOCK URLs only. Stock = generic licensable photo libraries (Pexels, Unsplash, Pixabay). Everything else (user-supplied URLs, subject-domain URLs / brand assets / the event or listing source's own image, CDN-hosted source-site images like Eventbrite/news/social CDNs) is non-stock and skips dedup entirely — legitimate reuse.
update*self-exclusion. When updating an existing record, exclude that record's own row from the dedup result set: forlistSingleImagePostshits, match bypost_id; forlistMultiImagePostPhotoshits, match byphoto_id. Hits on OTHER records still count as dupes.Batches (
createMultiImagePostCSV, or a multi-post skill run): (a) run the dedup call for EACH candidate URL, AND (b) dedup the candidates against EACH OTHER — two identical URLs in the same CSV is also a dupe. Reject and replace any URL that fails either check before committing the call.URL form to check. Use the bare canonical Pexels URL exactly as it gets stored:
https://images.pexels.com/photos/<id>/pexels-photo-<id>.jpeg(or.png). Exact match — no query string, no?w=suffix.
For Pexels candidate selection, retry strategy, and last-resort fallback, see Rule: Image URLs Pexels sourcing workflow.
Rule: Banned image sources
Banned image sources (never use, period):
Random/placeholder generators:
picsum.photos,lorempixel.com,placekitten.com, etc.Wikimedia / Wikipedia:
upload.wikimedia.org,commons.wikimedia.org,*.wikipedia.org/wiki/File:*, any/thumb/variant. Wikimedia enforces hotlink protection / User-Agent filtering - images render in a browser but serve an error placeholder on the live BD page.Restrictive-license sources: Getty, Shutterstock (watermark-stripped), Adobe Stock, etc. Reputational / legal risk.
If you reached for Wikimedia because the subject is a real entity (Juilliard, Harvard, a museum, a famous person), that's the wrong instinct - go to step 2 and pull from the subject's own website instead. Wikimedia isn't a "free alternative" for real-entity writes; the subject's own domain is.
Rule: users_meta identity
users_meta IDENTITY RULE (applies to every users_meta read, update, and delete - no exceptions). A users_meta row is identified by the PAIR (database, database_id) PLUS a key. The same database_id value can exist in users_meta pointing at different parent tables - e.g. database_id=123 might refer to rows in users_data, list_seo, data_posts, and subscription_types simultaneously, all unrelated records that happen to share the same numeric ID. Even low IDs like 1 routinely return hundreds of cross-table rows.
Safety rules (read, update, especially DELETE):
ALWAYS scope by BOTH
databaseANDdatabase_idtogether — neverdatabase_idalone. OnlistUserMeta/getUserMeta/updateUserMeta/deleteUserMeta, pass them as TOP-LEVEL args (first-class params, NOT insideproperty/property_value):listUserMeta {database: "users_data", database_id: 1}. Addkeyfor a single field:{database: "users_data", database_id: 1, key: "instagram"}. The wrapper enforces this via the 2-of-3 safety guard — single-field calls are rejected. One call, exact scope, no cross-table noise.NEVER loop-delete by
database_idalone - this WILL delete unrelated records on other tables.If a single-field query is ever unavoidable, CLIENT-SIDE filter results by
databasematch before acting — belt-and-suspenders for the destructive path.
A single mistake here can cascade-destroy member data, plan metadata, and page settings that happen to share the same ID across unrelated tables.
Rule: EAV auto-route
EAV auto-route — wrapper handles this, no agent action required. Some BD tables mix direct columns with EAV-stored fields in users_meta. You don't need to know which is which — just call the parent tool with whatever fields you want; the wrapper auto-detects EAV fields and routes the writes through users_meta. Do NOT call updateUserMeta directly for these.
On update calls the response includes eav_results confirming which EAV fields were written (and action: created for newly-seeded rows). On create calls the wrapper still routes the fields but does not surface a per-field receipt — verify via getWebPage/listUserMeta if confirmation matters. Reads merge automatically for getWebPage/listWebPages; getMembershipPlan does NOT merge users_meta values, read EAV-routed plan fields via listUserMeta directly.
BD's REST API itself silently ignores EAV fields on parent updates — without the wrapper, agents would have to know the EAV table by heart and route manually. The wrapper's table is the single source of truth.
Canonical auto-route table (parent table → fields → parent tool):
list_seo(WebPages, viaupdateWebPage):linked_post_category,linked_post_type,disable_preview_screenshot,disable_css_stylesheets,hero_content_overlay_opacity,hero_link_target_blank,hero_background_image_size,hero_link_size,hero_link_color,hero_content_font_size,hero_section_content,hero_column_width,h2_font_weight,h1_font_weight,h2_font_size,h1_font_size,hero_link_text,hero_link_url.users_data(Members, viacreateUser/updateUser): any field name not in the nativeusers_datacolumns auto-routes (compound identity(database='users_data', database_id=<user_id>, key=<field_name>)). Case-sensitive — BD's own column matching is case-sensitive, so a custom field namedAwardsroutes tousers_metawhile nativeawardswrites tousers_data. Form-builder custom fields (viacreateFormField/updateFormFieldon member forms or their clones) follow the same routing; see Rule: Forms.data_posts(Single-image posts of every type — blog, jobs, events, real-estate, digital products — viacreateSingleImagePost/updateSingleImagePost): any non-native field name auto-routes (compound identity(database='data_posts', database_id=<post_id>, key=<field_name>)).users_portfolio_groups(Multi-image / album posts, viacreateMultiImagePost/updateMultiImagePost): any non-native field name auto-routes (compound identity(database='users_portfolio_groups', database_id=<group_id>, key=<field_name>)).leads(viacreateLead/updateLead): any non-native field name auto-routes (compound identity(database='leads', database_id=<lead_id>, key=<field_name>)).users_reviews(viacreateReview/updateReview): any non-native field name auto-routes (compound identity(database='users_reviews', database_id=<review_id>, key=<field_name>)).
Do NOT call updateUserMeta directly for these — use the parent tool. Fields not on this list are NOT auto-routed; updateUserMeta requires an existing meta_id for them.
Delete cleanup: deleteWebPage deletes the list_seo row but does NOT cascade-delete the corresponding users_meta rows. After deleteWebPage(seo_id):
listUserMeta database=list_seo database_id=<deleted seo_id>(compound identity satisfies the 2-of-3 safety guard) to find orphan meta rows.For each row:
deleteUserMeta meta_id=<id> database=list_seo database_id=<deleted seo_id>— all three required.
Be SURGICAL - only delete meta rows where database_id exactly matches the deleted page's seo_id; NEVER bulk-delete across other database_id values or other database table values.
Rule: System timestamps
System timestamps (revision_timestamp, date_updated, modtime) are wrapper-owned — agent does nothing. The MCP wrapper resolves the site's timezone (getSiteInfo.timezone), renders the current time in that tz, and writes the field directly to the wire on every applicable create* / update*. Agents never see these fields in input schemas, never pass them, never have to think about them. Cache-busting, "Last Update" displays, audit trails — all reliable.
Sibling-field render-format inconsistency (read-side only). BD's read-back formatters aren't consistent across fields on the same record — e.g. post_live_date returns as ISO (2026-04-28T17:23:40+00:00) while post_start_date returns as 14-char (20260428172340) on the same getSingleImagePost row. Don't compute durations or sort across mixed-format timestamp fields without normalizing first. This is a BD read-formatter quirk, not a wrapper concern.
Bucket-B agent-set fields (rare, backfill only). A small set of timestamps still belong to the agent — only when the agent has a specific reason to set a non-current value (historical backfill, migration import, scheduled events). These remain in the input schema with the canonical format sentence on each:
createUser.signup_date/last_login— backfill legacy member data.createSingleImagePost.post_live_date/post_start_date/post_expire_date— campaign / event scheduling.createMemberSubCategoryLink.date/updateMemberSubCategoryLink.date— historical association timestamps.
Format for all Bucket-B fields: YYYYMMDDHHmmss in the site's timezone (14-digit, no separators). BD silently truncates other formats to 14 chars, corrupting the value.
Rule: Member search SEO pages
Member Search Results SEO pages - thin-content remedy. BD auto-generates dynamic search URLs for every location+category combo (e.g. california/beverly-hills/plumbers). Google penalizes thin pages (1-2 members). Convert to static via createWebPage with seo_type="profile_search_results" + filename=<exact slug> + custom SEO copy in content.
Slug hierarchy: country/state/city/top/sub — strict order, any subset valid (skip any segment from any position). Examples: country/state/city/sub, top/sub, country/state/top, state/sub, top alone, city alone, united-states alone. No leading slash; /-separated.
CRITICAL: filename MUST be a real location/category slug BD's dynamic router recognizes (wrapper validates this — see runtime guard). Arbitrary/made-up slugs (my-cool-page, foo-bar) return HTTP 404 publicly even though the list_seo record is created successfully - BD has no dynamic page to override. Bare category slugs (/strength-training) and full hierarchies (/california/los-angeles/personal-trainer) both work. For arbitrary-URL static pages with no underlying category/location route, use seo_type=content instead.
Every slug segment must come from live lookups:
listCountries- country slug = lowercase country_name with spaces -> hyphens (no country_filename field exists)listStates-state_filenamelistCities-city_filenamefor the slug. (BD schema typo: the city PK islocaiton_idNOTlocation_id- relevant only forgetCity/updateCitycalls, not for the slug that goes intofilename)listTopCategories-filenamelistSubCategories-filename
Before create, check existence: listWebPages property=filename property_value=<slug>.
Required defaults on create AND every update for profile_search_results pages (unless user overrides):
custom_html_placement=4form_name="Member Search Result"(sidebar - NOT "Member Profile Page", which is for member profile pages)menu_layout=3(Left Slim)updated_by(optional audit label like "AI Agent" or "API")enable_hero_section=1+ a content-relevant Pexels hero image + apply the hero safe-defaults bundle from Rule: Hero readability bundle (atomic — every value, every write). Most end-users won't know to ask for a hero; it's the default because thin-SEO pages underperform without one. Source the image per Rule: Image sourcing (Pexels large variant URL; never picsum/placekitten/random generators). Sethero_imageto the chosen URL. (Cache flush is automatic post-write.) User can opt out withenable_hero_section=0if they prefer a plain page.
Auto-generate SEO meta for the specific location+category combo using human names (not slugs) with natural "[city] [category]" / "in [location]" phrasing:
title(50-60 chars)meta_desc(150-160 chars)meta_keywords(~200 chars)facebook_title(55-60 chars, differ from title)facebook_desc(110-125 chars)
Do NOT auto-set facebook_image - needs a user-uploaded asset.
H1/H2 double-render trap: if hero enabled AND content contains <h1>/<h2>, both render. Pick one location - not both.
On these pages, NEVER set max-width or margin: auto in content_css on any selector. BD's layout owns width. If a full-width page needs a contained section, use <div class="container"> in content — it's the system global.
Location + Sidebar CRUD are read-only by design in this MCP (create/delete deliberately omitted to prevent collisions with BD's auto-seeding and system layouts).
Rule: Post search-results SEO pages (seo_type=data_category)
A seo_type=data_category page attaches custom SEO content to a post type's main search-results page or to a category-specific page. Pin via linked_post_type (REQUIRED — post type's data_id from listPostTypes) plus linked_post_category (literal post_main_page OR an exact case-sensitive category name from feature_categories). Wrapper auto-defaults linked_post_category=post_main_page when omitted, and enforces pair-uniqueness on (linked_post_type, linked_post_category) — only ONE data_category page per combo. Transitioning AWAY from data_category releases the slot, strips orphan meta, and retires the placeholder-slug redirect; you MUST supply a new filename on the transition update because the wrapper-managed placeholder 404s on every other seo_type. filename is wrapper-managed on data_category — a fresh 10-char lowercase alphanumeric slug is generated whenever the value isn't already 10-char alphanumeric. The public URL is <post_type.data_filename>?category[]=<Exact%2BCategory%2BName> (or just <data_filename> for post_main_page) — encode spaces as %2B. The wrapper auto-creates a 301 redirect from the placeholder to that destination on every successful write, and cascades the redirect-delete on deleteWebPage.
Wrapper response annotations (echoed on _data_category_* keys on success bodies):
Success echoes:
pair,autofilled,filename_generated,redirect,orphans_stripped,redirect_retired,redirect_deleted.Failure echoes (best-effort step couldn't complete; parent write still committed):
redirect_failed,orphans_strip_probe_failed,redirect_retire_failed,redirect_delete_failed. Each carries a<reason>. A retire/delete failure may leave a zombie redirect — manualdeleteRedirectif needed.
Rule: Resource disambiguation
Before editing any resource the user named by description, resolve to a stable ID and confirm — semantic similarity is NOT a match.
Layer ambiguity (the most common trap). "Edit my classifieds page" / "the events page" / "the members page" can mean any of: a seo_type=content WebPage with that slug; the post type's category_header/search_results_div/category_footer code group (updatePostType); the Member Listings post type's UI (data_type=10); a seo_type=data_category SEO page pinned to that post type; a top or sub category landing page. ALWAYS confirm WHICH layer before mutating, even when only one record string-matches.
Resolution algorithm.
Verbatim match on
data_name/system_name/data_filename(case-insensitive) → propose that record AND the layer interpretation; confirm before writing.Multiple plausible matches → STOP. List candidates with their distinguishing fields (
data_id,data_name,data_filename,data_typefor post types;seo_id,filename,seo_typefor WebPages; etc.). Ask which one.Semantic match only (no verbatim hit, but the description loosely fits one or more records) → STOP. Treat as multi-match. Never proceed on similarity.
User named a stable ID (
data_id=6,seo_id=42,data_filename="/classifieds") → unambiguous, proceed.
Trap classes (apply the algorithm whenever the user's reference falls in one of these): post types, categories (top vs sub same name), WebPages with similar title/filename, member profiles named only by first name, post records with reused titles.
Rule: Homepage
The homepage's visible content is built from Design Settings, NOT edited with updateWebPage.
getDesignSettings/updateDesignSettings: hero titlecustom_130, subtitlecustom_131, hero image, call to action, sections, their order (home_rows), spacing / background, colors, fonts.updateWebPageon theseo_type=homeWebPage, ONLY for: SEO tags, social share tags, page HEAD / footer JS, andcontent(Custom Content 1, shown only while a row holdsHomepage Content); the homepage never shows itsh1,h2orhero_*. Homepage-only CSS:updatePageCsswithoutseo_id(read:getWebPageinclude_code=1); Design Settingscode.cssis sitewide.Owner quotes homepage text or names a section:
getDesignSettingsfind; edit where the hit says. A colour or style to change or remove across the homepage:findits value (rgb(240, 173, 78),border-radius,box-shadow); each hit is a place that still holds it. Section named by position (first, last, above or below another):getDesignSettingswithout arguments returns the current row order; the target is the row at that position.Section of members, posts, events or other site records: a streaming section, never a custom widget with its own query:
getDesignSettingshome.rowslists them; place it withhome_rows; redesign it per the last line.New section: first
createWidget(markup per Rule: Widget code fields and Rule: Brand kit, CSS inwidget_style; its markup is one<section class="x" id="x">whose first child is<div class="container">, the layout inside that); then oneupdateDesignSettingssets a freehomepage_content_N(custom_content.free) to[widget=<name>](never HTML) and placescontent.Nwithhome_rows. Only when 2..10 are full:content(Custom Content 1) as one[widget=<name>]. Existing HTML (content, legacy blocks): edit in place, never convert unasked.Redesign or new layout of a section or the hero: customise its
widget(updateWidgetwidget_name,customize:true, with whole code fields orreplace). In any widget: a redesign rewrites its HTML with your own classes and leaves the PHP as is; a small change edits only that part; a data or logic change (show a field, add a condition) edits the PHP. Keep the ids, names,data-attributes and classes its scripts read. Its CSS goes in itswidget_style, never in page CSS. Never edit or copyBootstrap Theme - Custom Appearance Settings.
Rule: Sidebars
Sidebars - form_name field on WebPages is the SIDEBAR name, not a contact-form slug (BD's field is misnamed). On post types, the equivalent field is category_sidebar (same value set, different variable name).
When setting a sidebar on any page or post type, the name must match one of:
(a) The Master Default Sidebars (always available, never in listSidebars output - hardcoded in BD core, verbatim order from the admin UI dropdown):
Global Website SearchMember Profile PageMember Search ResultPersonal Post FeedPost Search ResultPost Single Page
(b) A custom sidebar row returned by listSidebars.
Empty string = no sidebar.
If the user names a sidebar that's in NEITHER list, DO NOT send it to BD (the page will render with no sidebar). Instead: ask the user to pick from the valid options - list both master defaults and any customs you find.
Position is controlled by menu_layout:
1= Left Wide2= Right Wide3= Left Slim (default onprofile_search_resultspages)4= Right Slim
Post category values are per-post-type dropdowns configured by the site admin - NOT a global taxonomy, and there is no createPostCategory tool. Before setting post_category on a post create/update, call getSingleImagePostFields (by form_name) or getPostTypeCustomFields (by data_id) and read the allowed values from the schema. Pass only values that appear there. If the user names a category not in the list, ask whether to pick the closest existing option or have them add it in BD admin first - don't invent values. (This is different from member categories, which ARE created via the API via createTopCategory/createSubCategory or auto-created by createUser.)
Lead routing - when to override auto-match: createLead accepts users_to_match (comma-separated member IDs or emails, mixed allowed). When set, BD bypasses the normal category/location/service-area auto-matching and routes the lead to ONLY those members. Use when the caller already knows who should receive the lead (external routing logic, round-robin assignment, VIP escalation). Typically paired with auto_match=1 (runs the match step inline) and send_lead_email_notification=1 (fires the matched-member email) - without the email flag, matches are recorded silently.
Writes are live and immediately visible on the public site. Confirm before any destructive or mass-modification operation. For reversible removal, prefer updateUser with active=3 (Canceled) over deleteUser - the record stays queryable and can be reactivated.
Rule: Input sanitization
Security & input sanitization (every write, every resource). BD stores input verbatim on API writes - BD's backend protectUserInputs() is NOT invoked on the API path, so THIS rule is the only sanitization layer. Render-time escaping is inconsistent across BD views. Reject writes that contain obvious injection payloads - asking the user to confirm if it looks intentional.
Pattern matching is case-insensitive for ALL listed patterns (not just ). Before matching, HTML-entity-decode the value once (turn <script> into <script>, turn &#x6a;avascript: into javascript:) and URL-decode once - an agent that matches only the raw form lets encoded payloads through. Reject patterns:
Script/markup tags:
<script>,</script>,<iframe>,<object>,<embed>,<svg ... on[a-z]+=(SVG is a common XSS vector via handlers), standalone<style>blocks on non-widget/non-email-body fields.Inline event handlers - pattern-match, not list-match: ANY
on[a-z]+=attribute pattern (onerror,onload,onclick,onmouseover,onfocus,onanimationend,ontoggle,onpointerdown,onwheel,onbeforeprint, etc. - 100+ DOM handlers, all fire XSS). Do NOT maintain a fixed list; match the pattern.Dangerous URL schemes (in
href,src, or any attribute):javascript:,data:text/html,data:application/,vbscript:. Plaindata:image/*(e.g.data:image/png;base64,...) is fine.CSS-injection patterns: inside any
style="..."attribute or<style>block, rejectexpression(,javascript:,data:,@import,behavior:(old-IE), or any URL scheme pattern.MySQL attack-shape fragments:
; DROP TABLE,UNION SELECT(adjacent OR comment-interspersed likeUNION/**/SELECT),OR 1=1adjacent to a quote/semicolon,' OR '1'='1,'/**/OR/**/'1'='1, trailing SQL comments (--or#followed by table/column-like tokens),xp_cmdshell,INFORMATION_SCHEMAqueries outside legitimate educational content.
Distinguish real content from attack shapes - "we DROP by the office at 5pm" is fine (no TABLE after DROP); "DROP the dose by half" is fine; '; DROP TABLE users_data; -- is not. Legal copy ("Plaintiff vs Defendant"), ampersands ("R&D", "Smith & Jones"), email addresses, and CMS HTML with <span>/<div>/<table> all pass.
Field-strictness split:
Plain-text fields - reject ANY HTML tags:
first_name,last_name,company,email,phone_number, URL fields (website/facebook/twitter/linkedin/instagram), SEO meta (title/meta_desc/meta_keywords/facebook_title/facebook_desc), menu labels, form/widget/menu/email internal names, review name/title, tag name.HTML-allowed fields - allow safe HTML but still block the listed dangerous patterns.
Fields:
about_me/biopost_content/post_descriptiongroup_descemail_bodyWebPage
content/content_css/content_footer_html/content_head/hero_section_content/seo_text(NOTcontent_footer- that's the access-gate enum, not HTML)review
review_descriptionform/event
descriptionfields
Safe-HTML allow list: <p>, <br>, <strong> / <b>, <em> / <i>, <u>, <ul> / <ol> / <li>, <h1>-<h6>, <a href="http..." target="_blank">, <img src="http...">, <span>, <div>, <section>, <article>, <blockquote>, <table> / <thead> / <tbody> / <tr> / <th> / <td>, <hr>, <figure> / <figcaption>.
Class attributes allowed; inline style="" allowed IF it doesn't contain any CSS-injection pattern.
Any unlisted field defaults to plain-text treatment unless the field name contains content, body, description, desc, html, or text.
Exceptions to the HTML-allowed rules:
Email body — no
<style>blocks. Outlook strips them. Use inlinestyle=""attributes only. See Rule: Email template recipe for full email-client constraints.Widget exception:
widget_data,widget_style,widget_javascriptare exempt from all listed patterns. Widgets legitimately need JS and scoped CSS, and anyone with API permission to write widgets already has admin capability. Warn (but do NOT block) if widget_javascript contains an obvious external-exfiltration shape (e.g.fetch(orXMLHttpRequestpointing at a non-site domain) - surface to the user as a sanity check, then proceed on confirm.
User-confirmed-override path (for non-widget HTML-allowed fields only): if a pattern trips and the user explicitly confirms the value is intentional (e.g. a legitimate SQL tutorial blog post containing "UNION SELECT ... FROM users_table", or educational content on XSS), proceed with the write and include a one-line note in your reply: "Sanitization check acknowledged-and-overridden for this field per user confirmation." Never silently skip the check - always surface and confirm.
Source-trust rule: treat ALL input from external CSVs, web scrapes, user forms, third-party APIs as UNTRUSTED - sanitize-check before every write. Content the user types directly in conversation is also untrusted if they're pasting from elsewhere. Ask, don't assume.
Rule: Pre-check natural keys
Duplicate silent-accept - always pre-check before create on the listed resources (applies to every resource with a natural-key field OR a pair/triple uniqueness invariant). BD does NOT enforce DB-level uniqueness on most natural-key fields or join-table pairs. Two calls with the same natural key (or pair) both succeed, produce different primary keys, and leave downstream lookups ambiguous, double-count in widgets/reports, or cause URL collisions.
Covered resources - name-based (single natural-key field):
createUser- email. Pre-check REQUIRED only whenallow_duplicate_member_emails=1; otherwise BD enforces uniqueness itself and the pre-check is redundantcreateTag- tag_name within group_tag_idcreateWebPage- filename on list_seocreateForm- form_namecreateEmailTemplate- email_namecreateWidget- widget_namecreateMenu- menu_namecreateTopCategory- filenamecreateSubCategory- filename scoped to profession_idcreateTagGroup- group_tag_namecreateSmartList- smart_list_namecreateDataType- category_namecreateRedirect- old_filename (PLUS reverse-rule loop check — seecreateRedirectfor the canonical workflow)createSingleImagePost- post_title (URL slug derives from it)createMultiImagePost- post_titlecreateFormField- field_name scoped to form_name (duplicate field system-names on same form break submit). Agent-checked: runlistFormFields property=form_name property_value=<form> property_operator==first; on collision append_2/_3or pick a different stem. See Rule: Forms § Field anatomy.
Pair / composite uniqueness (join tables):
createLeadMatch- (lead_id, user_id) - prevents double-billing / double-matching the same lead to the same membercreateTagRelationship- (tag_id, object_id, tag_type_id) - prevents the same tag attaching to the same object twicecreateMemberSubCategoryLink- (user_id, service_id) - prevents a member being double-linked to the same Sub Category in rel_services
Standard pre-check: server-side filter-find, NOT paginate-and-search. Before every create on these resources:
Call the corresponding
list*withproperty=<field>&property_value=<proposed>&property_operator=eq- returns one tiny payload regardless of site size (sites have thousands of posts/widgets/redirects/rel_tags; dumping full lists wastes rate limit and context). For pair/composite uniqueness (the 3 join-table cases): filter server-side on the most-selective field, then check the other condition(s) client-side on the returned rows. Example pre-check beforecreateLeadMatch lead_id=X user_id=Y:listLeadMatches property=lead_id property_value=X property_operator=eq(returns rows for that lead — typically a small set), then client-side checkuser_id == Y. Same shape forcreateTagRelationship(filtertag_id, then checkobject_idandtag_type_idclient-side) andcreateMemberSubCategoryLink(filteruser_id, checkservice_id). A compound array filter also works here — see Rule: Compound filters — but the single-field + client-side check stays fine for these small result sets.If a match exists: reuse the existing ID, update instead, or ask the user. For name-keyed config resources an alternate name and re-check also resolves it; for content posts (
createSingleImagePost,createMultiImagePost) a shared title demands a record comparison, never a rename - the same real-world record means do NOT create.Only if zero rows, proceed with create - for content posts a free title alone is not proof of a new record; the create tools' pre-checks add date/venue probes.
Special-case resources - run the expanded workflow on createRedirect BEFORE the standard pre-check:
createRedirect- TWO filter-finds required: exact-pair skip + reverse-rule loop prevention (avoid A->B + B->A infinite loops).
Rule: users_meta orphans
Orphan users_meta rows after a parent-record delete - BD does NOT cascade. When you delete a parent resource, any users_meta rows attached to it stay as orphans; the agent must clean them up surgically (see Rule: users_meta identity - applies to all read/update/delete, not just this cleanup - (database, database_id) is atomic compound identity, and database_id-alone queries return cross-table noise).
Cleanup workflow after any parent delete:
listUserMetascoped by BOTHdatabase_id=<parent id>ANDdatabase=<parent table>via top-level args (first-class params, notproperty/property_value):listUserMeta {database: "<parent_table>", database_id: <parent_id>}. Returns only the orphan rows for this parent with no cross-table noise. The wrapper's 2-of-3 safety guard rejects single-field calls.For each matching row:
deleteUserMeta(meta_id, database=<parent_table>, database_id=<id>)- all three required.
Delete tools where this cleanup applies:
Confirmed EAV (4 tools):
deleteUser->users_datadeleteSingleImagePost->data_postsdeleteMultiImagePost->data_postsdeleteWebPage->list_seo
Probable EAV - run the scoped cleanup; zero rows is a normal expected outcome (12 tools):
deleteLead->leadsdeleteLeadMatch->lead_matchesdeleteForm->formsdeleteFormField->form_fieldsdeleteReview->users_reviewsdeleteMenu->menusdeleteMenuItem->menu_itemsdeleteWidget->data_widgetsdeleteEmailTemplate->email_templatesdeleteRedirect->301_redirectsdeletePostType/deleteDataType->data_categories
Tools NOT listed (tags, taxonomy links, sub-categories, smart lists, clicks, unsubscribes) typically don't have users_meta rows - if in doubt, run the scoped cleanup anyway; zero rows = clean, move on.
Never loop-delete by database_id alone (see Rule: users_meta identity).
Rule: Enum silent-accept
Enum silent-accept (applies across resources). BD's API does NOT strictly validate most integer-enum fields - it accepts values outside the documented set and stores them verbatim, with undefined render behavior. Examples: user.active=99, review.review_status=1 (doc says invalid), lead.lead_status=3 (doc says value 3 doesn't exist) - all three stored silently. Always pass only values from the documented enum set in each field's description. If a user asks for a non-documented value, ask them to pick from the documented set - don't pass through.
Rule: Cache refresh
Cache refresh. createWebPage / updateWebPage / createWidget / updateWidget / updatePostType auto-flush cache server-side — response carries auto_cache_refreshed: true when the flush succeeded, auto_cache_refresh: "scheduled" when it is queued to run shortly together with other writes, false + auto_cache_refresh_error when it didn't. On false, retry refreshSiteCache once; on true or "scheduled", do nothing. For Menus / Categories, call refreshSiteCache once after a batch of edits so public nav / directory pages reflect the changes.
Rule: No scaffolding tags
Never include CDATA, scaffolding wrappers, or entity-escaped HTML in any content-field value. Not as wrappers, not inline, not anywhere. BD stores every byte verbatim — these render as literal visible text on the live site, breaking layouts (page-wide for content_css, site-wide for widget_style).
Forbidden substrings in HTML / CSS / JS / PHP fields (e.g. WebPage content / content_css / content_head / content_footer_html / hero_section_content, Widget widget_data / widget_style / widget_javascript, PostType code-template fields, User about_me, Post post_content / group_desc): <![CDATA[, ]]>, <parameter, </parameter>, <invoke, </invoke>, <function_calls>, </function_calls>. Forbidden at whole-value level: entity-escaped HTML (<div>... — send <div>... instead).
These have no legitimate place in BD content. If your reasoning produced one, regenerate the value clean. The MCP server strips these tokens server-side as a safety net, but the rule is yours — do not rely on the net.
Rule: Write-echo not canonical
Write-time params ECHO on reads. Fields like profession_name, services, credit_action, credit_amount, member_tag_action, member_tags, create_new_categories, auto_image_import appear on read responses when they were set on a recent write - they are NOT canonical state, just residual input from the last write. Canonical state lives elsewhere: profession_id + profession_schema (top category), services_schema (sub-categories), credit_balance (current balance as dollar-formatted string like "$35.00"), tags array (current tags). Don't build logic that reads these echo fields as truth.
users_data.services dual-representation trap. The raw services field stores whatever the last write sent — either CSV of integer IDs ("3,4,5") OR a single Sub Category name ("Weight Loss") OR a CSV of names — depending on whether createUser/updateUser was called with IDs or names. Verified live: User 64 has services: "3,4,5,16,17,18", User 27 has services: "Weight Loss". Same column, two shapes. Always read sub-categories via services_schema (with include_services=1 on getUser/listUsers) — the hydrate resolves to canonical [{service_id, name, ...}] regardless of how services was written. On WRITES, prefer integer IDs to keep the field machine-parseable for downstream consumers.
Rule: Response type quirks
Response typing quirks to defend against:
Primary keys and counts come as STRINGIFIED integers (
user_id: "1",total: "114"), but pagination positions (current_page,total_pages) come as real NUMBERS. Coerce before comparison.Empty/absent collection-like fields can come back as literal boolean
falseinstead ofnull/[]/{}. Observed on user records:card_info,tags,photos_schema,services_schema,profession_schema,transactions,subscription_details,user_clicks_schema.clicks. Check!x || x === false || (Array.isArray(x) && x.length === 0)before accessing nested properties.filename_hiddenon user records is NOT reliable - on legacy records it can contain a different member's slug. Always usefilenamefor profile URLs, neverfilename_hidden.last_login="1970-01-01T00:00:00+00:00"means never-logged-in, not an actual 1970 login.Unpaid invoice
datepaid="0000-00-00 00:00:00"(MariaDB zero-date). Don't parse as ISO; treatdatepaid.startsWith("0000")as "unpaid."credit_balanceis a dollar-formatted string like"$35.00"or"-$24.50"(negative allowed - BD doesn't reject deducts that exceed current balance). Parse with/^(-)?\$(\d+\.\d{2})$/.
Rule: Sensitive fields
Sensitive fields present in read responses: user records include password (bcrypt hash), token (member auth token), and cookie (session value) - redact before logging responses. There are TWO one-char-different fields: user_id (numeric PK, stringified - e.g. "1") is the canonical identifier; userid (a cookie-like hash or null) is a legacy form-context field, ignore it.
filename fields (on users, posts, pages) are NOT stable across updates. BD regenerates the slug when inputs that influence it change - e.g. updateUser can rewrite a member's filename from /us/city/slug to /us/city/category/slug after a category change. This is expected behavior, not a bug. If you're embedding profile/post URLs in other content (a blog article, email, redirect, another member's bio), write/publish that content AFTER all updates to the referenced records are done, OR re-fetch filename via getUser/getSingleImagePost/getWebPage right before you use it. Never cache a filename across an update cycle.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| verifyTokenA | Verify API key - Verify that your API key is valid and check rate limit status. Use when: at the start of any session or batch job, to confirm the API key is valid and the site is reachable BEFORE burning rate limit on real calls. Also useful for surfacing a clear "bad credentials" error to the user early. Parameter interactions:
Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listFormInquiriesA | List Forms Inbox submissions - Paginated Forms Inbox submissions. Read-only. Use when: reading contact-form and lead submissions. Per-row fields: Search — one form, last 30 days, newest first: Dates on Pretty name to Filter/sort: Pagination: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getFormInquiryA | Get a single Forms Inbox submission - One Forms Inbox submission by Use when: you hold an Required: Returns: the See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUserFieldsA | Get user field definitions - Returns available fields for user records with labels and required flags. Use this to discover custom fields. Use when: building dynamic forms or importers - you need to discover which fields exist on the User record on THIS specific site (custom fields vary per BD site config). Also useful for validating import-CSV headers before running a batch. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listUsersA | List members/users - Get a paginated list of all members. Supports filtering by any user field and sorting. Lean-by-default keep-list: rows return only identity + routing + location core: Use when: enumerating members for reports, CSV exports, bulk status updates, analytics, or pagination through the full member base. Also used for lookups by field - pass Pagination: cursor-based. Pass Filter/sort: Enums: Filter-property rule - use ACTUAL field names: Filtering by TOP CATEGORY (profession): the filter column is Filtering by Payment-method field (under See also: Returns: Profile URL: every user record has a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUserA | Get a single member/user - Fetch a single user record. Read-only. Lean-by-default keep-list: same shape as Use when: you already have the Required: See also: Returns: Payment method on file (under Profile URL: every user record has a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createUserA | Create a new member/user - Create a member. Writes live data. Welcome email silent by default - set Required: Use when: adding members outside BD signup - CSV imports, scraped listings, Zapier automations, admin test accounts. Enums: Prerequisites: Parameter interactions:
Email uniqueness - controlled by site setting
Field validation quirks:
Profile URL: Fetching publicly available business data is permitted for imports and data enrichment. When searching for external listings, fetch each entity's image from their own presence in this order:
Pass the URL with If none yield a match, create/update without image and report "no confirmed image found." Never substitute a stock photo or guess. Skip an entire record and find an alternate listing only when the user explicitly requires images. See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateUserA | Update an existing member/user - Update a member. PATCH semantics - omitted fields untouched; send only what changes. Required: Disambiguation: apply Rule: Resource disambiguation when the user names this member by description (first name only, partial title) rather than by Use when: changing any field on an existing member. Prefer Enums: Parameter interactions:
Category assignment — for Email uniqueness - controlled by site setting
Field validation quirks:
Profile URL: Filename may regenerate on this update. BD rewrites the slug when category/city/URL-forming inputs change. Do NOT cache pre-update Fetching publicly available business data is permitted for imports and data enrichment. When searching for external listings, fetch each entity's image from their own presence in this order:
Pass the URL with If none yield a match, create/update without image and report "no confirmed image found." Never substitute a stock photo or guess. Skip an entire record and find an alternate listing only when the user explicitly requires images. See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteUserA | Delete a member/user - Permanently delete a user record by ID. Destructive - cannot be undone via API. Use when: the member record truly must be purged (GDPR request, test cleanup, confirmed duplicate). For reversible removal prefer Required: Parameter interactions:
See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| searchUsersA | Search members/users - Full-text search across members with category, location, and sorting options. Lean-by-default keep-list: same shape as Use when: (1) mirroring the public member-search experience - embedding search results in an external app, building a custom search-results page, or letting users search BD from outside the site; (2) verifying what is publicly findable for a given keyword / category / location combo (SEO coverage audits, "who shows up if a visitor searches X?"); (3) keyword / partial-name / location / category lookup in general. For exact-field lookup (by email, by user_id, by phone, by any admin column) use Pagination: cursor-based ( Enums: Parameter interactions:
See also: Returns: Profile URL: every user record has a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| loginUserA | Validate user credentials - Checks if email/password are valid. Does NOT return profile data - use getUser after. Use when: implementing SSO or a custom login flow against BD - you need to verify a member's email+password is valid WITHOUT starting a web session. Does NOT return profile data; follow with Required: Parameter interactions:
Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUserTransactionsA | Get member billing transactions (invoices) - Fetch the billing transaction history (invoices) for a specific member. Read-only. Backed by the WHMCS billing integration. Required: exactly one of Use when: you need to see a member's paid/unpaid invoices, payment methods, billing history, or reconcile billing status. Common reasons: answering a member's "what did I pay for?" question, exporting billing history, auditing revenue per member. See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUserSubscriptionsA | Get member subscriptions (membership plan history) - Fetch the subscription / membership-plan history for a specific member. Read-only. Backed by the WHMCS billing integration. Required: exactly one of Use when: checking a member's current membership plan, their billing cycle (Monthly/Yearly), next due date, plan upgrade history, whether auto-renewal is on, or past canceled subscriptions. See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listReviewsA | List reviews - Paginated enumeration of review records. Read-only. Lean by default: Use when: building moderation queues (filter Pagination: cursor-based ( Filter/sort: Enums: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getReviewA | Get a single review - Fetch a single review record. Read-only. Lean by default: Use when: investigating one specific review (usually from a moderation notification or support ticket that includes the Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createReviewA | Create a review - Create a new review record. Writes live data. Use when: importing legacy reviews from another platform, adding placeholder reviews for test data, or scripting review submissions from an external integration. Real member-submitted reviews come through the BD review form - only use this API when bypassing that form. Required: Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateReviewA | Update a review - Update an existing review record by ID. Fields omitted are untouched. Writes live data. Use when: moderating - change Required: Enums: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteReviewA | Delete a review - Permanently delete a review record by ID. Destructive - cannot be undone via API. Use when: the review content violates policy and must be purged (spam, abuse, PII). For "hide without removing" use Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listClicksA | List click records - Paginated enumeration of click records. Read-only. Use when: pulling click-tracking analytics for reports - profile views, phone reveals, website clicks, email clicks. Filter by Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getClickA | Get a single click record - Fetch a single click record. Read-only. Use when: rare - drilling into a specific click record by Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createClickA | Create a click record - Create a new click record. Writes live data. Use when: replicating a click event from an external source (e.g., tracking clicks on a mirrored profile page on another domain). Usually not needed - BD auto-records clicks on its own surfaces. Required: Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateClickA | Update a click record - Update an existing click record by ID. Fields omitted are untouched. Writes live data. Use when: correcting click metadata. Rare - click records are typically append-only analytics. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteClickA | Delete a click record - Permanently delete a click record by ID. Destructive - cannot be undone via API. Use when: removing test or spam click records from analytics. Does NOT affect the member's click counter if the site displays one. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listLeadsA | List leads - Paginated enumeration of lead records. Read-only. Use when: pulling the admin's lead inbox, generating lead reports, or iterating all leads to push into a CRM. For fetching one lead by ID use Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getLeadA | Get a single lead - Fetch a single lead record. Read-only. Use when: handling one lead - viewing its details after a lead-notification email, following up in a CRM integration, or confirming the lead exists before calling Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createLeadA | Create a lead - Create a new lead record. Writes live data. Use when: importing leads from an external form, CSV, or web-scrape. Default is SILENT - no notification emails fire unless you pass Required: Parameter interactions:
See also: Operational rules (from BD support article 12000091106):
Targeting specific members (override auto-match): set | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| matchLeadA | Auto-match lead to members - Triggers automatic matching - system finds members matching category, location, and service area, then sends notification emails. Use when: you've just created a lead (or need to re-distribute an existing one) and want BD to automatically email eligible members in matching category + location + service area. SIDE EFFECT: sends real emails to real members. Confirm with the user before calling on production data. Required: Parameter interactions:
Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateLeadA | Update a lead - Update an existing lead record by ID. Fields omitted are untouched. Required: Custom (form-defined) lead fields — e.g. wizard-style hidden See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteLeadA | Delete a lead - Permanently delete a lead record by ID. Destructive - cannot be undone via API. Use when: removing a spam or test lead. For preserving the lead but closing it, use Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listLeadMatchesA | List lead matches - Paginated enumeration of lead_matches records. Read-only. Use when: auditing who got notified about which lead - useful for billing reports (paid-per-lead sites) or explaining to a member why they did/didn't receive a lead notification. Filter by Empty-state quirk: BD returns Pagination: cursor-based ( Filter/sort: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getLeadMatchA | Get a single lead match - Fetch a single leadmatch record. Read-only. Use when: you have a specific Required: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createLeadMatchA | Create a lead match - Create a new leadmatch record. Writes live data. Use when: manually creating a lead↔member match BYPASSING BD's auto-matching. Rarely needed - usually Required: Pre-check before create (PAIR uniqueness): BD does NOT enforce uniqueness on the Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateLeadMatchA | Update a lead match - Update an existing leadmatch record by ID. Fields omitted are untouched. Writes live data. Use when: recording a member's response to a lead ( Required: Enums: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteLeadMatchA | Delete a lead match - Permanently delete a leadmatch record by ID. Destructive - cannot be undone via API. Use when: cleaning up an erroneous match (e.g., test data) or removing a match that was auto-created but shouldn't exist. Does NOT unsend the notification email that may have already fired. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listSingleImagePostsA | List posts - Paginated enumeration of post records. Read-only. Lean-by-default keep-list: rows return only the core identity + routing + load-bearing fields:
Use when: enumerating posts of single-image families - blog articles, events, jobs, coupons, videos, discussions. Filter by Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getSingleImagePostA | Get a single post - Fetch a single post record. Read-only. Lean-by-default keep-list: response returns only the core identity + routing + load-bearing fields: Use when: fetching one post by Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getSingleImagePostFieldsA | Get post field definitions - Returns custom fields for a specific post type form. Use when: discovering the per-post-type custom fields before building a create/update payload. Pass Required: Returns: a BARE ARRAY of field-definition objects (NOT wrapped in Silent-fallback warning: if
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createSingleImagePostA | Create a post - Create a new post record. Writes live data. Use when: creating a blog article, event, job listing, coupon, or any other single-image post type. Look up Required: Pre-check before create: BD does NOT enforce uniqueness on Parameter interactions:
See also: Which endpoint to use - Every post type in
If you call the wrong create endpoint for a given post type, BD may accept the row but it won't render on the public site correctly. For "make a blog post" intent: look up For "make a photo album" / "gallery" intent: look up the album post type (often Picking | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateSingleImagePostA | Update a post - Update an existing post record by ID. Fields omitted are untouched. Writes live data. Use when: editing post content, switching from draft to published ( Required: Enums:
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteSingleImagePostA | Delete a post - Permanently delete a post record by ID. Destructive - cannot be undone via API. Use when: removing a post permanently. For "hide without deleting" use Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listMultiImagePostsA | List album groups - Paginated enumeration of portfoliogroup records. Read-only. Lean-by-default keep-list: rows return only the core identity + routing fields: Use when: enumerating photo-album / gallery-style posts (Photo Album, Classified, Property, Product - any post type with Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMultiImagePostA | Get a single album group - Fetch a single portfoliogroup record. Read-only. Lean-by-default keep-list: same shape as Use when: fetching one multi-image post by Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMultiImagePostFieldsA | Get album group field definitions - Fetch field definitions for a multi-image post type form. Read-only. Use when: discovering per-post-type custom fields for multi-image posts - same pattern as Required: Returns: a BARE ARRAY of field-definition objects (NOT wrapped in Silent-fallback warning: if | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createMultiImagePostA | Create an album group - Create a new portfoliogroup record. Writes live data. Use when: creating a photo album, gallery, product listing with multiple photos, or any post type with Required: Pre-check before create: BD does NOT enforce uniqueness on Parameter interactions:
Post-create verification (critical): HTTP 200 does NOT mean every photo imported. After create, call See also: Returns: Which endpoint to use - Every post type in
If you call the wrong create endpoint for a given post type, BD may accept the row but it won't render on the public site correctly. Category for multi-image posts: multi-image posts do NOT expose | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateMultiImagePostA | Update an album group - Update an existing portfoliogroup record by ID. Fields omitted are untouched. Writes live data. Use when: editing metadata (title, description, Required: Enums: Verify appended photos via
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteMultiImagePostA | Delete an album group - Permanently delete a portfoliogroup record by ID. Destructive - cannot be undone via API. Use when: removing the entire album. Recommended sequence: delete child photos first via Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listMultiImagePostPhotosA | List album photos - Paginated enumeration of portfoliophoto records. Read-only. Lean-by-default keep-list: rows return Use when: fetching all photos within a multi-image post - always pass Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMultiImagePostPhotoA | Get a single album photo - Fetch a single portfoliophoto record. Read-only. Lean-by-default keep-list: same shape as Use when: editing or removing one specific photo within an album. You need the Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createMultiImagePostPhotoA | Create an album photo - Create a new portfoliophoto record. Writes live data. Use when: adding ONE image to an existing album where the image is already hosted on the BD site (or hotlinking is acceptable). The parent album must exist (call Does NOT import external URLs. This endpoint has no Required: Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateMultiImagePostPhotoA | Update an album photo - Update an existing portfoliophoto record by ID. Fields omitted are untouched. Writes live data. Use when: reordering photos within an album ( Required: Cannot re-import a failed image. Only writes See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteMultiImagePostPhotoA | Delete an album photo - Permanently delete a portfoliophoto record by ID. Destructive - cannot be undone via API. Use when: permanently removing one photo from an album. For "hide" use Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listPostTypesA | List post types - Paginated enumeration of posttype records. Read-only. Lean-by-default keep-list: rows return only the core identity + routing fields:
Use when: discovering which post types exist on this site AND their Reserved data_types — default-excluded. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getPostTypeA | Get a single post type - Fetch a single posttype record. Read-only. Lean-by-default keep-list: same shape as Use when: checking the configuration of one post type (which Required: Code-field master-fallback: the up to eight HTML/PHP code fields on every post type record ( Reserved data_types — not reachable here. If the resolved record's See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getPostTypeCustomFieldsA | Get custom fields for a post type - Fetch a single posttypecustomfields record. Read-only. Use when: building a create/update payload for a post type that has custom fields (most do). Returns the exact per-type schema to send. Required: exactly one of Parameter interactions:
Discovering enumerated field values (e.g. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updatePostTypeA | Update a post type - Update a post type. PATCH semantics (except per Rule: Post-type code fields). Writes live data. Cache refresh is automatic. Response includes Required: Picking the right post type — disambiguation. Apply Rule: Resource disambiguation before editing. "Edit my classifieds page" is layer-ambiguous (a WebPage vs. the post type's code group vs. Member Listings UI vs. a category landing) — confirm WHICH layer even when only one record string-matches. Resolve to Use when: toggling a post type active/inactive, renaming, changing per-page display counts, editing search-results UI or profile-page code. For Member Listings specifically: tuning keyword-search, pagination, sidebar, sort order. Custom field DEFINITIONS live in BD admin UI, not API. Universal structural safety - NEVER mutate these fields on ANY post type: MEMBER LISTINGS SPECIAL CASE ( Member Listings cheat-sheet (12 commonly-edited UI/UX settings + 3 search-code fields - NOT a limit, any real column is writable per schema-is-documentation): Member Listings guardrails (apply ONLY to
CODE FIELDS - master-fallback on GET + all-or-nothing save per group. Up to 8 code-template fields begin life backed by BD's MASTER post-type template; they only persist locally when saved. GET returns master value for un-customized fields (agent sees real rendered code, not empty string). Writing ANY field in a group requires sending ALL fields in that group (unchanged fields copied verbatim from prior GET); omitting group-mates causes them to drift back to master on next render. Groups:
Code-edit workflow:
Code-field trust level: all 8 code fields are widget-equivalent - accept arbitrary HTML/CSS/JS/iframes/PHP (BD evaluates PHP server-side at render). XSS/SQLi sanitization rules do NOT apply - anyone editing post-type code already has full site code control. Supports PHP variables ( Member Listings code edits affect every member-search page on the site - confirm intent with user before editing Member Listings code fields. See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deletePostTypeA | Delete a post type - Permanently delete a posttype record by ID. Destructive - cannot be undone via API. Use when: removing a post type entirely. Existing posts of this type become orphaned - consider migrating them to another type first via a bulk Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listUnsubscribesA | List unsubscribe records - Paginated enumeration of unsubscribe records. Read-only. Use when: auditing the email unsubscribe list - useful for compliance (GDPR, CAN-SPAM) or before launching a new email campaign. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUnsubscribeA | Get a single unsubscribe record - Fetch a single unsubscribe record. Read-only. Use when: checking one unsubscribe record by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createUnsubscribeA | Add email to unsubscribe list - Create a new unsubscribe record. Writes live data. Use when: programmatically adding an email address to the Unsubscribe List. Required:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateUnsubscribeA | Update an unsubscribe record - Update an existing unsubscribe record by ID. Fields omitted are untouched. Writes live data. Use when: editing an unsubscribe record. Rare. Required: Enums: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteUnsubscribeA | Remove email from unsubscribe list - Permanently delete an unsubscribe record by ID. Destructive - cannot be undone via API. Use when: re-subscribing an email address to newsletters and automated email campaigns. Confirm the recipient's consent first. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listWidgetsA | List widgets - Paginated enumeration of widget records. Read-only. Lean-by-default keep-list: rows return only Use when: discovering the reusable HTML/CSS/JS components available for embedding in pages (as Pagination: cursor-based ( Filter/sort: See also: Returns: Widget object fields (from BD support article 12000108056):
Site records and platform master defaults are merged in the response — see Rule: Default-merge models to filter to one and to sort. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getWidgetA | Get a single widget - Fetch a single widget record by Lean-by-default keep-list: returns only Use when: you have a Required: See also: Returns: For the full field list, see | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createWidgetA | Create a widget - Create a new widget (reusable HTML/CSS/JS component). Writes live data. Cache refresh is automatic. Response includes Use when: programmatically adding a new reusable block to embed as Required: widget_name format: alphanumeric + spaces + hyphens + plus + underscores only ( Pre-check before create: BD does NOT enforce uniqueness on On collision (auto-suffix flow): if the proposed name is taken, append Route by type BEFORE writing values: decide what each piece of code is, then put it in the matching field — HTML → Common fields on create:
See also: Writes live data: the widget is available immediately but does nothing until referenced by a Returns: Post-create verification (recommended, especially when uncertain about routing): call For the full field list, see | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateWidgetA | Update a widget - Update an existing widget by Cache refresh is automatic. Response includes Use when: editing widget HTML ( Required: Common edits:
Renaming via See also: Returns: For the full field list, see | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteWidgetA | Delete a widget - Permanently delete a widget by Use when: removing an unused widget. Destructive caveat: any page or email using Required: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| renderWidgetA | Render a widget to HTML - Diagnostic tool only. Returns BD's rendered HTML output for a widget — useful for confirming render-pipeline symptoms during troubleshoot (backslash strip on Use when: the user reports a widget is broken and you need to see what BD's render pipeline actually emits. See Rule: Widget code fields scenario 3 (TROUBLESHOOT). Required: either Returns (distinct from standard envelope): See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listEmailTemplatesA | List email templates - Paginated enumeration of emailtemplate records. Read-only. Use when: enumerating the site's transactional/marketing email templates before editing. Common audit: before bulk updating "from" addresses or footers. Lean-by-default: Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getEmailTemplateA | Get a single email template - Fetch a single emailtemplate record. Read-only. Use when: fetching one template's HTML body and subject for edit. Required: Lean-by-default: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createEmailTemplateA | Create an email template - Create a new emailtemplate record. Writes live data. Use when: adding a new transactional/marketing template. Rare - most BD email templates are built into the admin UI. Required: Pre-check before create: BD does NOT enforce uniqueness on Enums: Parameter interactions:
See also: On create: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateEmailTemplateA | Update an email template - Update an existing emailtemplate record by ID. Fields omitted are untouched. Writes live data. Use when: editing any field on an existing template — subject, body, wrapper mode ( Required: Enums (same as See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteEmailTemplateA | Delete an email template - Permanently delete a emailtemplate record by ID. Destructive - cannot be undone via API. Use when: removing a deprecated template. BD may fall back to defaults if a required system template is deleted - confirm before purging. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listFormsA | List forms - Paginated enumeration of form records. Read-only. Use when: enumerating the site's forms (signup, contact, quote request, custom forms). Child fields are fetched separately via Pagination: cursor-based ( Filter/sort: See also: Returns: Site records and platform master defaults are merged in the response — see Rule: Default-merge models to filter to one and to sort. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getFormA | Get a single form - Fetch a single form record. Read-only. Use when: fetching one form's metadata. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createFormA | Create a form - Create a new form record. Writes live data. Add fields afterward via Required: Class selection — see Rule: Forms § Form classes before picking Mandatory Wrapper-enforced refusal: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateFormA | Update a form - Update an existing form record by ID. Fields omitted are untouched. Writes live data. Required: Cross-refs same as Wrapper-enforced refusal: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteFormA | Delete a form - Permanently delete a form record by ID. Destructive - cannot be undone via API. Use when: removing a form - child fields orphan. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listFormFieldsA | List form fields - Paginated enumeration of formfield records. Read-only. Use when: listing fields on a form. Filter by Pagination: cursor-based ( Filter/sort: See also: Returns: Site records and platform master defaults are merged in the response — see Rule: Default-merge models to filter to one and to sort. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getFormFieldA | Get a single form field - Fetch a single formfield record. Read-only. Use when: one field by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createFormFieldA | Create a form field - Create a new formfield record. Writes live data. Required: Canonical See Rule: Forms § Field anatomy for field shape, view-flag defaults, validators, and the canonical Wrapper-enforced refusals: (1) Agent pre-checks (NOT wrapper-enforced): See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateFormFieldA | Update a form field - Update an existing formfield record by ID. Fields omitted are untouched. Writes live data. Required: When renaming See Rule: Forms § Field anatomy for field shape, view-flag defaults, validators, and the canonical Wrapper-enforced refusals: (1) Agent pre-checks (NOT wrapper-enforced): See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteFormFieldA | Delete a form field - Permanently delete a formfield record by ID. Destructive - cannot be undone via API. Use when: removing a field. Existing submission records may reference the old field name - data persists but becomes orphan metadata. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listMembershipPlansA | List membership plans - Paginated enumeration of membership-plan records. Read-only. Use when: discovering Lean-by-default keep-list: rows return only the core fields:
Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMembershipPlanA | Get a single membership plan - Fetch a single membership-plan record. Read-only. Use when: fetching one plan's config. Same lean-by-default as Required: Lean-by-default keep-list: the core fields —
EAV-routed fields not merged: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listMenusA | List menus - Paginated enumeration of menu records. Read-only. Lean-by-default keep-list: rows return only Use when: enumerating navigation menus on the site (main menu, footer menu, sidebar, etc.). For items within a menu use Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMenuA | Get a single menu - Fetch a single menu record. Read-only. Lean-by-default keep-list: same shape as Use when: fetching one menu's metadata. Child items are fetched separately. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createMenuA | Create a menu - Create a new menu record. Writes live data. Use when: adding a new navigation container. After creating the container, add entries via Required: Pre-check before create: BD does NOT enforce uniqueness on Parameter interactions:
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateMenuA | Update a menu - Update an existing menu record by ID. Fields omitted are untouched. Writes live data. Use when: renaming a menu, toggling Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteMenuA | Delete a menu - Permanently delete a menu record by ID. Destructive - cannot be undone via API. Use when: removing a menu container. Child items ( Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listMenuItemsA | List menu items - Paginated enumeration of menuitem records. Read-only. Lean-by-default keep-list: rows return only Default empty-link filter: rows where Use when: enumerating items in a menu - always filter by Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMenuItemA | Get a single menu item - Fetch a single menuitem record. Read-only. Lean-by-default keep-list: same shape as Use when: editing one specific menu entry. Single-record fetch does NOT apply the empty-link filter — caller asked for this specific row by ID and gets it back. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createMenuItemA | Create a menu item - Create a new menuitem record. Writes live data. Use when: adding a nav link to an existing menu. Parent Required: Enums: Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateMenuItemA | Update a menu item - Update an existing menuitem record by ID. Fields omitted are untouched. Writes live data. Use when: renaming, re-linking (change Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteMenuItemA | Delete a menu item - Permanently delete a menuitem record by ID. Destructive - cannot be undone via API. Use when: removing a single menu entry. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listSubCategoriesA | List services (sub-categories) - Paginated enumeration of SUB-level member categories (services). Read-only. Lean by default: each row keeps Sub Categories are level 2 of the 3-tier member classification (e.g., "Sushi" under "Restaurants"). Each has a Use when: enumerating sub-categories (services) - always filter by Permission note - platform gap: this endpoint ( Pagination: cursor-based ( Filter/sort: See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getSubCategoryA | Get a single service - Fetch a single SUB-level member category (service) by Lean by default: keeps Use when: fetching one sub-category by Required: See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createSubCategoryA | Create a service - Create a new SUB-level member category under an existing Top Category. Writes live data. Use A Sub Category is level 2 of the 3-tier member classification. It MUST have a parent Top Category (via Use when: adding one sub-category that needs Required: Pre-check before create: BD does NOT enforce uniqueness on Parameter guidance:
See also: Writes live data: changes are immediately visible on the public site. Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateSubCategoryA | Update a service - Update an existing SUB-level member category by Use when: renaming, re-parenting (change Required: Filename rename caveat: if the existing Parameter notes:
See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteSubCategoryA | Delete a service - Permanently delete a SUB-level member category by Use when: removing an unused sub-category. Any member with this Required: Destructive: confirm intent. Members whose Bound-page caveat: if this category's See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listMemberSubCategoryLinksA | List user-service relationships - Paginated enumeration of MEMBER ↔ SUB CATEGORY links. Read-only. Each record links a member ( Use when: auditing per-service-link metadata (prices, specialty flags, completion counts) across members. Filter by When to use this vs. the simpler Pagination + filter/sort: standard. See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getMemberSubCategoryLinkA | Get a single user-service relationship - Fetch a single Member ↔ Sub Category link by Use when: you have a Required: See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createMemberSubCategoryLinkA | Link a service to a user - Create a new Member ↔ Sub Category link with optional metadata. Writes live data. Links an existing member ( Use when: the simpler Required: Pre-check before create (PAIR uniqueness): BD does NOT enforce uniqueness on the Parameter guidance:
See also: Writes live data: appears on the member's public profile immediately. Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateMemberSubCategoryLinkA | Update a user-service relationship - Update a Member ↔ Sub Category link by Use when: adjusting per-link metadata - member's price for this service, specialty flag, completion counter. Required: Updatable fields: See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteMemberSubCategoryLinkA | Remove a service from a user - Permanently delete a Member ↔ Sub Category link by Removes the member's link to this Sub Category in the Use when: removing a specific link row. Does NOT update the Required: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listUserPhotosA | List user photos - Paginated enumeration of userphoto records. Read-only. Use when: enumerating photos attached to members (profile, logo, cover). Filter by Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUserPhotoA | Get a single user photo - Fetch a single userphoto record. Read-only. Use when: fetching one photo record by Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createUserPhotoA | Create a user photo - Create a new userphoto record. Writes live data. Use when: attaching a new photo record to a member. The image file must already exist in site storage (upload via admin or Required: Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateUserPhotoA | Update a user photo - Update an existing userphoto record by ID. Fields omitted are untouched. Writes live data. Use when: changing a photo's Required: Enums: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteUserPhotoA | Delete a user photo - Permanently delete a userphoto record by ID. Destructive - cannot be undone via API. Use when: removing a photo attachment. For member image management consider Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listUserMetaA | List user metadata records - Paginated enumeration of users_meta records (EAV key/value table). Read-only. Use when: enumerating metadata rows (key/value pairs) attached to a parent record in any BD table. IDENTITY RULE - Commonly-seen Pagination: cursor-based ( Filter: prefer the first-class See also: Returns: Note on duplicates: BD does NOT enforce a uniqueness constraint on | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getUserMetaA | Get a single metadata record - Fetch a single usermeta record. Read-only. Use when: fetching one metadata row by Required: Identity check before downstream writes: Before using this row's See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateUserMetaA | Update a metadata record - Update an existing users_meta record's IDENTITY RULE - Use when:
Workflow: find the Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteUserMetaA | Delete a metadata record - Permanently delete a users_meta record by HARD RULE - Use when: removing a specific metadata row, OR cleaning up orphan meta rows after a parent record is deleted (BD does not cascade-delete users_meta when a parent is removed - it's the agent's job to find and delete the orphan rows surgically). Required: Post-parent-delete cleanup workflow (safe pattern):
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listTagsA | List tags - Paginated enumeration of tag records. Read-only. Use when: enumerating member tags, fetching tag names for display, or building a tag-management UI. Tags are lightweight labels attached to members, different from categories (which are taxonomy). Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getTagA | Get a single tag - Fetch a single tag record. Read-only. Use when: fetching one tag by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createTagA | Create a tag - Create a new tag record. Writes live data. Use when: adding a new tag. Group ( Required:
Duplicate Parameter interactions:
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateTagA | Update a tag - Update an existing tag record by ID. Fields omitted are untouched. Writes live data. Use when: renaming a tag without losing the tag-to-member relationships. Required:
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteTagA | Delete a tag - Permanently delete a tag record by ID. Destructive - cannot be undone via API. Use when: removing a tag entirely. Tag-relationships ( Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listTagGroupsA | List tag groups - Paginated enumeration of taggroup records. Read-only. Use when: discovering the tag groupings before creating tags - each tag belongs to a group. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getTagGroupA | Get a single tag group - Fetch a single taggroup record. Read-only. Use when: fetching one tag group by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createTagGroupA | Create a tag group - Create a new taggroup record. Writes live data. Use when: organizing tags into new themes (e.g., "Skill Level", "Service Area"). Rare. Required: Pre-check before create: BD does NOT enforce uniqueness on See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateTagGroupA | Update a tag group - Update an existing taggroup record by ID. Fields omitted are untouched. Writes live data. Use when: renaming a tag group. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteTagGroupA | Delete a tag group - Permanently delete a taggroup record by ID. Destructive - cannot be undone via API. Use when: removing a group - child tags orphan; delete or re-group them first. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listTagTypesA | List tag types - Paginated enumeration of tagtype records. Read-only. Use when: enumerating the tag-type classifiers on this site. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getTagTypeA | Get a single tag type - Fetch a single tagtype record. Read-only. Use when: one tag type by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listTagRelationshipsA | List tag relationships - Paginated enumeration of tagrelationship records. Read-only. Use when: auditing which tags are attached to which records. Filter by tag or by target record. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getTagRelationshipA | Get a single tag relationship - Fetch a single tagrelationship record. Read-only. Use when: one relationship row by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createTagRelationshipA | Create a tag relationship - Create a new tagrelationship record. Writes live data. Use when: attaching an existing tag to a record (member, post, etc.). The alternative for members is setting the Required: Pre-check before create (TRIPLE uniqueness): BD does NOT enforce uniqueness on the Parameter interactions:
See also:
The
Process: call | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateTagRelationshipA | Update a tag relationship - Update an existing tagrelationship record by ID. Fields omitted are untouched. Writes live data. Use when: adjusting a tag-relationship record's metadata. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteTagRelationshipA | Delete a tag relationship - Permanently delete a tagrelationship record by ID. Destructive - cannot be undone via API. Use when: detaching a tag from a record. Note: if the member has Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listSmartListsA | List smart lists - Paginated enumeration of smartlist records. Read-only. Use when: enumerating saved dynamic filter configurations the admin has created - these back the BD admin's saved-filter UI for members, leads, reviews, etc. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getSmartListA | Get a single smart list - Fetch a single smartlist record. Read-only. Use when: fetching one saved filter's config. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createSmartListA | Create a smart list - Create a new smartlist record. Writes live data. Use when: programmatically saving a filter configuration for later reuse. Required: Pre-check before create: BD does NOT enforce uniqueness on Parameter interactions:
See also:
The API accepts the value as a plain string; BD handles the internal encryption. Don't pre-encrypt client-side - you'll get double-encrypted garbage. Use the JSON-key-value format for filterable types. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateSmartListA | Update a smart list - Update an existing smartlist record by ID. Fields omitted are untouched. Writes live data. Use when: editing the filter criteria or schedule on a saved list. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteSmartListA | Delete a smart list - Permanently delete a smartlist record by ID. Destructive - cannot be undone via API. Use when: removing a saved filter configuration. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listSidebarsA | List custom sidebars - Paginated enumeration of CUSTOM sidebars defined on this site. Read-only in this MCP (create/update/delete deliberately omitted - sidebars are layout infrastructure; changes belong in the BD admin UI). Use when: an agent needs to set Important - this endpoint returns ONLY custom sidebars. It does NOT return the Master Default Sidebars that are seeded in BD's master database and always valid on every site. Those are hardcoded in BD core and are NOT rows in the Returns: rows with Pagination + filter/sort: standard. Site records and platform master defaults are merged in the response — see Rule: Default-merge models to filter to one and to sort. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getSidebarA | Get a single custom sidebar - Fetch a single custom sidebar by Required: Only returns custom sidebars. Master defaults are not rows in this table — see Rule: Sidebars for the canonical Master Default list; use those names directly in Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getSiteInfoA | Get site-level identity, locale, currency, and brand-image URLs - Returns the site's own identity and locale context — what kind of directory this is, who it serves, the formatting conventions to respect, and the URLs of branding assets. Read-only, no params. Call this once on the first BD task of a conversation and cache for the session; the values rarely change mid-conversation. Response shape (wrapper adds Field semantics to know:
Why agents should call this early: the grounding it provides (site purpose, member archetype, locale) shapes every subsequent decision — what 'add a member' means, what categories are relevant, how to format dates and money, what the profile-placeholder image looks like, which brand assets to use in designs. Auth: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getStockVideoA | Free stock video (mp4) for a background video. - Free stock video for a background, e.g. behind the homepage hero. Wrapper-native synthetic tool; does NOT proxy to BD. Give it Pexels video pages and it returns, for each, a ready-to-use mp4 Find the pages with a web search for Use when: the owner wants a background video and has not given a YouTube or Vimeo link. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getImageDimensionsA | Probe an image URL and return its dimensions + orientation. - Wrapper-native synthetic tool. Range-GETs the first 64KB of an image URL and parses JPG/PNG header bytes to return width, height, format, aspect_ratio, and orientation (landscape | portrait | square). Does NOT proxy to BD. Used by content-creation skills to verify image orientation before committing to a feature-image field ( Batch mode — preferred for 2+ candidates: pass Caller contract: filter candidate URLs to See also: Rule: Image dimensions, Rule: Image dedup. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getBrandKitA | Get the site's brand kit (colors + fonts) for design decisions - Return a compact, semantically-labeled brand kit for this BD site - colors (body / primary / dark / muted / success / warm / alert accents, card surface) + fonts (body + heading Google Fonts). Call this ONCE at the start of any design-related task (building a widget, WebPage, post template, email, hero banner - anything where colors or fonts are chosen) so the output visually matches the site's brand. Handler is synthetic - makes 20 parallel internal calls to No args. Read-only. Safe to call anytime. Response shape: Usage guidance embedded in response - agents should read it every call. Key rules:
When a slot is empty on the site, the handler applies BD's documented fallback defaults (same defaults BD's admin AI Companion uses). Response is never missing keys - every field always has a value. Auth: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getDesignSettingsA | Read design settings by block: labels, allowed and current values. Several blocks in one call: block "hero.primary,hero.cta,home.rows" (up to 30), returned as blocks[]. No arguments: the block list and the homepage sections in order, each Custom Content row with its widget. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateDesignSettingsB | Change design settings by name in one all-or-nothing call, checked like the Design Settings page; returns the changes and an undo. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listCitiesA | List cities (location-based search & SEO slugs) - Paginated enumeration of cities enabled on this site for location-based member/post browsing and SEO page URL generation. Read-only source-of-truth for city slugs used in search-result URLs. Backed by BD's Use when: resolving a human city name (e.g. "Beverly Hills") to its Pagination: cursor-based ( Filter/sort: Returns:
System-critical table - create & delete deliberately omitted from this MCP. Cities are managed by BD automatically (a new city row is added when a member signs up from a new location). Creating cities via API risks slug collisions with auto-created rows, and deleting risks orphaning members whose Auth: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getCityA | Get a single city - Fetch one city row. Read-only. Note BD schema typo: PK is Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateCityA | Update a city (corrections only) - Update an existing city row. Read-mostly - use sparingly. Fields omitted are untouched (PATCH semantics - only send what you want to change). Use when: correcting a typo in Required: Warning on Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listStatesA | List states / provinces / regions - Paginated enumeration of states/provinces/regions enabled on this site. The Use when: resolving a state/province name ("California", "Ontario") to its Pagination + filter/sort: standard. Useful filters: Returns: rows with System-critical table - create & delete deliberately omitted. States are seeded by BD as needed. Use | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getStateA | Get a single state/province - Fetch one state row by Required: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateStateA | Update a state (corrections only) - Update a state row. Read-mostly - use for corrections. Fields omitted are untouched (PATCH semantics - only send what you want to change). Required: Warning on | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listCountriesA | List countries - Paginated enumeration of countries in the global reference table. Read-only reference. Use when: resolving a country name to its 2-letter Country URL slug derivation: BD does NOT store a Pagination + filter/sort: standard. Useful filters: Returns: rows with System-critical table - create & delete deliberately omitted. Countries are a global reference list. Use | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getCountryA | Get a single country - Fetch one country row. Read-only. Required: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateCountryA | Update a country (corrections / active toggle) - Update a country record. Read-mostly - primary use is toggling Required: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listWebPagesA | List pages (list_seo) - Paginated enumeration of web pages ( Returns every static/SEO page on the site - homepage, about, contact, custom landing pages, templates, etc. Filter by Use when: listing all site pages. Filter by Pagination: cursor-based ( Filter/sort: Lean-by-default keep-list: rows return only the core identity + linkage fields:
On sites with heavy pages, a single row can be 10-30KB with code assets; opt in only when you actually need the data (e.g. before See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getWebPageA | Get a single page - Fetch a single web page by Use when: fetching one page's metadata (+ optionally its body/CSS/JS) before editing. Common for "let me read the current About page before editing it" workflows. Required: Lean-by-default keep-list: same shape as
Before See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createWebPageA | Create a page - Create a Cache refresh is automatic. Response includes Required fields: Filename uniqueness — enforced by the wrapper, no exceptions. BD does NOT enforce unique Thin-content warning: if no Asset field routing (mandatory - Froala strips mismatched content silently):
All asset fields accept raw content verbatim. No CDATA, no SVG/canvas prohibited in
Hero section - when
Used to override BD's auto-generated dynamic search URLs (e.g. CRITICAL - Workflow for "add SEO to [category] in [location]":
SEO content for categories: route to
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateWebPageA | Update a page - Update an existing Cache refresh is automatic. Every successful Required fields: Disambiguation: apply Rule: Resource disambiguation when the user names a page by Common edits:
Misnamed fields (BD repurposed these columns - name is misleading):
Template tokens supported in Changing Asset field routing (Froala strips mismatched content silently):
All asset fields accept raw content verbatim. No CDATA, no EAV-stored fields — auto-routed by the wrapper, no special handling. BD's Hero section — which hero does the user mean? Read the page's current **Hero section edits - when
Do NOT re-apply hero defaults on updates that don't touch H1/H2 double-render trap: when hero is enabled (
SEO content for categories: route to
On See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteWebPageA | Delete a page - Permanently delete a web page by Use when: permanently removing a page. Required: Destructive: confirm with the user. If inbound links or menus reference the deleted page's URL, consider creating a
ORPHAN CLEANUP REQUIRED - BD does NOT cascade-delete users_meta rows. Each WebPage with a hero or custom layout has up to 18 EAV rows in
Never loop-delete by See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listRedirectsA | List redirects (301) - Paginated list of all 301 redirect rules on the site. Use when: auditing existing 301 rules - useful before bulk URL changes to avoid duplicate rules, or when debugging why a URL unexpectedly redirects. Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getRedirectA | Get a single redirect - Fetch a single redirect record. Read-only. Use when: investigating one specific redirect rule by Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createRedirectA | Create a redirect - Create a new 301 redirect rule. Use when: preserving SEO after any URL change - slug rename on a member profile, post, page, or category. BD auto-creates some redirects on its own (admin-triggered renames), but you must create them manually for API-triggered changes. Avoid duplicate Required:
Pre-check before create - TWO checks (redirects are uniquely dangerous: wrong rules cause infinite loops and SEO damage): Check 1 - exact-pair skip (idempotent): Do a server-side filter-find: Check 2 - reverse-rule loop prevention (CRITICAL): Do a second filter-find: Do NOT paginate unfiltered redirect lists - filtered lookups are two tiny responses. On any site with a large redirect history, dumping the full table wastes rate limit and context. Parameter interactions:
See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateRedirectA | Update a redirect - Update an existing redirect record by ID. Fields omitted are untouched. Writes live data. Use when: adjusting an existing rule's destination or source path. Rare - most redirects are create-once. Required:
See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteRedirectA | Delete a redirect - Permanently delete a redirect record by ID. Destructive - cannot be undone via API. Use when: an old redirect is no longer needed (source content has been offline long enough that the 301 value is gone) or the rule is conflicting with a new page at the same path. Required: See also: Destructive: confirm intent with the user before bulk use. No soft-delete via API - records removed are not recoverable. Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| refreshSiteCacheA | Refresh the site cache (template/theme/widget/menu/page invalidation) - Clears BD's internal template/theme/widget caches. Useful when recent admin edits to design settings or widgets aren't showing on the public site yet. Use when: the user has just updated a template, theme setting, widget, menu, or page layout and the public site is still serving the old version. Also a safe troubleshooting step if they report a recent admin-edit not appearing after ~1 minute. Optional parameters:
Not needed after Do NOT use for:
Returns: With Undocumented by BD publicly; exposed via admin API-permissions UI. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listDataTypesA | List data types - List all data types configured on this BD site. Use the data_id values as data_type parameters when creating posts or portfolio groups. Use when: discovering the valid Pagination: cursor-based ( Filter/sort: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getDataTypeA | Get a single data type - Fetch a single datatype record. Read-only. Use when: fetching one data type's record by ID. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createDataTypeA | Create a data type - Define a new content-type template. Only do this when the user explicitly wants a new post type - most sites come pre-configured with the types they need. Use when: adding a new data-type classifier. Rare - usually preconfigured. Required: Pre-check before create: BD does NOT enforce uniqueness on Enums: See also: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateDataTypeA | Update a data type - Update an existing datatype record by ID. Fields omitted are untouched. Writes live data. Use when: renaming a data type. Required: Enums: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteDataTypeA | Delete a data type - Deletes a data type definition. Records (posts, portfolio groups) referencing a deleted data type may become orphaned - confirm with the user before deleting. Use when: removing an unused data type. Posts/groups referencing it orphan - clean up first. Required: See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listTopCategoriesA | List categories (professions) - Paginated enumeration of TOP-level member categories. Read-only. Lean by default: each row keeps Top Categories are the highest level of the 3-tier member classification (e.g., "Restaurants", "Dentists"). Each record's Use when: populating a category dropdown, generating a site map, or discovering the Permission note - platform gap: this endpoint ( Pagination: cursor-based ( Filter/sort: See also: Returns: 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:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| getTopCategoryA | Get a single category - Fetch a single TOP-level member category by Lean by default: keeps A Top Category is the highest level of the 3-tier member classification. Backed by BD's Use when: you already have a Required: See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createTopCategoryA | Create a category - Create a new TOP-level member category. Writes live data. Use A Top Category is the highest level of the 3-tier member classification (e.g., "Restaurants"). It populates the Use when: adding one top category that needs Required: Pre-check before create: BD does NOT enforce uniqueness on Parameter guidance:
See also: Writes live data: changes are immediately visible on the public site. Returns: Common workflow - full 3-tier setup ("create Restaurants -> Sushi -> assign Alice"):
How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateTopCategoryA | Update a category - Update an existing TOP-level member category by Use when: renaming a category, changing its URL slug ( Required: Filename rename caveat: if the existing See also: Writes live data: changes are immediately visible on the public site. Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteTopCategoryA | Delete a category - Permanently delete a TOP-level member category by Use when: removing an unused top-level category. Any members with matching Required: Destructive: confirm intent with the user. Members who referenced this Bound-page caveat: if this category's See also: Returns: How a member gets classified on their public profile:
Sub-sub-categories: There is NO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createCategoryTreeA | Create a full category taxonomy (tops + subs + sub-subs) in one call. - Wrapper-native synthetic tool. Creates member categories — top categories, their sub-categories, and third-tier sub-sub-categories — in one call. Use when: creating a category at any level, including adding to a structure that already exists. Use Required: Send the whole taxonomy in one call. A top category named again is matched by name and reused, so a later call adds to it. Never issue two calls concurrently: a top category named in both is created twice, because BD's category list does not reflect a row written by a call still in flight. A second call is safe once the first call's response has returned. The three shapes, all the same input:
Third tier — Sub-category names must not contain commas — this tool writes them through BD's comma-separated Nothing is written until every name validates. Writing itself is not atomic: a failure part-way leaves earlier groups created. Building sub-categories requires a temporary member, which this tool creates and deletes for you. See also: Returns: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updatePageCssA | Add, replace or remove individual CSS rules in a web page's CSS field by selector - every other character of the field is left as it is. An icon is a Bootstrap Icons 1.13.1 icon unless the user names another icon set: write Returns: |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 175 tools
Most tools are distinguishable by resource+action, but the huge surface contains several near-neighbors: createTopCategory/createSubCategory/createCategoryTree, getPostTypeCustomFields/getSingleImagePostFields/getMultiImagePostFields/getUserFields, and updateWebPage/updatePageCss. Detailed descriptions and cross-references help, but agents must still read carefully to avoid misselection.
Almost every tool follows a predictable camelCase verb_noun pattern (listX, getX, createX, updateX, deleteX), including synthetic helpers like getBrandKit and verifyToken. Singular/plural variations and a few one-off names do not break the overall convention.
175 tools is far beyond the 3-15 sweet spot and even beyond the 25+ threshold, exposing CRUD for every BD resource plus numerous synthetic utilities. This is an extreme count mismatch that burdens discovery, context, and selection.
Coverage is broad: users, posts, post types, categories, widgets, pages, menus, forms, tags, redirects, leads, reviews, clicks, meta, locations, and email templates all have lifecycle tools. Gaps remain for write operations on membership plans, sidebars, tag types, locations, and form inquiries, but most core workflows are covered.