marketplace

Search for service businesses by location. Returns businesses with their booking URLs, ratings, and descriptions. Use get_business to see services and get_availability to check open slots.

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City, city+state, or zip code. E.g. 'Brooklyn NY', 'Austin, TX', '90210'"
    },
    "category": {
      "description": "Filter by business type",
      "type": "string",
      "enum": [
        "barbershop",
        "hair_salon",
        "tattoo_piercing",
        "nail_salon",
        "mobile_services",
        "fitness_training",
        "car_detailing",
        "spa_wellness",
        "yoga",
        "personal_trainer"
      ]
    },
    "limit": {
      "description": "Max results (default 10)",
      "default": 10,
      "type": "number",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "location"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get full details for a business including services (with IDs and prices), staff, and hours. You need service_id and optionally staff_id before calling book_appointment.

{
  "type": "object",
  "properties": {
    "slug": {
      "description": "The business slug from search_businesses results",
      "type": "string"
    },
    "business_slug": {
      "description": "Alias for slug — the business slug from search_businesses results",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get open appointment slots for a business on a specific date. Returns ISO timestamps for each available slot. Use these start_time/end_time values when calling book_appointment.

{
  "type": "object",
  "properties": {
    "business_slug": {
      "type": "string",
      "description": "The business slug from search_businesses results"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date to check in YYYY-MM-DD format"
    },
    "staff_id": {
      "description": "Specific staff member ID (from get_business). Omit to check any available staff.",
      "type": "string"
    },
    "timezone": {
      "description": "IANA timezone string (e.g. 'America/New_York'). Defaults to business local time.",
      "type": "string"
    }
  },
  "required": [
    "business_slug",
    "date"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reserve an appointment slot at a service business. Provide a unique idempotency_key to safely retry without double-booking. Get service_id from get_business and start_time/end_time from get_availability.

{
  "type": "object",
  "properties": {
    "business_slug": {
      "type": "string",
      "description": "The business slug from search_businesses results"
    },
    "service_id": {
      "type": "string",
      "description": "The service ID from get_business results"
    },
    "start_time": {
      "type": "string",
      "description": "ISO 8601 datetime for the appointment start (from get_availability)"
    },
    "end_time": {
      "type": "string",
      "description": "ISO 8601 datetime for the appointment end (from get_availability)"
    },
    "customer_name": {
      "type": "string",
      "description": "Customer full name"
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Customer email address"
    },
    "customer_phone": {
      "description": "Customer phone number (optional)",
      "type": "string"
    },
    "staff_id": {
      "description": "Staff member ID (from get_business). Omit to auto-assign.",
      "type": "string"
    },
    "notes": {
      "description": "Any special requests or notes for the business",
      "type": "string"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Unique key to prevent duplicate bookings (e.g. UUID). Reuse the same key to safely retry."
    }
  },
  "required": [
    "business_slug",
    "service_id",
    "start_time",
    "end_time",
    "customer_name",
    "customer_email",
    "idempotency_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Look up the current status/time of a booking you made. Requires the booking_id and the lookup_token that book_appointment returned. No account needed.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string",
      "description": "The booking_id returned from book_appointment"
    },
    "lookup_token": {
      "type": "string",
      "description": "The lookup_token returned from book_appointment for this booking"
    }
  },
  "required": [
    "booking_id",
    "lookup_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancel a booking you made. Requires booking_id and the lookup_token from book_appointment. Safe to retry (idempotent). No account needed.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string",
      "description": "The booking_id returned from book_appointment"
    },
    "lookup_token": {
      "type": "string",
      "description": "The lookup_token returned from book_appointment for this booking"
    }
  },
  "required": [
    "booking_id",
    "lookup_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Move a booking you made to a new time. Requires booking_id, the lookup_token from book_appointment, and new_start_time/new_end_time (ISO 8601, from get_availability). The new slot is checked for conflicts. No account needed.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string",
      "description": "The booking_id returned from book_appointment"
    },
    "lookup_token": {
      "type": "string",
      "description": "The lookup_token returned from book_appointment for this booking"
    },
    "new_start_time": {
      "type": "string",
      "description": "ISO 8601 datetime for the new appointment start (from get_availability)"
    },
    "new_end_time": {
      "type": "string",
      "description": "ISO 8601 datetime for the new appointment end (from get_availability)"
    }
  },
  "required": [
    "booking_id",
    "lookup_token",
    "new_start_time",
    "new_end_time"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a BookingMaven signup link pre-filled with the customer's details. The customer visits the link to set their password and activate their account, which links their past bookings.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Customer email (use the same email used for booking)"
    },
    "name": {
      "type": "string",
      "description": "Customer full name"
    },
    "phone": {
      "description": "Customer phone number (optional)",
      "type": "string"
    }
  },
  "required": [
    "email",
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a link for a business owner to sign up and list their business on BookingMaven. Returns a URL with optional pre-filled details.

{
  "type": "object",
  "properties": {
    "business_name": {
      "description": "Name of the business",
      "type": "string"
    },
    "category": {
      "description": "Type of business",
      "type": "string",
      "enum": [
        "barbershop",
        "hair_salon",
        "tattoo_piercing",
        "nail_salon",
        "mobile_services",
        "fitness_training",
        "car_detailing",
        "spa_wellness",
        "yoga",
        "personal_trainer"
      ]
    },
    "email": {
      "description": "Business owner email",
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List all appointments booked with your email address. Requires signing in (OAuth) — your AI must be connected with an authenticated account that has a verified email. Returns your upcoming and past bookings.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Link the guest bookings you made with your email to your signed-in account so you can manage them from your account. Requires signing in (OAuth) with a verified email.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}