---
title: "B2B Nl Query"
method: POST
path: "/api/v1/b2b/planner/query"
tags: ["b2b"]
---

# B2B Nl Query

`POST /api/v1/b2b/planner/query`

## Request

- Base URL: `https://yondry.app` (the document declares no server; this is the origin it was published from)
- URL: `https://yondry.app/api/v1/b2b/planner/query`
- Auth: API key in header `X-API-Key`

Natural-language planner for B2B callers.

No end-user account required — the caller supplies a lat/lon instead of a
user JWT. The planner uses Google Places gap-fill to source nearby
attractions (the same mechanism used when a registered user's library is
sparse in the requested area).

Returns 429 when the tenant's monthly plan cap is exceeded.

## Request body

- B2BPlannerRequest: Request body for POST /b2b/planner/query.
  - `query` string, required
  - `lat` number, required
  - `lon` number, required
  - `radius_km` number
  - `travel_mode` string
  - `companion` string
  - `vibes` string[]
  - `language` string

## Response `201`

Successful Response

- B2BPlannerResponse: Response for POST /b2b/planner/query.
  - `query` string, required
  - `intent` PlannerIntent, required: Structured intent extracted from a free-text query by Claude Haiku.
    - `moods` string[]
    - `place_types` string[]
    - `duration_hours` number, nullable
    - `companions` string[]
    - `time_of_day` string, nullable
    - `budget` string, nullable
    - `excluded_place_types` string[]
    - `prefer_discovery` boolean
    - `vibe_conflicts` string[]
    - `planning_mode` union
      - 'local' | 'known_day_trip' | 'discovery_day_trip' | 'away_trip'
      - string
    - `destination` string, nullable
    - `discovery_constraints` DiscoveryConstraints: Spatial/vibe constraints when the user wants us to find a destination.
      - `max_travel_minutes` integer, required
      - `vibe_keywords` string[]
      - `must_haves` string[]
      - `exclusions` string[]
    - `start_location_type` union
      - 'home' | 'custom' | 'current_location' | 'future_location'
      - string
    - `arrival_transport` string, nullable
    - `local_transport` string, nullable
    - `duration_minutes` integer, nullable
    - `start_time` string, date-time, nullable
    - `must_include_meal` boolean
    - `constraints_inferred` string[]
    - `ambiguity_flags` string[]
    - `first_time_visitor` boolean, nullable
    - `named_landmarks` string[]
  - `plans` Plan[], required
    - `label` string, required
    - `stops` PlanStop[], required
      - `place_id` string, nullable
      - `name` string, required
      - `category` string, required
      - `why` string, required
      - `suggested_duration_minutes` integer, required
      - `is_discovery` boolean
      - `is_meal` boolean
      - `lat` number, nullable
      - `lng` number, nullable
      - `admission_price` string, nullable
      - `alternative_stops` AlternativeStop[]
        - `name` string, required
        - `category` string, required
        - `why` string, required
      - `travel_leg` TravelLegOut
        - `from_stop` string, required
        - `to_stop` string, required
        - `distance_km` number, required
        - `travel_mins` integer, required
        - `travel_mode` string, required
      - `arrival_time` string, date-time, nullable
      - `transition_to_next` TransitionSegment: Travel segment between two consecutive stops within the zone.
        - `mode` string, required
        - `minutes` integer, required
        - `distance_km` number, required
        - `is_estimated` boolean
    - `summary` string, required
    - `conflicts` PlanningConflictOut[]
      - `type` string, required
      - `stop_name` string, required
      - `detail` string, required
      - `suggestion` string, required
    - `total_duration_mins` integer, nullable
    - `plan_notes` string
    - `arrival_segment` JourneySegment: Arrival or return leg between the user's start location and the destination zone.
      - `from_location` string, required
      - `to_location` string, required
      - `mode` string, required
      - `minutes` integer, required
      - `depart_time` string, date-time, required
    - `return_segment` JourneySegment: Arrival or return leg between the user's start location and the destination zone.
      - `from_location` string, required
      - `to_location` string, required
      - `mode` string, required
      - `minutes` integer, required
      - `depart_time` string, date-time, required
    - `buffer_minutes` integer
    - `travel_note` string
  - `weather` string, nullable, required
  - `generated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/yondry/apis/yondry-api.md) · [All operations](https://skmtc.dev/yondry/apis/yondry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yondry/apis/yondry-api/revisions/d2c213cea95b?raw)