> ## 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. # flight-price-advice > Accept a flight with its current price for price advice This endpoint is in preview. Contact support to request access. It accepts a flight with its current price and returns schema 3.2 price advice. Available results compare the fare with typical fares for comparable flights and provide fixed 1-day and 3-day price forecasts, each with a forecasted price and estimated probabilities of an increase, decrease, or no change. Initial numeric coverage is one-adult, one-way, nonstop, USD; other structurally valid inputs return a reasoned unavailable result. The deterministic summary can be displayed without an LLM. The endpoint requires a verified jnk\_ API key and does not search, monitor, quote, or book flights. ## OpenAPI ````yaml api-reference/public-api-dev.yaml POST /v1/flight_price_advice openapi: 3.0.0 info: title: Jinko Public API version: 0.23.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: - url: https://api.dev.gojinko.com description: Development preview security: [] paths: /v1/flight_price_advice: post: tags: - Discovery summary: Accept a flight with its current price for price advice description: >- This endpoint is in preview. Contact support to request access. It accepts a flight with its current price and returns schema 3.2 price advice. Available results compare the fare with typical fares for comparable flights and provide fixed 1-day and 3-day price forecasts, each with a forecasted price and estimated probabilities of an increase, decrease, or no change. Initial numeric coverage is one-adult, one-way, nonstop, USD; other structurally valid inputs return a reasoned unavailable result. The deterministic summary can be displayed without an LLM. The endpoint requires a verified jnk_ API key and does not search, monitor, quote, or book flights. requestBody: content: application/json: schema: $ref: '#/components/schemas/FlightPriceAdviceRequest' responses: '200': description: >- Computed flight price advice or a reasoned unavailable/not-ready result content: application/json: schema: $ref: '#/components/schemas/FlightPriceAdviceResponse' '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/authentication/api-keys '402': description: Payment required — organization balance exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PAYMENT_REQUIRED message: >- Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup doc_url: https://docs.gojinko.com/concepts/errors '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: A required field is missing or invalid. 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: The travel provider rejected the request, or an upstream call failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_REJECTED message: The upstream service rejected the request. doc_url: https://docs.gojinko.com/concepts/errors '503': description: No travel provider can serve the request right now headers: Retry-After: description: >- Seconds to wait before retrying, forwarded verbatim from the upstream service. Absent when the upstream named no interval. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_UNAVAILABLE message: >- The upstream service is temporarily unavailable. Please retry later. doc_url: https://docs.gojinko.com/concepts/errors '504': description: The travel provider did not answer in time content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_TIMEOUT message: The upstream service did not respond in time. doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: FlightPriceAdviceRequest: type: object properties: origin: type: string pattern: ^[A-Z]{3}$ example: NYC destination: type: string pattern: ^[A-Z]{3}$ example: LAX departure_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-10-20' trip_type: type: string enum: - oneway - roundtrip stops: type: number description: >- Actual number of flight connections: 0 for nonstop, 1, or 2. Omit when unknown. enum: - 0 - 1 - 2 cabin_class: type: string enum: - economy - premium_economy - business - first current_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' required: - origin - destination - departure_date - trip_type - cabin_class - current_price additionalProperties: false description: >- DEV contract preview input. Structural trip type, optional actual connection count, and cabin values are validated; this preview does not imply statistics coverage. FlightPriceAdviceResponse: type: object properties: schema_version: type: string enum: - '3.2' status: type: string enum: - available - partial - unavailable - not_ready reason: type: string nullable: true enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable summary: type: string minLength: 1 context: $ref: '#/components/schemas/FlightPriceAdviceContext' price_assessment: oneOf: - type: object properties: status: type: string enum: - available reason_code: nullable: true label: type: string enum: - low - typical - high typical_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' typical_range: type: object properties: low: $ref: '#/components/schemas/FlightPriceAdviceAmount' high: $ref: '#/components/schemas/FlightPriceAdviceAmount' required: - low - high additionalProperties: false percentile: type: number minimum: 0 maximum: 100 difference_pct: type: number comparison_basis: type: string enum: - historical_comparable_low_fares evidence: type: object properties: artifact_id: type: string pattern: ^price-advice-v1-[a-f0-9]{64}$ fit_window: type: object properties: start: type: string format: date-time end_exclusive: type: string format: date-time required: - start - end_exclusive additionalProperties: false source_price_unit: type: string enum: - amd_totalpricenuc_millicents currency_mapping: type: string enum: - >- gateway_platform_usd_millicents_to_usd_minor_units_divide_by_10 apex_band: type: string enum: - 0-2 - 3-6 - 7-13 - 14-20 - 21-29 - 30-59 - 60-89 - 90-179 - '>=180' support: type: object properties: daily_units: type: integer minimum: 0 exclusiveMinimum: true observation_days: type: integer minimum: 0 exclusiveMinimum: true departure_dates: type: integer minimum: 0 exclusiveMinimum: true flight_identities: type: integer minimum: 0 exclusiveMinimum: true required: - daily_units - observation_days - departure_dates - flight_identities additionalProperties: false required: - artifact_id - fit_window - source_price_unit - currency_mapping - apex_band - support additionalProperties: false required: - status - reason_code - label - typical_price - typical_range - percentile - difference_pct - comparison_basis - evidence additionalProperties: false - type: object properties: status: type: string enum: - unavailable reason_code: type: string enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable label: nullable: true typical_price: nullable: true typical_range: nullable: true percentile: nullable: true difference_pct: nullable: true comparison_basis: type: string enum: - historical_comparable_low_fares evidence: nullable: true required: - status - reason_code - label - typical_price - typical_range - percentile - difference_pct - comparison_basis - evidence additionalProperties: false wait_assessment: anyOf: - type: object properties: status: type: string enum: - available reason_code: nullable: true horizons: type: array items: anyOf: - type: object properties: horizon_days: type: number enum: - 1 status: type: string enum: - available reason_code: nullable: true direction: type: string enum: - increase - decrease - unchanged - mixed forecasted_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' probabilities: type: object properties: increase: type: number minimum: 0 maximum: 1 decrease: type: number minimum: 0 maximum: 1 unchanged: type: number minimum: 0 maximum: 1 required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false - type: object properties: horizon_days: type: number enum: - 3 status: type: string enum: - available reason_code: nullable: true direction: type: string enum: - increase - decrease - unchanged - mixed forecasted_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' probabilities: type: object properties: increase: type: number minimum: 0 maximum: 1 decrease: type: number minimum: 0 maximum: 1 unchanged: type: number minimum: 0 maximum: 1 required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false minItems: 2 maxItems: 2 required: - status - reason_code - horizons additionalProperties: false - type: object properties: status: type: string enum: - partial reason_code: type: string enum: - partial_statistics horizons: anyOf: - type: array items: anyOf: - type: object properties: horizon_days: type: number enum: - 1 status: type: string enum: - available reason_code: nullable: true direction: type: string enum: - increase - decrease - unchanged - mixed forecasted_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' probabilities: type: object properties: increase: type: number minimum: 0 maximum: 1 decrease: type: number minimum: 0 maximum: 1 unchanged: type: number minimum: 0 maximum: 1 required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false - type: object properties: horizon_days: type: number enum: - 3 status: type: string enum: - unavailable reason_code: type: string enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable direction: nullable: true forecasted_price: type: number nullable: true not: type: number probabilities: type: object properties: increase: nullable: true decrease: nullable: true unchanged: nullable: true required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false minItems: 2 maxItems: 2 - type: array items: anyOf: - type: object properties: horizon_days: type: number enum: - 1 status: type: string enum: - unavailable reason_code: type: string enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable direction: nullable: true forecasted_price: type: number nullable: true not: type: number probabilities: type: object properties: increase: nullable: true decrease: nullable: true unchanged: nullable: true required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false - type: object properties: horizon_days: type: number enum: - 3 status: type: string enum: - available reason_code: nullable: true direction: type: string enum: - increase - decrease - unchanged - mixed forecasted_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' probabilities: type: object properties: increase: type: number minimum: 0 maximum: 1 decrease: type: number minimum: 0 maximum: 1 unchanged: type: number minimum: 0 maximum: 1 required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false minItems: 2 maxItems: 2 required: - status - reason_code - horizons additionalProperties: false - type: object properties: status: type: string enum: - unavailable reason_code: type: string enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable horizons: type: array items: anyOf: - type: object properties: horizon_days: type: number enum: - 1 status: type: string enum: - unavailable reason_code: type: string enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable direction: nullable: true forecasted_price: type: number nullable: true not: type: number probabilities: type: object properties: increase: nullable: true decrease: nullable: true unchanged: nullable: true required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false - type: object properties: horizon_days: type: number enum: - 3 status: type: string enum: - unavailable reason_code: type: string enum: - statistics_not_ready - future_statistics - stale_statistics - unsupported_currency - unsupported_trip_type - stops_unknown - unsupported_stops - route_not_covered - insufficient_data - horizon_not_supported - unsafe_projected_amount - request_cancelled - partial_statistics - statistics_unavailable direction: nullable: true forecasted_price: type: number nullable: true not: type: number probabilities: type: object properties: increase: nullable: true decrease: nullable: true unchanged: nullable: true required: - increase - decrease - unchanged additionalProperties: false required: - horizon_days - status - reason_code - direction - forecasted_price - probabilities additionalProperties: false minItems: 2 maxItems: 2 required: - status - reason_code - horizons additionalProperties: false recommendation: anyOf: - type: object properties: action: type: string enum: - buy_now - wait basis: oneOf: - $ref: >- #/components/schemas/FlightPriceAdviceExpectedFareRecommendationBasis - $ref: >- #/components/schemas/FlightPriceAdviceModalDirectionRecommendationBasis discriminator: propertyName: policy mapping: expected_fare: $ref: >- #/components/schemas/FlightPriceAdviceExpectedFareRecommendationBasis modal_direction: $ref: >- #/components/schemas/FlightPriceAdviceModalDirectionRecommendationBasis summary: type: string minLength: 1 required: - action - basis - summary additionalProperties: false - type: object properties: action: type: string enum: - no_clear_signal basis: type: object nullable: true oneOf: - $ref: >- #/components/schemas/FlightPriceAdviceExpectedFareRecommendationBasis - $ref: >- #/components/schemas/FlightPriceAdviceModalDirectionRecommendationBasis - type: number nullable: true not: type: number summary: type: string minLength: 1 required: - action - basis - summary additionalProperties: false live_quotes_used: type: boolean enum: - false required: - schema_version - status - reason - summary - context - price_assessment - wait_assessment - recommendation - live_quotes_used additionalProperties: false description: >- Schema 3.2 price advice. Results may be available, partial, unavailable, or not ready; fixed 1-day and 3-day horizons are always present. ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - credential_format_invalid - payment_type_not_enabled - payment_credential_invalid - trip_owned_by_other_payment - idempotency_key_reused - attempt_in_progress - quote_expired - attempt_terminal - temporarily_unavailable - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - INVALID_PHONE_NUMBER - CURRENCY_UNSUPPORTED - HOTEL_NAME_LOW_CONFIDENCE - DESTINATION_LOW_CONFIDENCE - UPSTREAM_REJECTED - UPSTREAM_UNAVAILABLE - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - INTERNAL description: >- What went wrong, as a stable machine-readable code. This is a closed set — branch on it rather than on `message`, which is prose and may change. New codes arrive in a minor version, so treat an unknown one as its HTTP status. A code can also stop being emitted: it leaves this set in a minor version, named in the changelog, and a branch you wrote for it goes unreached rather than wrong. example: BAD_REQUEST message: type: string doc_url: type: string required: - code - message required: - error FlightPriceAdviceAmount: type: object properties: value: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Positive integer in currency minor units. example: 32000 currency: type: string pattern: ^[A-Z]{3}$ example: USD decimal_places: type: integer minimum: 0 example: 2 required: - value - currency - decimal_places additionalProperties: false description: >- One adult total fare for the supplied trip, including tax and excluding optional paid extras. Value 32000, USD, decimal_places 2 means USD 320.00. FlightPriceAdviceContext: type: object properties: origin: type: string pattern: ^[A-Z]{3}$ example: NYC destination: type: string pattern: ^[A-Z]{3}$ example: LAX departure_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-10-20' trip_type: type: string enum: - oneway - roundtrip stops: type: number description: >- Actual number of flight connections, or null when the request omitted stops. nullable: true anyOf: - type: number enum: - 0 - 1 - 2 - not: type: number cabin_class: type: string enum: - economy - premium_economy - business - first current_price: $ref: '#/components/schemas/FlightPriceAdviceAmount' price_basis: type: string enum: - per_adult_total_including_tax evaluated_at: type: string format: date-time apex_days: type: integer minimum: 0 exclusiveMinimum: true required: - origin - destination - departure_date - trip_type - stops - cabin_class - current_price - price_basis - evaluated_at - apex_days additionalProperties: false FlightPriceAdviceExpectedFareRecommendationBasis: type: object properties: policy: type: string enum: - expected_fare price_label: type: string enum: - low - typical - high selected_horizon_days: anyOf: - type: number enum: - 1 - type: number enum: - 3 wait_direction: type: string enum: - increase - decrease - unchanged required: - policy - price_label - selected_horizon_days - wait_direction additionalProperties: false FlightPriceAdviceModalDirectionRecommendationBasis: type: object properties: policy: type: string enum: - modal_direction price_label: type: string enum: - low - typical - high selected_horizon_days: type: number nullable: true not: type: number wait_direction: type: string enum: - increase - decrease required: - policy - price_label - selected_horizon_days - wait_direction additionalProperties: false securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.