---
title: "Refine Flight Guide Inventory"
method: POST
path: "/conv/trips/{trip_id}/flight-guide/{source_frame_id}/refine"
tags: ["conversational"]
---

# Refine Flight Guide Inventory

`POST /conv/trips/{trip_id}/flight-guide/{source_frame_id}/refine`

Proxy typed Guide filters without accepting browser-owned candidates.

## Path parameters

- `trip_id` string, required
- `source_frame_id` string, required

## Request body

- FlightGuideRefinementRequest
  - `cursor` integer
  - `refinement` FlightGuideRefinement — Server-resolved filters for one canonical Flight Guide frame. The browser supplies preferences, never candidate inventory. Brain applies these constraints to the persisted outbound frame and the complete cached Phase-2 return market, selecting at most one checkout observation per outbound.
    - `nonstop_only` boolean
    - `airline_only` string, nullable
    - `avoided_airlines` string[]
    - `origin_airport_codes` string[], nullable
    - `destination_airport_codes` string[], nullable
    - `outbound_depart_after_minutes` integer, nullable
    - `outbound_depart_before_minutes` integer, nullable
    - `return_depart_after_minutes` integer, nullable
    - `return_depart_before_minutes` integer, nullable
  - `retry_failed` boolean

## Response `200`

Successful Response

- FlightGuideRefinementResponse — One stable refinement page over complete checkout observations. ``complete`` is true only on the final provider page after every outbound in that page has a conclusive cached Phase-2 result. Callers must not claim zero matches or a +/- fare impact before it becomes true.
  - `source_frame_id` string, required
  - `cursor` integer, required
  - `next_cursor` integer, nullable
  - `pending_outbounds` integer, required
  - `failed_outbounds` integer — Return pairings that exhausted automatic provider retries.
  - `complete` boolean, required
  - `refinement` FlightGuideRefinement, required — Server-resolved filters for one canonical Flight Guide frame. The browser supplies preferences, never candidate inventory. Brain applies these constraints to the persisted outbound frame and the complete cached Phase-2 return market, selecting at most one checkout observation per outbound.
    - `nonstop_only` boolean
    - `airline_only` string, nullable
    - `avoided_airlines` string[]
    - `origin_airport_codes` string[], nullable
    - `destination_airport_codes` string[], nullable
    - `outbound_depart_after_minutes` integer, nullable
    - `outbound_depart_before_minutes` integer, nullable
    - `return_depart_after_minutes` integer, nullable
    - `return_depart_before_minutes` integer, nullable
  - `results` object[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/helloaxel/apis/client-api-gateway.md) · [All operations](https://skmtc.dev/helloaxel/apis/client-api-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/helloaxel/client-api-gateway/revisions/d3c4c29fede7/schema)