{"openapi":"3.0.3","info":{"title":"Jing Companion (京伴) travel API","version":"2.0.0","description":"A private Beijing local-companion (地陪) service for international visitors. Jing Companion is a private local-companion (地陪) service. It is not a government agency or official tourism bureau, and is not affiliated with the sites we visit. Currently Beijing only. Recommended call order: GET /llms-travel.txt → list cities/attractions/services/availability → confirm date and party size → POST /api/v1/travel/bookings with contact_email and Idempotency-Key → give the guest the PayPal payment link → never invent a paid status. Guests do not need an account. Google sign-in is only for operators and travel hosts. PayPal is the live payment method.","contact":{"email":"zhangjianwin@gmail.com","url":"https://t.irss.cc"}},"servers":[{"url":"https://t.irss.cc"}],"tags":[{"name":"Catalog","description":"Public read APIs. No authentication."},{"name":"Bookings","description":"Guest checkout with contact email and Idempotency-Key."},{"name":"Subscriptions","description":"Guest plan checkout with contact email and Idempotency-Key."}],"paths":{"/api/v1/travel/cities":{"get":{"tags":["Catalog"],"summary":"List cities","parameters":[{"name":"lang","in":"query","required":false,"description":"Locale: en (default), zh-Hans, ja, ko, es, fr","schema":{"type":"string"}}],"responses":{"200":{"description":"City list"}}}},"/api/v1/travel/attractions":{"get":{"tags":["Catalog"],"summary":"List attractions in a city","parameters":[{"name":"city","in":"query","required":false,"description":"City slug","schema":{"type":"string","example":"beijing"}},{"name":"lang","in":"query","required":false,"description":"Locale: en (default), zh-Hans, ja, ko, es, fr","schema":{"type":"string"}}],"responses":{"200":{"description":"Attraction list"},"404":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/services":{"get":{"tags":["Catalog"],"summary":"List published tours","parameters":[{"name":"city","in":"query","required":false,"description":"City slug","schema":{"type":"string","example":"beijing"}},{"name":"attraction","in":"query","required":false,"description":"Optional attraction slug","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"attraction or combo","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Locale: en (default), zh-Hans, ja, ko, es, fr","schema":{"type":"string"}}],"responses":{"200":{"description":"Tour list, including price.amount_cents, currency, and group_size.base_guests"}}}},"/api/v1/travel/services/{id}":{"get":{"tags":["Catalog"],"summary":"Get one tour by id or slug","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Locale: en (default), zh-Hans, ja, ko, es, fr","schema":{"type":"string"}}],"responses":{"200":{"description":"Tour detail"},"404":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/availability":{"get":{"tags":["Catalog"],"summary":"Check whether a tour date is open","parameters":[{"name":"service_id","in":"query","required":true,"description":"Tour id or slug","schema":{"type":"string"}},{"name":"date","in":"query","required":true,"description":"Tour date YYYY-MM-DD","schema":{"type":"string"}}],"responses":{"200":{"description":"open, reason, remaining, start_times, closed_weekdays"},"400":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}},"404":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/plans":{"get":{"tags":["Catalog"],"summary":"List active stay plans","parameters":[{"name":"lang","in":"query","required":false,"description":"Locale: en (default), zh-Hans, ja, ko, es, fr","schema":{"type":"string"}}],"responses":{"200":{"description":"Plan list with price_cents and currency"}}}},"/api/v1/travel/plans/{id}":{"get":{"tags":["Catalog"],"summary":"Get one plan by id or slug","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"Locale: en (default), zh-Hans, ja, ko, es, fr","schema":{"type":"string"}}],"responses":{"200":{"description":"Plan detail"},"404":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/bookings":{"post":{"tags":["Bookings"],"summary":"Create a guest booking","description":"No account required. contact_email and Idempotency-Key are required. Returns checkout_path and access_token. Give the guest the payment link. Never invent a paid status.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for this create call. Replays return the original booking or subscription.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service_id","date","start_time","party_size","contact_email"],"properties":{"service_id":{"type":"string"},"date":{"type":"string","format":"date"},"start_time":{"type":"string","example":"08:30"},"party_size":{"type":"integer","minimum":1},"contact_email":{"type":"string","format":"email"},"preferred_language":{"type":"string"},"pickup_location":{"type":"string"},"special_requests":{"type":"string"},"addon_ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Idempotent replay of the same Idempotency-Key."},"201":{"description":"Booking created. Includes booking.checkout_path and access_token."},"400":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}},"409":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/bookings/{id}":{"get":{"tags":["Bookings"],"summary":"Get a booking","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"access","in":"query","required":false,"description":"Guest access token from the create response. Alternative: header X-Checkout-Access.","schema":{"type":"string"}},{"name":"X-Checkout-Access","in":"header","required":false,"description":"Guest access token from the create response. Alternative: query access=.","schema":{"type":"string"}}],"responses":{"200":{"description":"Booking and payment mode"},"401":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}},"404":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/subscriptions":{"post":{"tags":["Subscriptions"],"summary":"Create a guest subscription","description":"No account required. contact_email and Idempotency-Key are required.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for this create call. Replays return the original booking or subscription.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan_id","contact_email"],"properties":{"plan_id":{"type":"string"},"contact_email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Idempotent replay"},"201":{"description":"Subscription created with checkout_path and access_token"},"400":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/subscriptions/{id}":{"get":{"tags":["Subscriptions"],"summary":"Get a subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"access","in":"query","required":false,"description":"Guest access token from the create response. Alternative: header X-Checkout-Access.","schema":{"type":"string"}},{"name":"X-Checkout-Access","in":"header","required":false,"description":"Guest access token from the create response. Alternative: query access=.","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription and payment mode"},"401":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/subscriptions/{id}/cancel":{"post":{"tags":["Subscriptions"],"summary":"Cancel a subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"access","in":"query","required":false,"description":"Guest access token from the create response. Alternative: header X-Checkout-Access.","schema":{"type":"string"}},{"name":"X-Checkout-Access","in":"header","required":false,"description":"Guest access token from the create response. Alternative: query access=.","schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"401":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}},"409":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/subscriptions/{id}/paypal/create":{"post":{"tags":["Subscriptions"],"summary":"Start PayPal Subscriptions checkout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"access","in":"query","required":false,"description":"Guest access token from the create response. Alternative: header X-Checkout-Access.","schema":{"type":"string"}},{"name":"X-Checkout-Access","in":"header","required":false,"description":"Guest access token from the create response. Alternative: query access=.","schema":{"type":"string"}}],"responses":{"200":{"description":"PayPal approval link"},"409":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}},"/api/v1/travel/subscriptions/{id}/demo-pay":{"post":{"tags":["Subscriptions"],"summary":"Development-only demo activation","description":"Available only when PayPal is not configured. Clearly labeled demo. Not a PayPal charge. Do not present this as the primary payment path.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"access","in":"query","required":false,"description":"Guest access token from the create response. Alternative: header X-Checkout-Access.","schema":{"type":"string"}},{"name":"X-Checkout-Access","in":"header","required":false,"description":"Guest access token from the create response. Alternative: query access=.","schema":{"type":"string"}}],"responses":{"200":{"description":"Demo activation"},"409":{"description":"Error with machine-readable code and human message","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message. Relay this to the guest."},"code":{"type":"string","description":"Machine-readable code such as not_found, invalid_input, idempotency_required, invalid_date, invalid_party_size, invalid_start_time, unavailable, closed_weekday, sold_out, past_date, unauthorized, forbidden, paypal_unconfigured, paypal_required, invalid_state."},"details":{}},"required":["error","code"]}}}}