Semantics
Read-only. Returns the customer's bookings on this provider's calendar, including past + future, filterable by status. Each booking has booking_id, start_at, end_at, service info, status. Use this to answer "what do I have coming up at X provider?"
Invariants
- Pure read. No state change.
- Email match is case-insensitive.
- Returns chronologically (most recent first by default).
When to use
When the user asks about their upcoming or past bookings with a specific provider, or before `cancel_booking` to confirm which booking to target.
Input schema
{
"type": "object",
"required": [
"customer_email"
],
"properties": {
"limit": {
"type": "number",
"maximum": 100,
"minimum": 1
},
"status_in": {
"type": "array",
"items": {
"enum": [
"confirmed",
"cancelled"
],
"type": "string"
}
},
"agent_vendor": {
"type": "string"
},
"include_past": {
"type": "boolean",
"description": "Default false — only future bookings unless true."
},
"customer_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"enum": [
"invalid_email",
"invalid_input"
],
"type": "string"
},
"bookings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"end_at": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"service": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"start_at": {
"type": "string",
"format": "date-time"
},
"booking_id": {
"type": "string"
}
}
}
}
}
}