CitedTravel Entry API

openapi: 3.2.0
info:
  title: CitedTravel Entry 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}`.


    **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.


    **Entry requirements** are a pilot (GB, US, JP passports) and decision support only: every answer has an `advisory`, `official_links` and `not_a_verdict`.


    **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 US$19/month and Pro US$99/month plus any tax, monthly subscriptions sold through Link (Stripe) as merchant of record, renewing until cancelled (`POST /v1/billing/checkout`; manage or cancel at https://citedtravel.com/account/ or `POST /v1/billing/portal`; paid plans aren''t available in every country, see https://citedtravel.com/terms/#6-subscriptions). Agents may instead pay per call with x402 v2 (`PAYMENT-SIGNATURE` header; USDC on Base mainnet; payments are final).


    **Disclaimer:** informational only; not legal or immigration advice. See https://citedtravel.com/disclaimer/.'
  termsOfService: https://citedtravel.com/terms/
  contact:
    name: CitedTravel
    url: https://citedtravel.com/support/
    email: support@citedtravel.com
  license:
    name: 'Data: per-fact source licenses (see attribution field)'
    url: https://citedtravel.com/docs/#licensing
  x-guidance: Without an API key, GET /v1/entry ($0.01) and GET /v1/trip-brief ($0.02) answer 402 with an x402 v2 PAYMENT-REQUIRED header (USDC). Retry with PAYMENT-SIGNATURE. Static fact routes are free without a key up to 60 requests/min/IP and cost $0.005 per call beyond that. Always show the advisory and official_links from entry answers; they are decision support, never a go/no-go verdict. Settled payments are final.
servers:
- url: https://citedtravel.com
security:
- {}
- bearer: []
- apiKey: []
tags:
- name: entry
paths:
  /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)
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.010000'
        protocols:
        - x402: {}
  /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)
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.020000'
        protocols:
        - x402: {}
components:
  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.
  schemas:
    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
    EntryAnswer:
      type: object
      required:
      - status
      - quotes
      - confidence
      - official_links
      - advisory
      - decision_support_only
      properties:
        status:
          enum:
          - visa_free
          - visa_free_with_requirements
          - visa_required
          - visa_on_arrival
          - evisa_required
          - eta_required
          - unclear
          description: 'visa_free_with_requirements: no visa, but the cited source requires another formality (pre-arrival registration, digital arrival card, tourist card); see additional_requirements. A required electronic travel authorisation is eta_required.'
        prior_application_needed:
          type:
          - boolean
          - 'null'
        additional_requirements:
          type: array
          description: Formalities beyond the visa status, each quoted verbatim from the official source. Never treat a route as plain visa-free when this lists a 'required' item.
          items:
            type: object
            required:
            - type
            - description
            - certainty
            - quote
            - source_url
            properties:
              type:
                enum:
                - travel_authorisation
                - pre_arrival_registration
                - arrival_card
                - tourist_card
                - evisa
                - health_insurance
              description:
                type: string
              certainty:
                enum:
                - required
                - check_official
                description: 'required: the quoted sentence says it is needed. check_official: mentioned conditionally, waived for this passport, or in conflict with the status; confirm on the official page.'
              quote:
                type: string
              source_id:
                type: string
              source_url:
                type: string
                format: uri
        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
    Problem:
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
  headers:
    RateLimit-Reset:
      schema:
        type: integer
      description: Seconds until reset
    RateLimit-Remaining:
      schema:
        type: integer
    RateLimit-Limit:
      schema:
        type: integer
  responses:
    PaymentRequired:
      description: 'x402 v2: payment required (PAYMENT-REQUIRED header, base64 JSON)'
      headers:
        PAYMENT-REQUIRED:
          schema:
            type: string
      content:
        application/json:
          schema:
            type: object
    Problem:
      description: RFC 9457 problem
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  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.