{"info":{"description":"Book real appointment slots at local businesses. A confirmed booking costs the agent 0.10 USDC on Base L2 through the AgentPay facilitator; the business pays nothing and no contractor can pay for position in the queue.","title":"AgentPay Bookings - agent-callable appointments","version":"1.0.0"},"openapi":"3.0.0","paths":{"/api/b/<slug>/service-specs":{"post":{"responses":{"200":{"description":"specs stored"}},"summary":"Declare machine-checkable spec facts for one service (admin token)"}},"/api/b/<slug>/specs":{"get":{"responses":{"200":{"description":"services and products with their specs"}},"summary":"Every spec fact a business publishes (free)"}},"/api/b/desert-sage-demo":{"get":{"responses":{"200":{"description":"ok"}},"summary":"Business profile, services, hours, endpoints"}},"/api/b/desert-sage-demo/availability":{"get":{"parameters":[{"in":"query","name":"service","required":true,"schema":{"type":"string"}},{"in":"query","name":"date","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"}},"summary":"Open appointment start times for a service on a date"}},"/api/b/desert-sage-demo/book":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"agent":{"type":"string"},"date":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"notify_secret":{"description":"optional HMAC key; we send X-Agentbook-Signature: sha256=<hex>","type":"string"},"notify_url":{"description":"https URL we POST a signed change event to if the business reschedules or cancels","type":"string"},"phone":{"type":"string"},"service":{"type":"string"},"time":{"type":"string"}},"required":["service","date","time","name"],"type":"object"}}},"required":true},"responses":{"201":{"description":"booked"},"409":{"description":"slot taken"}},"summary":"Reserve a slot for a human; returns a confirmation code"}},"/api/b/desert-sage-demo/cancel":{"post":{"responses":{"200":{"description":"ok"}},"summary":"Cancel with the confirmation code"}},"/api/b/{slug}":{"get":{"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"profile"},"404":{"description":"unknown business"}},"summary":"One business profile and its services"}},"/api/b/{slug}/availability":{"get":{"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}},{"in":"query","name":"service","required":true,"schema":{"type":"string"}},{"in":"query","name":"date","required":true,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"description":"slots"},"400":{"description":"bad request"}},"summary":"Free start times for a service on a date (business local)"}},"/api/b/{slug}/book":{"post":{"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"agent":{"type":"string"},"date":{"format":"date","type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"service":{"type":"string"},"time":{"description":"HH:MM business-local","type":"string"}},"required":["service","date","time","name"],"type":"object"}}},"required":true},"responses":{"201":{"description":"booked, returns a confirmation code"},"400":{"description":"invalid input (checked before any payment)"},"402":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Payment required. The body names the facilitator at all three levels."},"409":{"description":"slot taken or does not exist on that date"}},"summary":"Reserve a slot. Holds it, then charges, then confirms."}},"/api/b/{slug}/booking/{code}/reschedule":{"post":{"description":"Requires the business admin_token. Send date + time in the business timezone, or starts_at as ISO-8601. Refuses a local time that does not exist (DST gap), a time another booking already holds, and a cancelled booking. If the booking registered notify_url, the agent gets a signed webhook and the delivery result is recorded.","requestBody":{"content":{"application/json":{"schema":{"properties":{"admin_token":{"type":"string"},"date":{"type":"string"},"note":{"type":"string"},"starts_at":{"type":"string"},"time":{"type":"string"}},"required":["admin_token"],"type":"object"}}},"required":true},"responses":{"200":{"description":"rescheduled; says whether the agent was notified"},"403":{"description":"admin_token_required"},"404":{"description":"unknown_code"},"409":{"description":"slot_taken | slot_in_dst_gap | already_cancelled"}},"summary":"Business moves an appointment; the agent's code resolves to the new time"}},"/api/b/{slug}/cancel":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"description":"cancelled"}},"summary":"Cancel with the confirmation code"}},"/api/b/{slug}/order":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"agent":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"note":{"type":"string"},"phone":{"type":"string"},"qty":{"type":"integer"},"reserve_only":{"description":"free 45 minute hold so you can show your human first","type":"boolean"},"sku":{"type":"string"}},"required":["sku","name"],"type":"object"}}},"required":true},"responses":{"200":{"description":"held, returns an HL- code"},"201":{"description":"placed"},"402":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Payment required. The body names the facilitator at all three levels."},"409":{"description":"out of stock"}},"summary":"Reserve stock (free hold) or buy outright"}},"/api/b/{slug}/order/confirm":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"description":"placed"},"402":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Payment required. The body names the facilitator at all three levels."},"409":{"description":"hold expired"}},"summary":"Turn a hold into a placed order (the fee is charged here)"}},"/api/b/{slug}/order/return":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"reason":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"description":"returned"}},"summary":"The human rejected it: return the item and read the refund terms"}},"/api/b/{slug}/products":{"get":{"responses":{"200":{"description":"catalog"}},"summary":"The business's product catalog with stock and preview images"},"post":{"responses":{"200":{"description":"saved"},"403":{"description":"admin token required"}},"summary":"Add or update stock (business admin token)"}},"/api/booking/{code}":{"get":{"description":"Free. Returns status, current start time in the business timezone, change_note, the payment that was taken, and the full event history. A code is not a snapshot: it follows the row, so a shop-side reschedule appears here as well.","parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current appointment state + events"},"404":{"description":"unknown_code"}},"summary":"Resolve a confirmation code to the appointment's CURRENT state"}},"/api/businesses":{"get":{"responses":{"200":{"description":"ok"}},"summary":"List bookable businesses"}},"/api/directory":{"get":{"responses":{"200":{"description":"directory"}},"summary":"Everything bookable here in one document"}},"/api/hvac/book":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"address":{"type":"string"},"agent":{"type":"string"},"city":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"notes":{"type":"string"},"phone":{"type":"string"},"service":{"type":"string"},"urgency":{"enum":["emergency","soon","planned"],"type":"string"},"window":{"type":"string"}},"required":["city","service","name"],"type":"object"}}},"required":true},"responses":{"200":{"description":"already booked (retry) or booked"},"201":{"description":"booked"},"402":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Payment required. The body names the facilitator at all three levels."},"404":{"description":"outside coverage"}},"summary":"Book a vetted local trade call (HVAC, appliance, refrigeration)"}},"/api/hvac/cancel":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"code":{"type":"string"},"reason":{"type":"string"}},"required":["code"],"type":"object"}}},"required":true},"responses":{"200":{"description":"cancelled"}},"summary":"Cancel a trade booking and tell you whether the desk acknowledged it"}},"/api/hvac/coverage":{"get":{"responses":{"200":{"description":"coverage"}},"summary":"Which trade desks cover which cities, free"}},"/api/match":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"category":{"type":"string"},"city":{"type":"string"},"kind":{"enum":["service","product"],"type":"string"},"limit":{"type":"integer"},"must":{"additionalProperties":true,"description":"requirements, e.g. {\"accessible\": true, \"return_window_days\": {\"op\": \">=\", \"value\": 30}}","type":"object"},"q":{"type":"string"},"service":{"type":"string"},"slug":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"candidates with pass/fail/unknown per requirement, plus recommendation book or skip"}},"summary":"Match services or products to a must-have list (free)"}},"/api/products":{"get":{"parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"city","schema":{"type":"string"}},{"in":"query","name":"in_stock","schema":{"type":"boolean"}}],"responses":{"200":{"description":"matches"}},"summary":"Search every listed product, free"}},"/api/register":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"booking_url":{"type":"string"},"category":{"type":"string"},"city":{"type":"string"},"email":{"type":"string"},"hours":{"type":"object"},"mode":{"enum":["hosted","link"],"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"services":{"items":{"type":"object"},"type":"array"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"description":"created"}},"summary":"Register a business on the booking rail"}},"/api/skip":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"kind":{"enum":["service","product"],"type":"string"},"must":{"additionalProperties":true,"description":"requirements, e.g. {\"accessible\": true, \"return_window_days\": {\"op\": \">=\", \"value\": 30}}","type":"object"},"reason":{"type":"string"},"service":{"type":"string"},"sku":{"type":"string"},"slug":{"type":"string"},"unmet":{"items":{"type":"string"},"type":"array"}},"required":["reason"],"type":"object"}}},"required":true},"responses":{"200":{"description":"skip recorded; nothing booked, nothing charged"}},"summary":"Record an honest no-fit decision instead of a wrong booking (free)"}},"/api/skips/stats":{"get":{"responses":{"200":{"description":"skip counts by kind, bookings, orders, skip_rate"}},"summary":"30-day skip rate against real bookings and orders (free)"}},"/mcp":{"post":{"responses":{"200":{"description":"json-rpc"}},"summary":"MCP streamable HTTP endpoint (initialize, tools/list, tools/call)"}}},"servers":[{"url":"https://agentpaystore.com/book"}]}