{"openapi":"3.1.0","info":{"title":"Taylor Notaries Agent API","version":"2.0.0","summary":"Check availability and book notary appointments in Austin, Texas.","description":"Taylor Notaries provides out-of-hours notary appointments in Austin, Texas, in person or online via Zoom. External AI agents may use this API to list services, check genuine appointment availability, book an appointment on behalf of a customer, look up a booking and cancel one.\n\nRules: never invent availability; always call checkAvailability first; only call bookAppointment with an exact slot returned by checkAvailability; re-query availability if your information may be stale. All times use the America/Chicago business time zone unless a timezone parameter is supplied. No authentication is required; requests are rate limited per caller.","contact":{"name":"Taylor Notaries","email":"richard@taylornotaries.com"}},"servers":[{"url":"https://taylornotaries.com","description":"Taylor Notaries production"}],"externalDocs":{"description":"Agent guidance","url":"https://taylornotaries.com/llms.txt"},"tags":[{"name":"appointments","description":"Appointment availability and booking."}],"components":{"securitySchemes":{},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated unique string. Reuse the same value when retrying so a retry cannot create a second booking.","schema":{"type":"string","maxLength":200},"example":"agent-8f21c0f4-2f0a-4b7f-9a2a-2d0c1b6d1a11"}},"schemas":{"Service":{"type":"object","properties":{"id":{"type":"string","example":"notary_appointment"},"name":{"type":"string"},"description":{"type":"string"},"durationMinutes":{"type":"integer","example":10},"meetingTypes":{"type":"array","items":{"type":"string","enum":["in_person","online"]}},"currency":{"type":"string","example":"usd"},"unitPriceCents":{"type":"integer","example":1000},"pricingModel":{"type":"string"},"fees":{"type":"object","description":"Statutory notarial fees (Tex. Gov't Code 406.024). No sales tax, no card fee."},"fields":{"type":"object"},"location":{"type":"string"},"requiredCustomerFields":{"type":"array","items":{"type":"string"}}},"required":["id","name","durationMinutes","meetingTypes"]},"Slot":{"type":"object","properties":{"time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Slot start, 24-hour, business time zone.","example":"18:30"},"startsAt":{"type":"string","format":"date-time"},"localTime":{"type":"string","description":"Slot start rendered in the requested timezone.","example":"2026-09-15T18:30"}},"required":["time","startsAt"]},"AvailabilityResponse":{"type":"object","properties":{"serviceId":{"type":"string"},"timezone":{"type":"string"},"businessTimezone":{"type":"string","example":"America/Chicago"},"slotMinutes":{"type":"integer","example":10},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"availableSlots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}}},"required":["date","availableSlots"]}},"closestToPreferredTime":{"type":"array","description":"Present only when preferred_time was supplied.","items":{"$ref":"#/components/schemas/Slot"}}},"required":["serviceId","timezone","slotMinutes","days"]},"BookRequest":{"type":"object","required":["date","time","customer_name","customer_email","customer_phone"],"properties":{"service_id":{"type":"string","default":"notary_appointment"},"date":{"type":"string","format":"date","description":"Appointment date in the business time zone.","example":"2026-09-15"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Exact slot start returned by checkAvailability, 24-hour, business time zone.","example":"18:30"},"meeting_type":{"type":"string","enum":["in_person","online"],"default":"in_person"},"customer_name":{"type":"string","example":"Jordan Alvarez"},"customer_email":{"type":"string","format":"email"},"customer_phone":{"type":"string","example":"+1 512 555 0142"},"act_type":{"type":"string","enum":["acknowledgment","jurat"],"default":"acknowledgment","description":"Notarial act. acknowledgment: $10 first signature + $1 each additional signature per certificate; jurat (oath/affirmation): $10 per certificate. Tex. Gov't Code 406.024; no sales tax."},"signers":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Signatures per document (sets the acknowledgment fee); for a jurat, people signing (planning only)."},"documents":{"type":"integer","minimum":1,"maximum":20,"default":1},"notes":{"type":"string","maxLength":450}}},"BookResponse":{"type":"object","properties":{"status":{"type":"string","enum":["pending_payment"]},"message":{"type":"string"},"bookingReference":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"integer","description":"Unix time the checkout link expires."},"booking":{"type":"object","properties":{"serviceId":{"type":"string"},"date":{"type":"string","format":"date"},"time":{"type":"string"},"timezone":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"meetingType":{"type":"string","enum":["in_person","online"]},"signers":{"type":"integer"},"documents":{"type":"integer"},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"subtotalCents":{"type":"integer"},"actType":{"type":"string","enum":["acknowledgment","jurat"]},"lineItems":{"type":"array","items":{"type":"object"},"description":"Itemized notarial fee lines; non-notarial charges appear as separate lines."},"totalCents":{"type":"integer"},"currency":{"type":"string"}}}},"required":["status","bookingReference","checkoutUrl"]},"BookingResponse":{"type":"object","properties":{"bookingId":{"type":"string","format":"uuid"},"bookingReference":{"type":"string"},"status":{"type":"string","enum":["confirmed","not_found"]},"serviceId":{"type":"string"},"date":{"type":"string","format":"date"},"time":{"type":"string"},"timezone":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"meetingType":{"type":"string"},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"signers":{"type":"integer"},"documents":{"type":"integer"},"totalCents":{"type":"integer"},"currency":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"cancellable":{"type":"boolean"},"cancellationPolicy":{"type":"string"}}},"CancelRequest":{"type":"object","required":["email","date","time"],"properties":{"email":{"type":"string","format":"email"},"date":{"type":"string","format":"date","example":"2026-09-15"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","example":"18:30"}}},"CancelResponse":{"type":"object","properties":{"status":{"type":"string","enum":["cancelled"]},"refunded":{"type":"boolean"},"booking":{"type":"object","properties":{"date":{"type":"string","format":"date"},"time":{"type":"string"},"email":{"type":"string","format":"email"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}},"security":[],"paths":{"/api/agent/services":{"get":{"operationId":"getServices","tags":["appointments"],"summary":"List bookable appointment types","description":"Returns the service types that can be booked, their duration, pricing and the customer details required. Call this first if you do not already know the service_id.","security":[],"responses":{"200":{"description":"The bookable services and business details.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"type":"object"},"slotMinutes":{"type":"integer"},"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}},"examples":{"default":{"value":{"business":{"name":"Taylor Notaries","timezone":"America/Chicago","address":"7201 Ranch Road 2222, Austin, Texas 78730","openingHours":["Monday – Friday: 6:00 pm – 11:00 pm","Saturday: 9:00 am – 11:00 pm","Sunday: 1:00 pm – 11:00 pm"]},"slotMinutes":10,"services":[{"id":"notary_appointment","name":"Notary appointment","durationMinutes":10,"meetingTypes":["in_person","online"],"currency":"usd","unitPriceCents":1000}]}}}}}}}}},"/api/agent/availability":{"get":{"operationId":"checkAvailability","tags":["appointments"],"summary":"Check genuine appointment availability","description":"Returns the appointment slots that are actually free, taking opening hours, existing bookings and manually blocked times into account. Never present a time to a customer unless it appears in this response. Re-query if your information may be stale.","security":[],"parameters":[{"name":"service_id","in":"query","required":false,"schema":{"type":"string","default":"notary_appointment"},"description":"Service to check. Defaults to the notary appointment."},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Single date to check (YYYY-MM-DD, business time zone). Use this or start_date.","example":"2026-09-15"},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"First date of a range (maximum 31 days)."},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Last date of a range. Defaults to start_date."},{"name":"timezone","in":"query","required":false,"schema":{"type":"string","default":"America/Chicago"},"description":"IANA time zone used for the localTime field. Slot 'time' values always stay in the business time zone.","example":"America/New_York"},{"name":"preferred_time","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"description":"Optional preferred start time; the response then also lists the five closest available slots.","example":"19:00"}],"responses":{"200":{"description":"Available slots.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"},"examples":{"singleDate":{"summary":"Availability for one date","value":{"serviceId":"notary_appointment","timezone":"America/Chicago","businessTimezone":"America/Chicago","slotMinutes":10,"startDate":"2026-09-15","endDate":"2026-09-15","days":[{"date":"2026-09-15","availableSlots":[{"time":"18:30","startsAt":"2026-09-15T23:30:00.000Z","localTime":"2026-09-15T18:30"}]}],"date":"2026-09-15","availableSlots":["18:30"]}}}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"invalid_request","message":"Provide either 'date' or 'start_date'."}}}}}}},"404":{"description":"Unknown service_id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"not_found","message":"Unknown service_id 'haircut'."}}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Try again in a minute."}}}}}}}}}},"/api/agent/book":{"post":{"operationId":"bookAppointment","tags":["appointments"],"summary":"Book an appointment","description":"Call only after the customer has chosen an exact slot returned by checkAvailability. The server rechecks availability immediately before creating anything and applies the normal appointment rules. It returns a checkoutUrl: give that link to the customer. The appointment is confirmed only once payment completes. Send an Idempotency-Key header and reuse it on retries so a retry cannot create a second booking.","security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookRequest"},"examples":{"default":{"value":{"service_id":"notary_appointment","date":"2026-09-15","time":"18:30","meeting_type":"online","customer_name":"Jordan Alvarez","customer_email":"jordan@example.com","customer_phone":"+1 512 555 0142","signers":1,"documents":2,"notes":"Power of attorney, needs a witness."}}}}}},"responses":{"200":{"description":"Checkout created; awaiting customer payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookResponse"},"examples":{"default":{"value":{"status":"pending_payment","message":"Give the customer this checkout link. The appointment is confirmed only after payment is completed.","bookingReference":"cs_test_a1b2c3","checkoutUrl":"https://checkout.stripe.com/c/pay/cs_test_a1b2c3","expiresAt":1789000000,"booking":{"serviceId":"notary_appointment","date":"2026-09-15","time":"18:30","timezone":"America/Chicago","startsAt":"2026-09-15T23:30:00.000Z","meetingType":"online","signers":1,"documents":2,"totalCents":2125,"currency":"usd"}}}}}}},"400":{"description":"Invalid booking details.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"invalid_request","message":"customer_name, customer_email and customer_phone are required."}}}}}}},"409":{"description":"Slot cannot be booked.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"slot_unavailable","message":"That slot is no longer available. Call checkAvailability again and pick another slot."}}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"rate_limited","message":"Too many booking requests. Try again shortly."}}}}}}},"502":{"description":"Payment provider error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"payment_error","message":"Could not create a checkout session."}}}}}}}}}},"/api/agent/booking/{booking_id}":{"get":{"operationId":"getBooking","tags":["appointments"],"summary":"Get a booking's confirmation and status","description":"Returns the confirmed booking for a reference. Authorization: the customer's email address must be supplied and must match the booking. A 404 means either no such booking or payment was never completed.","security":[],"parameters":[{"name":"booking_id","in":"path","required":true,"schema":{"type":"string"},"description":"The bookingReference returned by bookAppointment, or the booking's id.","example":"cs_test_a1b2c3"},{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email"},"description":"The customer email the booking was made with.","example":"jordan@example.com"}],"responses":{"200":{"description":"The confirmed booking.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingResponse"},"examples":{"default":{"value":{"bookingId":"0f1d5b62-6d63-4a1e-9a8f-2a1c0e7d33aa","bookingReference":"cs_test_a1b2c3","status":"confirmed","serviceId":"notary_appointment","date":"2026-09-15","time":"18:30","timezone":"America/Chicago","startsAt":"2026-09-15T23:30:00.000Z","meetingType":"online","customerName":"Jordan Alvarez","customerEmail":"jordan@example.com","signers":1,"documents":2,"totalCents":2125,"currency":"usd","cancellable":true}}}}}},"400":{"description":"Missing booking id or email.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"invalid_request","message":"A booking id and the customer's 'email' query parameter are required."}}}}}}},"404":{"description":"No confirmed booking matches that reference and email.","content":{"application/json":{"examples":{"default":{"value":{"bookingReference":"cs_test_a1b2c3","status":"not_found","message":"No confirmed booking matches that reference and email. If the customer has not finished paying, the appointment is not confirmed yet."}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Try again in a minute."}}}}}}}}}},"/api/agent/cancel":{"post":{"operationId":"cancelAppointment","tags":["appointments"],"summary":"Cancel an appointment","description":"Cancels a confirmed appointment and refunds the customer in full. Allowed only at least 24 hours before the appointment start time. Identify the appointment by the customer email plus the exact date and time.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"},"examples":{"default":{"value":{"email":"jordan@example.com","date":"2026-09-15","time":"18:30"}}}}}},"responses":{"200":{"description":"Cancelled and refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelResponse"},"examples":{"default":{"value":{"status":"cancelled","refunded":true,"booking":{"date":"2026-09-15","time":"18:30","email":"jordan@example.com"}}}}}}},"400":{"description":"Invalid cancellation details.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"invalid_request","message":"Invalid cancellation details."}}}}}}},"404":{"description":"No matching appointment.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"not_found","message":"No appointment found for that email, date and time."}}}}}}},"409":{"description":"Inside the cancellation cutoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"cancellation_cutoff","message":"Appointments can only be cancelled at least 24 hours in advance. Please call or email us."}}}}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","slot_unavailable","outside_opening_hours","in_the_past","cancellation_cutoff","rate_limited","idempotency_conflict","payment_error","server_error"]},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"examples":{"default":{"value":{"error":{"code":"rate_limited","message":"Too many requests. Try again in a minute."}}}}}}}}}}}}