CitedTravel Meta API

openapi: 3.2.0
info:
  title: CitedTravel Meta 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: Meta
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/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:
                $ref: '#/components/schemas/ChangeFeed'
        '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'
  /mcp:
    post:
      tags:
      - Meta
      operationId: mcp
      summary: Remote MCP endpoint (Streamable HTTP, JSON-RPC 2.0)
      responses:
        '200':
          description: JSON-RPC response
components:
  schemas:
    ChangeFeed:
      type: object
      required:
      - since
      - data
      properties:
        since:
          type: string
          format: date
          description: Rows with changed_on on or after this date (inclusive).
        dataset_version:
          type: string
        data:
          type: array
          description: Changes, newest first.
          items:
            $ref: '#/components/schemas/Change'
    Problem:
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
    Change:
      type: object
      required:
      - fact_id
      - country
      - category
      - change
      - changed_on
      - detected_at
      properties:
        seq:
          type: integer
        dataset_version:
          type: string
          description: Dataset in which the change was detected.
        changed_on:
          type: string
          format: date
          description: When OUR pipeline detected the change (the dataset's build date), not when the rule took effect. Same value as detected_at; kept for compatibility.
        detected_at:
          type: string
          format: date
          description: When our pipeline detected the change (= changed_on). Not the date the rule took effect.
        effective_date:
          type:
          - string
          - 'null'
          format: date
          description: When the rule itself took effect, only if an official source states it; otherwise null.
        change_reason:
          type:
          - string
          - 'null'
          enum:
          - source_update
          - pipeline_fix
          - rule_change
          - new_coverage
          - null
          description: 'Why our data changed, when known: source_update = the cited official text changed; pipeline_fix = same official text, our extraction was corrected; rule_change = the source states a new rule (with effective_date); new_coverage = a fact we did not publish before; null = not determined.'
        fact_id:
          type: string
        country:
          type: string
        category:
          type: string
        change:
          type: string
          enum:
          - added
          - updated
          - removed
        old_value:
          description: Previous value (null when added).
        new_value:
          description: New value (null when removed).
        source_url:
          type:
          - string
          - 'null'
          description: Main source of the fact.
  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-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.