Brilliant Directories

Brilliant Directories (BD) is the SaaS platform behind 50,000+ membership and directory websites. This skill gives you programmatic control over a BD-powered site via its REST API.

What having this skill active means for your user

You can do, without them opening the BD admin UI:

Member ops — create, bulk import, update, search, delete members; auto-fetch profile photos/logos/cover images from external URLs (web-scrapes, CSVs, cross-site migrations); manage categories, credits, and tags
Content ops — write blog articles, events, job listings, coupons, video posts, photo albums, property/product listings; edit the homepage, landing pages, about/contact, SEO meta tags, social Open Graph tags
Taxonomy ops — build out the site's 3-tier category hierarchy (Top Category → Sub Category → Sub-Sub Category) from scratch or inline while creating members
Inbox & engagement — read lead inbox, moderate reviews, trigger lead matching to send notification emails to eligible members
Site config — edit navigation menus, form fields, email templates, widgets, smart lists, 301 redirects, membership plans
Billing introspection — pull a member's invoice history and subscription status (read-only)

Typical outcome unlocks: "scrape 50 local businesses → create members with logos locally stored → write a blog post showcasing them → add redirects preserving SEO" — one agent run, zero admin clicks.

Ground truth

The authoritative source for every available operation is the OpenAPI spec: https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/mcp/openapi/bd-api.json

If this skill and the spec disagree, the spec wins. Scan the relevant tool description end-to-end before claiming a limit — BD exposes BD-specific capabilities (auto-image-import, auto-category-create, parent=>child sub-sub syntax, filename-is-full-path) that don't match typical REST API assumptions.

When to activate

Activate this skill when the user:

Mentions "my BD site," "my directory," "my directoryup site," "brilliant directories," or "my members"
Asks to manage, import, update, export, search, or bulk-modify members/leads/posts/pages
Wants to update the homepage, create a landing page, edit site content, or change SEO
Wants to send emails, manage templates, configure forms, categories, tags, menus, or membership plans
Mentions automating tasks across their directory/membership platform
Asks something that sounds like an admin-panel task on a BD-powered site

Two ways to reach the API (agent-agnostic)

This skill works with any AI agent. Two integration paths — use whichever the agent supports:

Path A — MCP (preferred for Claude Desktop / Cursor / Windsurf / Cline / Claude Code)

The user installs the MCP server once; it exposes every BD operation as a tool. To check if it's active, look at your available tools for names like verifyApiKey, listUsers, createUser, listWebPages, etc.

Two install options — both give the full tool surface + same agent directives:

Remote (no Node.js install): add an MCP server to the AI client's config pointing at https://brilliantmcp.com with two headers — X-Api-Key (user's BD API key) and X-BD-Site-URL (user's BD site URL). This hits our hosted Cloudflare Worker; the user does nothing on their machine beyond editing the config file.
Local (runs as a child process on the user's machine, needs Node.js): run the setup wizard:
```
npx --prefer-online brilliant-directories-mcp@latest --setup
```
The wizard asks for their BD site URL and API key, then configures their AI client automatically. After a client restart, the tools become available.

Both paths are documented in detail in the README's "Setup by Platform" section. Remote is the faster recommendation for non-technical users; Local is useful when the user wants the MCP on their own infrastructure.

Getting an API key: BD Admin > Developer Hub > Generate API Key (full walkthrough: https://support.brilliantdirectories.com/support/solutions/articles/12000088768).

Path B — Direct HTTPS using the OpenAPI spec (for ChatGPT Actions, n8n, Make, Zapier, LangChain, custom agents)

If MCP isn't available but the agent can make authenticated HTTP requests:

Base URL: the user's BD site, full canonical URL with www. if applicable (e.g., https://www.mysite.com) — never hardcode, always ask
Auth: HTTP header X-Api-Key: {user's API key}
All endpoints and schemas: the OpenAPI spec URL above. Read it to discover operations, required fields, response shapes.

Both paths hit the same underlying REST API and behave identically.

Tool / operation discovery (future-proof rule)

Never assume a tool exists based on this document. BD's API grows over time and this skill can't be updated for every new resource. The correct pattern:

If using MCP: list your available tools. Use whatever the client exposes.
If using HTTP directly: GET the OpenAPI spec (URL above). Enumerate paths to see every endpoint. Each operation's operationId is the stable name.
To discover writable fields on any resource: many resources expose a /fields endpoint (e.g., GET /api/v2/user/fields, GET /api/v2/data_posts/fields) that returns field metadata including required, type, choices, and helpText.

If a user asks for something and no matching operation appears in the spec, say so honestly: "The BD API doesn't currently expose that operation — you'll need to do it in the BD admin panel."

Core conventions (stable across all resources)

Authentication

Every API call uses X-Api-Key as an HTTP header. Via MCP, the server handles this automatically. Never ask the user to paste their API key into chat.

Base URL pattern

All endpoints live under {site_url}/api/v2/{resource}/{action} — e.g., https://www.mysite.com/api/v2/user/get.

Pagination (cursor-based)

Request: limit (default 25, max 100) + page (opaque cursor token from prior response's next_page)
Response includes: total, current_page, total_pages, next_page, prev_page
Never assume sequential integer page numbers. The page parameter is an opaque token.

Filtering

All list endpoints support property-based filtering:

?property=city&property_value=Los Angeles&property_operator==

Operators: =, LIKE, >, <, >=, <=. Multiple filters via property[]=...&property_value[]=....

Sorting

?order_column=last_name&order_type=ASC

Response shape

Success: { "status": "success", "message": [...records...] or {record}, ...pagination fields... }. Error: { "status": "error", "message": "human-readable reason" } with standard HTTP status codes.

Rate limits

Default 100 requests per 60 seconds per API key. Customers can request a raise to anywhere between 100 and 1,000/min by contacting Brilliant Directories support — this is NOT a self-service admin setting.

For bulk operations:

Warn the user about the limit before starting
Add pacing between writes (~600–700ms per call at the default limit)
Watch for HTTP 429 responses; if hit, back off at least 60 seconds before retrying
For known-large jobs (>500 records), suggest the user contact BD support to raise the limit first

Template tokens in text fields

Many text fields (titles, meta tags, email subjects, page content) support BD template tokens:

%%%website_name%%% — the site's configured name
%%Profession%% — the user's profession/category
Widget embeds: [widget=Widget Name] Preserve these exactly as the user provides — do not "clean them up" or escape them.

Canonical multi-step pattern

For any non-trivial task, follow this sequence:

Verify — call verifyApiKey (or GET /api/v2/token/verify) to confirm credentials and site are reachable
Discover — if unsure about field names/types, call the resource's /fields endpo

brilliant-directories