cruise-itinerary-com Cruise Itinerary Data API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data API
  version: 1.0.0
  summary: Cruise reference data, weekly fares, itineraries on the calendar, port traffic and a change feed.
  description: 'Reference data and weekly fare snapshots for cruise lines, ships, ports and sailings, refreshed every Monday. Fares are snapshots from an inventory feed, not live bookable prices. A null fare means the cabin is not offered or is sold out; the feed does not distinguish.


    **Authentication.** Send `Authorization: Bearer ` or `X-API-Key: `. Every endpoint needs a key, and a Free key costs nothing but an email address. A request without one gets 401 `key_required`. A malformed, unknown or revoked key is a 401, never a silent downgrade.


    **Plans.** Each endpoint lists the lowest plan that can call it in `x-required-plan`. Rate limits are per minute and some plans have a monthly call quota; both are reported in response headers. See /pricing for the current numbers.


    **Envelope.** Single objects come back as `{"data": {...}, "meta": {...}}`, lists as `{"data": [...], "meta": {as_of, page, per_page, total, has_more}}`, errors as `{"error": {status, code, message}}`. Every key is always present; absent values are null. Dates are YYYY-MM-DD. Money is whole US dollars.


    **Ids.** Lines, ships, ports, destinations, regions and cruises use slugs. Sailings use their integer id.


    **Caching.** Anonymous responses from open endpoints are cacheable for an hour and carry an ETag. Everything keyed is `private, no-store`.


    **Counting.** A keyed request that returns 2xx counts toward the monthly quota; errors do not.'
  termsOfService: https://cruise-itinerary.com/terms
  contact:
    name: Cruise Itinerary
    url: https://cruise-itinerary.com
servers:
- url: https://cruise-itinerary.com
  description: Production
security:
- {}
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Cruise Itinerary Data API
paths: {}
webhooks:
  changes.batch:
    post:
      summary: Change events after a weekly load
      operationId: webhookChangesBatch
      x-required-plan: business
      description: 'Business plans and above can subscribe an HTTPS URL from the dashboard, with optional kind, ship, line and port filters. After each weekly load we POST the matching change events, up to 1,000 per delivery (`page` of `pages`). Respond with any 2xx within 10 seconds. Otherwise we retry after 5 minutes, 30 minutes, 2, 6, 12 and 24 hours, and 24 hours again (8 attempts), then mark the delivery failed; an endpoint with 20 consecutive failed deliveries is disabled. URLs that resolve to private, loopback or link-local addresses are refused.


        `X-CI-Signature: t=,v1=` where `v1 = HMAC_SHA256(secret, ".")`, hex encoded, using the endpoint secret shown in the dashboard. Reject requests whose timestamp is far from your clock. The dashboard''s "send test" delivers a `ping` with an empty `events` list.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookBatch'
            example:
              id: 1
              type: changes.batch
              detected_on: '2026-09-28'
              previous_on: '2026-09-21'
              page: 1
              pages: 1
              events:
              - id: 813554
                detected_on: '2026-10-19'
                previous_on: '2026-10-12'
                kind: price_drop
                sailing_id: 14026501
                cruise_id: 21-night-panama-canal-nieuw-amsterdam-6d1d00
                previous_cruise_id: null
                ship:
                  id: nieuw-amsterdam
                  name: Nieuw Amsterdam
                line:
                  id: holland-america-line
                  name: Holland America Line
                departure_date: '2027-04-11'
                cabin: inside
                old_value: 2199
                new_value: 2099
                currency: USD
      responses:
        2XX:
          description: Delivered.
      tags:
      - Cruise Itinerary Data API
components:
  schemas:
    Ref:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
      required:
      - id
      - name
      additionalProperties: false
    WebhookBatch:
      type: object
      properties:
        id:
          type: integer
          description: Delivery id; the same on every retry of this delivery.
        type:
          type: string
          enum:
          - changes.batch
          - ping
        detected_on:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        previous_on:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        page:
          type: integer
        pages:
          type: integer
          description: Deliveries for this load; each holds up to 1,000 events.
        events:
          type: array
          items:
            $ref: '#/components/schemas/ChangeEvent'
      required:
      - id
      - type
      - detected_on
      - previous_on
      - page
      - pages
      - events
      additionalProperties: false
    ChangeEvent:
      type: object
      properties:
        id:
          type: integer
        detected_on:
          type: string
          description: Load that revealed the change.
          format: date
        previous_on:
          type: string
          description: Load it was compared against.
          format: date
        kind:
          type: string
          description: '`schedule_changed`: the sailing''s route is the same but port days moved, were added or removed, or estimated days were confirmed by the line''s own itinerary; re-fetch the sailing for its new days. It covers every rebuild of the day-by-day itineraries since the previous load, nightly ones included.'
          enum:
          - price_drop
          - price_rise
          - cabin_unavailable
          - cabin_available
          - sailing_added
          - sailing_removed
          - itinerary_changed
          - schedule_changed
        sailing_id:
          type: integer
        cruise_id:
          oneOf:
          - type: string
            description: Cruise slug.
          - type: 'null'
        previous_cruise_id:
          oneOf:
          - type: string
            description: 'For itinerary_changed: the cruise it replaced.'
          - type: 'null'
        ship:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        line:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        departure_date:
          type: string
          format: date
        cabin:
          oneOf:
          - type: string
            enum:
            - inside
            - outside
            - balcony
            - suite
          - type: 'null'
        old_value:
          oneOf:
          - type: integer
            description: 'Fare before, USD. For schedule_changed: port days whose date moved, or that were added or removed.'
          - type: 'null'
        new_value:
          oneOf:
          - type: integer
            description: 'Fare after, USD. For schedule_changed: estimated days now exact.'
          - type: 'null'
        currency:
          type: string
          enum:
          - USD
      required:
      - id
      - detected_on
      - previous_on
      - kind
      - sailing_id
      - cruise_id
      - previous_cruise_id
      - ship
      - line
      - departure_date
      - cabin
      - old_value
      - new_value
      - currency
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Key from the dashboard: ci_live_ followed by 32 letters and digits.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same key, as a header.