> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.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.
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
          example: 289.99
        value:
          type: number
        currency:
          type: string
          example: USD
        decimal_places:
          type: integer
          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

````