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

TierDaily limitNotes
Anonymous100 / day per IPNo key. Best-effort.
Free100 / dayTied to your key.
Developer10,000 / dayBy request. Email us.
EnterpriseCustomBy request. Email us.

429 responses include the current count and limit. Limits reset daily.

Endpoints

GET/api/v1/businesses/searchAuth optional

Search 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.

Parameters
qquery · stringFree-text search across name + category.
categoryquery · stringCategory keyword (ILIKE match).
cityquery · stringCity name (case-insensitive). A Connecticut county here, like Litchfield County CT, searches its towns.
countyquery · stringA 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.
statequery · stringUS state code like CT, or the full state name. DC also takes D.C. and Washington DC. Anything else returns 400.
min_ratingquery · numberMinimum avg_rating filter (0-5).
pagequery · numberPagination page (default 1).
limitquery · numberPage size (1-20, default 10).
Example request
curl "https://bezal.ai/api/v1/businesses/search?q=hr+consulting&state=CT&limit=5" \
  -H "Authorization: Bearer bzl_your_key"
Example response
{
  "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
}
GET/api/v1/businesses/{id}Auth optional

Fetch 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.

Parameters
id*path · uuidBusiness UUID.
Example request
curl "https://bezal.ai/api/v1/businesses/abc123…" \
  -H "Authorization: Bearer bzl_your_key"
Example response
{
  "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
  }
}
GET/api/v1/categoriesAuth optional

List all business categories with name + slug.

Example request
curl "https://bezal.ai/api/v1/categories"
Example response
{
  "categories": [
    { "name": "HR Consulting", "slug": "hr-consulting" },
    { "name": "Plumbing", "slug": "plumbing" },
    ...
  ]
}
POST/api/v1/requestsAuth required

Submit 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.

Parameters
business_idbody · uuidOptional. Target business.
seeker_name*body · stringRequester name.
seeker_email*body · stringRequester email.
seeker_phonebody · stringOptional phone.
message*body · stringWhat the requester needs.
Example request
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"}'
Example response
{
  "success": true,
  "id": "request-uuid",
  "delivered": false
}
GET/api/v1/healthNo auth

Service health check + total business count.

Example request
curl "https://bezal.ai/api/v1/health"
Example response
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-04-11T...",
  "businesses_count": <number>
}
GET/api/v1/openapiNo auth

OpenAPI 3 spec in YAML format. No auth required.

Example request
curl "https://bezal.ai/api/v1/openapi"
POST/api/mcpAuth optional

Model Context Protocol endpoint for AI agents. Stateless streamable HTTP transport. Implements tools/list and tools/call automatically via the official MCP SDK.

Parameters
Authorizationheader · stringBearer bzl_… (optional, anonymous requests are rate limited per IP).
Example request
# 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
Get your API key →