> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# price-monitoring

> Monitor price for a specific origin, destination, and dates pair

Watch a specific route and date pair over time so an agent can act when the fare drops. Use it for prompts like "alert me when Paris to New York for June 17 to 26 goes under €400". Each response includes the current cheapest cached fare and an offer token you can pass to flight\_search when the user decides to book. Cache-only; never triggers a live call.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/price_monitoring
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.1.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.


    ### Per-end-user attribution


    On booking calls you may send an optional `X-End-User-Id` request header to
    attribute the booking to one of your own end users (for per-end-user
    attribution and rate-limiting). The value is an **opaque, tenant-scoped**
    identifier that you choose — not a Jinko account id. Omit it to book as the
    tenant. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected.
servers: []
security: []
paths:
  /v1/price_monitoring:
    post:
      tags:
        - Discovery
      summary: Monitor price for a specific origin, destination, and dates pair
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceMonitoringRequest'
      responses:
        '200':
          description: Cheapest cached itinerary, or stale on a cache miss
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceMonitoringResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: Malformed JSON in request body.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_REQUIRED
                  message: Invalid or expired API key.
                  doc_url: https://docs.gojinko.com/api-reference/authentication
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: >-
                    origins: origins is required; trip_type: trip_type is
                    required
                  doc_url: https://docs.gojinko.com/concepts/errors
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Rate limit or quota exceeded.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '502':
          description: Upstream service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_ERROR
                  message: Upstream travel provider returned an error. Please retry.
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    PriceMonitoringRequest:
      type: object
      properties:
        origin:
          type: string
          example: PAR
        destination:
          type: string
          example: NYC
        departure_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        return_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        origin_type:
          type: string
          enum:
            - city
            - airport
        destination_type:
          type: string
          enum:
            - city
            - airport
        cabin_class:
          type: string
          enum:
            - economy
            - premium_economy
            - business
            - first
        direct_only:
          type: boolean
        max_price:
          type: number
          minimum: 0
          exclusiveMinimum: true
        include_carriers:
          type: array
          items:
            type: string
        exclude_carriers:
          type: array
          items:
            type: string
        adults:
          type: integer
          minimum: 1
          default: 1
        children:
          type: integer
          minimum: 0
        infants:
          type: integer
          minimum: 0
        currency:
          type: string
        locale:
          type: string
        intent:
          $ref: '#/components/schemas/IntentInput'
      required:
        - origin
        - destination
        - departure_date
    PriceMonitoringResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        monitored_at:
          type: string
          example: '2026-06-01T12:34:56Z'
        flight:
          $ref: '#/components/schemas/MonitoredFlight'
        request_echo:
          nullable: true
      required:
        - status
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    IntentInput:
      type: object
      properties:
        user_intent:
          type: string
          nullable: true
          description: >-
            The user's natural-language intent: the Alpic PII-stripped
            paraphrase when available, else a best-effort fallback to the
            client-provided NL query.
          example: find a cheap flight to Tokyo
    MonitoredFlight:
      type: object
      properties:
        offer_token:
          type: string
          example: oft_7c2e9a1b4d
        total_price:
          $ref: '#/components/schemas/MonitoredMoney'
        outbound_carrier:
          $ref: '#/components/schemas/MonitoredCarrier'
        inbound_carrier:
          $ref: '#/components/schemas/MonitoredCarrier'
        outbound_stops:
          type: number
          example: 0
        inbound_stops:
          type: number
          example: 1
        outbound_duration_minutes:
          type: number
          example: 470
        inbound_duration_minutes:
          type: number
          example: 520
        outbound_departure_local:
          type: string
          example: '2026-07-15T10:15:00'
        outbound_arrival_local:
          type: string
          example: '2026-07-15T13:05:00'
        inbound_departure_local:
          type: string
          example: '2026-07-22T17:40:00'
        inbound_arrival_local:
          type: string
          example: '2026-07-23T07:25:00'
        cabin_class:
          type: string
          example: economy
        fare_brand:
          type: string
          example: Main
    MonitoredMoney:
      type: object
      properties:
        amount:
          type: number
          description: >-
            Alternative to `value` on some endpoints (the two never appear
            together); its scale depends on decimal_places. When this object
            carries decimal_places, amount is an INTEGER in minor units — divide
            by 10 ** decimal_places (e.g. select_ancillaries
            total_with_ancillaries). When there is no decimal_places field,
            amount is a decimal in MAJOR units, safe to display as-is (e.g. trip
            and checkout totals).
        value:
          type: integer
          description: >-
            Integer amount in MINOR units, always paired with decimal_places —
            divide by 10 ** decimal_places to display. Example: value 15977 with
            decimal_places 2 is 159.77 USD. Rendering this field directly shows
            prices 100x too high for 2-decimal currencies.
          example: 41250
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        decimal_places:
          type: integer
          description: >-
            Scale of the integer value/amount: display = integer / 10 **
            decimal_places. Always sent alongside minor-unit amounts. Usually
            the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for
            JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry
            a different scale — ALWAYS use the decimal_places sent with the
            amount, never a hardcoded 2. Only if the field is genuinely absent
            on a value-shaped object, fall back to the ISO digits for the
            currency.
          example: 2
    MonitoredCarrier:
      type: object
      properties:
        code:
          type: string
          example: DL
        name:
          type: string
          example: Delta Air Lines
        flight_number:
          type: string
          example: DL263
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````