CitedTravel Billing API

openapi: 3.2.0
info:
  title: CitedTravel Billing 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: Billing
paths:
  /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
                newsletter:
                  type: boolean
                  default: false
                  description: 'Optional. true = also ask for the CitedTravel newsletter: we email a confirmation link (double opt-in) and send nothing else until it is clicked. Never required for a key.'
      responses:
        '201':
          description: Key created
        '400':
          $ref: '#/components/responses/Problem'
        '429':
          $ref: '#/components/responses/Problem'
  /v1/billing/portal:
    post:
      tags:
      - Billing
      operationId: createPortalSession
      summary: Open the Stripe customer portal for a paid key (manage or cancel the…
      security:
      - bearer: []
      - apiKey: []
      responses:
        '200':
          description: Portal URL
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
        '503':
          $ref: '#/components/responses/Problem'
  /v1/billing/checkout:
    post:
      tags:
      - Billing
      operationId: createCheckout
      summary: Start a Stripe Checkout session (Builder US$19/month or Pro US$99/month plus…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - plan
              - accept_terms
              properties:
                plan:
                  enum:
                  - builder
                  - pro
                email:
                  type: string
                  format: email
                accept_terms:
                  type: boolean
                  const: true
                  description: You confirm you are 18 or older, agree to the Terms of Service (/terms/) and the monthly automatic renewal, and have read the Privacy Notice (/privacy/).
                start_immediately:
                  type: boolean
                  description: Optional and currently ignored (the start-right-away request is not offered; a withdrawal within 14 days is refunded in full).
      responses:
        '200':
          description: Checkout URL
        '400':
          $ref: '#/components/responses/Problem'
        '503':
          $ref: '#/components/responses/Problem'
components:
  responses:
    Problem:
      description: RFC 9457 problem
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    Problem:
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
  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.