{"openapi":"3.1.0","info":{"title":"CitedTravel API","version":"0.2.0","summary":"Agent-readable travel facts with citations, licenses, last_verified dates and confidence scores.","description":"Every fact carries `sources` (publisher, URL, license, verbatim quote or source value), `cross_checks`, `last_verified`, `next_review_due` and `confidence {score, level, reasons}`.\n\n**Languages:** pass `lang` (BCP 47) or `Accept-Language`. Supported: en, ja, zh-Hans, zh-Hant. Any field `x` with a sibling `x_i18n` is resolved to the requested language with English fallback, and `x_lang` says which was served. Verbatim official quotes are never translated; translations (none yet) would be separate and labelled unofficial.\n\n**Entry requirements** are a pilot (GB, US, JP passports) and decision support only: every answer has an `advisory`, `official_links` and `not_a_verdict`.\n\n**Access:** static categories work without a key (60 requests/min/IP). A free key (1,000 calls/month, 50 entry calls) is required for entry and trip briefs. Paid plans (Builder, Pro) are coming soon. Agents may instead pay per call with x402 v2 (`PAYMENT-SIGNATURE` header; USDC on Base mainnet; payments are final).\n\n**Disclaimer:** informational only; not legal or immigration advice. See https://citedtravel.com/disclaimer/ (DRAFT).","termsOfService":"https://citedtravel.com/terms/","contact":{"name":"CitedTravel","url":"https://citedtravel.com/docs/"},"license":{"name":"Data: per-fact source licenses (see attribution field)","url":"https://citedtravel.com/docs/#licensing"}},"servers":[{"url":"https://citedtravel.com"}],"security":[{},{"bearer":[]},{"apiKey":[]}],"tags":[{"name":"facts"},{"name":"entry"},{"name":"meta"},{"name":"billing"}],"paths":{"/v1/countries":{"get":{"tags":["meta"],"operationId":"listCountries","summary":"List countries with localized names","parameters":[{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Countries","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/resolve":{"get":{"tags":["meta"],"operationId":"resolveCountry","summary":"Resolve a country name/alias/code (en, ja, zh)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Name, alias or code"},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Matches","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/countries/{cc}":{"get":{"tags":["facts"],"operationId":"getCountry","summary":"All static facts for one country (holidays: current year)","parameters":[{"name":"cc","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2,3}$"},"description":"ISO 3166-1 alpha-2 or alpha-3 code"},{"name":"categories","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated subset"},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Country bundle","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"x-x402-price-usd":0.005,"x-x402-network":"eip155:8453 (Base mainnet, USDC)"}},"/v1/countries/{cc}/{category}":{"get":{"tags":["facts"],"operationId":"getCountryCategory","summary":"Facts for one category","parameters":[{"name":"cc","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2,3}$"},"description":"ISO 3166-1 alpha-2 or alpha-3 code"},{"name":"category","in":"path","required":true,"schema":{"enum":["power","currency","emergency","driving","holidays","tipping"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"holidays only: start date"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"holidays only: end date"},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Category facts","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryResponse"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"x-x402-price-usd":0.005,"x-x402-network":"eip155:8453 (Base mainnet, USDC)"}},"/v1/power/compat":{"get":{"tags":["facts"],"operationId":"powerCompat","summary":"Adapter / converter verdict (computed)","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string"},"description":"Home country"},{"name":"to","in":"query","required":true,"schema":{"type":"string"},"description":"Destination"},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Verdict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"x-x402-price-usd":0.005,"x-x402-network":"eip155:8453 (Base mainnet, USDC)"}},"/v1/entry":{"get":{"tags":["entry"],"operationId":"getEntry","summary":"Visa/entry pilot answer (informational)","description":"Short tourist stays. Returns status, max stay, verbatim official quotes (authoritative, original language), confidence, official links and a mandatory advisory. Never a go/no-go verdict.","parameters":[{"name":"passport","in":"query","required":true,"schema":{"type":"string"},"description":"Passport country (GB, US, JP)"},{"name":"destination","in":"query","required":true,"schema":{"type":"string"},"description":"Destination country"},{"name":"purpose","in":"query","required":false,"schema":{"enum":["tourism"]},"description":"Only 'tourism'"},{"$ref":"#/components/parameters/lang"}],"security":[{"bearer":[]},{"apiKey":[]},{"x402":[]}],"responses":{"200":{"description":"Entry answer","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryAnswer"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"x-x402-price-usd":0.01,"x-x402-network":"eip155:8453 (Base mainnet, USDC)"}},"/v1/trip-brief":{"get":{"tags":["entry"],"operationId":"getTripBrief","summary":"Combined trip brief","parameters":[{"name":"home","in":"query","required":true,"schema":{"type":"string"},"description":"Home country"},{"name":"destinations","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated, max 5"},{"name":"passport","in":"query","required":false,"schema":{"type":"string"},"description":"Passport country (optional; adds entry)"},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Trip start"},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Trip end"},{"$ref":"#/components/parameters/lang"}],"security":[{"bearer":[]},{"apiKey":[]},{"x402":[]}],"responses":{"200":{"description":"Trip brief","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"x-x402-price-usd":0.02,"x-x402-network":"eip155:8453 (Base mainnet, USDC)"}},"/v1/changes":{"get":{"tags":["meta"],"operationId":"listChanges","summary":"Change feed","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD"},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Category filter"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Country filter"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max rows (500)"}],"responses":{"200":{"description":"Changes","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"x-x402-price-usd":0.005,"x-x402-network":"eip155:8453 (Base mainnet, USDC)"}},"/v1/sources":{"get":{"tags":["meta"],"operationId":"listSources","summary":"Source register with licenses and attribution","responses":{"200":{"description":"Sources","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/sources/{source_id}":{"get":{"tags":["meta"],"operationId":"getSource","summary":"One source","parameters":[{"name":"source_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Source","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Content-Language":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/v1/keys":{"post":{"tags":["billing"],"operationId":"createFreeKey","summary":"Create a free API key (shown once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"accept_terms":{"type":"boolean","const":true}}}}}},"responses":{"201":{"description":"Key created"},"400":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/mcp":{"post":{"tags":["meta"],"operationId":"mcp","summary":"Remote MCP endpoint (Streamable HTTP, JSON-RPC 2.0)","responses":{"200":{"description":"JSON-RPC response"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key: ct_live_… / ct_test_…"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment payload (base64 JSON). See the PAYMENT-REQUIRED header of a 402 response."}},"parameters":{"lang":{"name":"lang","in":"query","schema":{"type":"string","examples":["en","ja","zh-Hans","zh-Hant","zh-TW"]},"description":"BCP 47 language tag; falls back to English."}},"headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until reset"}},"responses":{"Problem":{"description":"RFC 9457 problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PaymentRequired":{"description":"x402 v2: payment required (PAYMENT-REQUIRED header, base64 JSON)","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}}},"schemas":{"Problem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}},"I18n":{"type":"object","description":"BCP 47 tag → string","propertyNames":{"enum":["en","ja","zh-Hans","zh-Hant"]},"additionalProperties":{"type":"string"}},"Confidence":{"type":"object","required":["score","level","reasons"],"properties":{"score":{"type":"number","minimum":0,"maximum":1},"level":{"enum":["high","medium","low"]},"reasons":{"type":"array","items":{"type":"string"}}}},"Source":{"type":"object","required":["source_id","publisher","url","license","retrieved_at"],"properties":{"source_id":{"type":"string"},"publisher":{"type":"string"},"url":{"type":"string","format":"uri"},"license":{"type":"string"},"retrieved_at":{"type":"string"},"quote":{"type":"string"},"quote_language":{"type":"string"},"source_value":{}}},"Fact":{"type":"object","required":["id","country","category","field","value","sources","last_verified","confidence"],"properties":{"id":{"type":"string"},"country":{"type":"string"},"category":{"type":"string"},"field":{"type":"string"},"value":{},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"cross_checks":{"type":"array","items":{"type":"object"}},"last_verified":{"type":"string","format":"date"},"next_review_due":{"type":"string","format":"date"},"confidence":{"$ref":"#/components/schemas/Confidence"},"attribution":{"type":"array","items":{"type":"string"}},"localization":{"type":"object"}}},"CategoryResponse":{"type":"object","properties":{"country":{"type":"object"},"category":{"type":"string"},"dataset_version":{"type":"string"},"data":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Fact"}},"attribution":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"}}},"EntryAnswer":{"type":"object","required":["status","quotes","confidence","official_links","advisory","decision_support_only"],"properties":{"status":{"enum":["visa_free","visa_required","visa_on_arrival","evisa_required","eta_required","unclear"]},"max_stay_days":{"type":["integer","null"]},"quotes":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"language":{"type":"string"},"authoritative":{"const":true},"translations":{"type":"object"}}}},"confidence":{"$ref":"#/components/schemas/Confidence"},"official_links":{"type":"array","items":{"type":"object"}},"advisory":{"type":"string"},"not_a_verdict":{"type":"string"},"decision_support_only":{"const":true}}}}}}