# Jing Companion (京伴) travel API 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. This manual is for first-party agents muse and instinct, and for any LLM agent that can call HTTPS APIs. Guests browse, book, and subscribe without signing in. Leave a contact email. Google sign-in is only for operators and travel hosts. Base URL: https://t.irss.cc Locale: send ?lang= or Accept-Language (en default; also zh-Hans, ja, ko, es, fr). Cache: catalog GET responses may be cached briefly. Booking and payment responses are Cache-Control: no-store and are never stored in KV. Recommended call order: 1. Read this document (GET /llms-travel.txt). 2. GET /api/v1/travel/cities 3. GET /api/v1/travel/attractions?city=beijing 4. GET /api/v1/travel/services?city=beijing&lang=en (optional filters: attraction, kind=attraction|combo) 5. GET /api/v1/travel/services/{id_or_slug} 6. GET /api/v1/travel/availability?service_id={id_or_slug}&date=YYYY-MM-DD 7. Confirm the date, start time, and party size with the guest. 8. POST /api/v1/travel/bookings with contact_email and header Idempotency-Key. 9. Give the guest booking.checkout_path (and access_token if they need to reopen the checkout). 10. Do not invent a paid status. Wait for the guest to pay with PayPal. Public catalog (no auth): - GET /api/v1/travel/cities - GET /api/v1/travel/attractions?city=beijing - GET /api/v1/travel/services?city=beijing&attraction=&kind=attraction|combo&lang=en - GET /api/v1/travel/services/:id - GET /api/v1/travel/availability?service_id=&date=YYYY-MM-DD - GET /api/v1/travel/plans - GET /api/v1/travel/plans/:id - Fact pages: GET /llms/index.md, /llms/tours/{slug}.md, /llms/plans/{slug}.md - OpenAPI: GET /openapi-travel.json Guest bookings and subscriptions: - POST /api/v1/travel/bookings — Idempotency-Key required. Body must include contact_email, service_id, date, start_time, party_size. - GET /api/v1/travel/bookings/:id — use query ?access= or header X-Checkout-Access with the access_token from the create response. - POST /api/v1/travel/subscriptions — Idempotency-Key required. Body: plan_id, contact_email. - GET /api/v1/travel/subscriptions/:id — same access token pattern. - POST /api/v1/travel/subscriptions/:id/cancel — same access token pattern. - POST /api/v1/travel/subscriptions/:id/paypal/create — starts PayPal Subscriptions when PayPal is configured. - POST /api/v1/travel/subscriptions/:id/demo-pay — development only, when PayPal is not configured. Clearly labeled demo. Not a PayPal charge. Do not offer this as the primary payment path. Access tokens are HMAC values bound to the order or subscription id. Pass them as ?access= or X-Checkout-Access. They are not session cookies and do not grant admin access. Authorization: Bearer is optional for muse and instinct. It is not required to create a guest booking. A contact email is required for guest checkout. The platform does not issue a login session for that email. Booking JSON example: {"service_id":"tour_forbidden_city","date":"2026-12-01","start_time":"08:30","party_size":2,"preferred_language":"en","pickup_location":"Beijing Hotel lobby","contact_email":"guest@example.com","addon_ids":["private_car"]} Subscription JSON example: {"plan_id":"weekly-host","contact_email":"guest@example.com"} Prices are in USD cents unless a response says otherwise. Tour prices typically cover a private host for 1–4 guests. Extra guests and a private-car add-on may apply; check the service payload. PayPal is the live payment method (Orders v2 Capture for one-time tours; PayPal Subscriptions for plans). Errors are JSON objects with a machine-readable code and a human message, for example {"error":"...","code":"idempotency_required"}. Relay the message; do not invent a success. Common error codes: 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.