Semantics
Reserves a specific time slot for a named service with a named customer. The provider's calendar becomes blocked for the duration. The customer receives a confirmation. The booking is later addressable by `booking_id` for cancellation or status lookups.
Invariants
- `start_at` must be strictly in the future at the time of the call.
- `service_id` must be a service the provider currently offers.
- If a booking with the same `(provider_id, service_id, start_at, customer.email)` was created within the previous 60 seconds, the same `booking_id` is returned and no second booking is persisted (idempotency window).
- If the requested slot is no longer free at submit time, the call fails with `slot_taken` and returns the closest free slots from `available_alternatives`.
- The booking's `end_at` is derived from the service's declared duration; callers do not specify it.
When to use
When the user has already chosen which service, which provider, and which time. If any of those is missing, call `check_availability` first.
Input schema
{
"type": "object",
"required": [
"service_id",
"start_at",
"customer"
],
"properties": {
"notes": {
"type": "string",
"description": "Free-text note from customer to provider, max 1000 chars."
},
"customer": {
"type": "object",
"required": [
"name",
"email"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string"
}
},
"additionalProperties": false
},
"start_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 instant in UTC."
},
"service_id": {
"type": "string",
"description": "Provider-scoped service identifier from the provider's catalog (e.g. as returned by check_availability)."
},
"agent_vendor": {
"type": "string",
"description": "Self-identification of the calling agent (claude, chatgpt, cursor, ...). Optional but recommended."
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"enum": [
"slot_taken",
"invalid_service",
"past_time",
"invalid_input"
],
"type": "string"
},
"end_at": {
"type": "string",
"format": "date-time"
},
"service": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"customer": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
}
}
},
"start_at": {
"type": "string",
"format": "date-time"
},
"confirmed": {
"type": "boolean"
},
"booking_id": {
"type": "string"
},
"cancellation_url": {
"type": "string",
"format": "uri"
},
"available_alternatives": {
"type": "array",
"items": {
"type": "object",
"properties": {
"end_at": {
"type": "string",
"format": "date-time"
},
"start_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}