API Documentation
REST API and MCP server reference. Base URL: https://bezal.ai
Authentication
All authenticated endpoints accept your API key via either header:
Authorization: Bearer bzl_your_key_here # or X-API-Key: bzl_your_key_here
Read endpoints (search, lookup, categories, health, openapi) work anonymously but are rate limited per IP. Write endpoints (POST /api/v1/requests) require a real key.
Rate limits
| Tier | Daily limit | Notes |
|---|---|---|
| Anonymous | 100 / day per IP | No key. Best-effort. |
| Free | 100 / day | Tied to your key. |
| Developer | 10,000 / day | By request. Email us. |
| Enterprise | Custom | By request. Email us. |
429 responses include the current count and limit. Limits reset daily.
Endpoints
/api/v1/businesses/searchAuth optionalSearch the directory. Results are ranked by Bezal rank, then rating. With no q, category or city, total is an estimate. When a town or Connecticut county has none of what q or category asks for, page 1 keeps results empty and total 0 and adds nearby, matches within 30 miles in the same state, nearest first, each with distance_miles, and nearby_note, which says whether they are provably the closest.
| q | query · string | Free-text search across name + category. |
| category | query · string | Category keyword (ILIKE match). |
| city | query · string | City name (case-insensitive). A Connecticut county here, like Litchfield County CT, searches its towns. |
| county | query · string | A Connecticut county, like Litchfield or New Haven County. Searches its towns and adds county to the response. Read only when city names no town. A county Bezal can't search returns 400. |
| state | query · string | US state code like CT, or the full state name. DC also takes D.C. and Washington DC. Anything else returns 400. |
| min_rating | query · number | Minimum avg_rating filter (0-5). |
| page | query · number | Pagination page (default 1). |
| limit | query · number | Page size (1-20, default 10). |
curl "https://bezal.ai/api/v1/businesses/search?q=hr+consulting&state=CT&limit=5" \ -H "Authorization: Bearer bzl_your_key"
{
"results": [
{
"id": "uuid",
"name": "Example HR Partners",
"category": "HR Consulting",
"city": "Hartford",
"state": "CT",
"avg_rating": 4.8,
"review_count": 42,
"tier": "free",
"quote_request_url": "https://bezal.ai/example-hr-partners",
"upgrade_note": "Phone, website, address and hours are included once a provider claims its profile and is on a paid Bezal plan."
}
],
"total": 12,
"page": 1,
"pageSize": 5
}/api/v1/businesses/{id}Auth optionalFetch a single business by UUID. phone, website, address, zip, hours, photos, lat and lng are included only for listings on a paid Bezal plan, and description for a higher paid plan. Other listings return upgrade_note instead.
| id* | path · uuid | Business UUID. |
curl "https://bezal.ai/api/v1/businesses/abc123…" \ -H "Authorization: Bearer bzl_your_key"
{
"business": {
"id": "abc123…",
"name": "...",
"category": "...",
"city": "...",
"state": "CT",
"avg_rating": 4.8,
"review_count": 42,
"tier": "pro",
"quote_request_url": "https://bezal.ai/...",
"phone": "...",
"website": "...",
"address": "...",
"zip": "...",
"hours": "...",
"photos": [...],
"lat": 41.76,
"lng": -72.67
}
}/api/v1/categoriesAuth optionalList all business categories with name + slug.
curl "https://bezal.ai/api/v1/categories"
{
"categories": [
{ "name": "HR Consulting", "slug": "hr-consulting" },
{ "name": "Plumbing", "slug": "plumbing" },
...
]
}/api/v1/requestsAuth requiredSubmit a service request to a business. Requires a real API key. delivered is true only when the business has an owner on Bezal who was notified.
| business_id | body · uuid | Optional. Target business. |
| seeker_name* | body · string | Requester name. |
| seeker_email* | body · string | Requester email. |
| seeker_phone | body · string | Optional phone. |
| message* | body · string | What the requester needs. |
curl -X POST "https://bezal.ai/api/v1/requests" \
-H "Authorization: Bearer bzl_your_key" \
-H "Content-Type: application/json" \
-d '{"business_id":"abc123…","seeker_name":"Jane Doe","seeker_email":"jane@example.com","message":"Need help with HR compliance"}'{
"success": true,
"id": "request-uuid",
"delivered": false
}/api/v1/healthNo authService health check + total business count.
curl "https://bezal.ai/api/v1/health"
{
"status": "ok",
"version": "1.0.0",
"timestamp": "2026-04-11T...",
"businesses_count": <number>
}/api/v1/openapiNo authOpenAPI 3 spec in YAML format. No auth required.
curl "https://bezal.ai/api/v1/openapi"
/api/mcpAuth optionalModel Context Protocol endpoint for AI agents. Stateless streamable HTTP transport. Implements tools/list and tools/call automatically via the official MCP SDK.
| Authorization | header · string | Bearer bzl_… (optional, anonymous requests are rate limited per IP). |
# Use any MCP-aware client (Claude Desktop, MCP Inspector, etc.) # Server URL: https://bezal.ai/api/mcp # Available tools: # search_businesses search by keyword, category, city or state # search_by_city businesses in one city, optionally by category # search_by_service businesses offering a specific service # get_business one business by UUID # get_reviews ratings and reviews for a business # get_service_catalog services and pricing for a business # check_business_availability opening hours on a given date # compare_businesses up to 5 businesses side by side # list_categories all categories