> ## Documentation Index > Fetch the complete documentation index at: https://docs.prexsell.com/llms.txt > Use this file to discover all available pages before exploring further. # Search bookable offers > Returns bookable offers for the given city pair, date, and passenger count. Authenticated via the api-key header; data scoped to the caller's partner. Offer ids are 20-minute signed JWT booking tokens — use expiresAt to detect expiry before attempting to book. ## OpenAPI ````yaml /docs/openapi/openapi.json get /v2/offers openapi: 3.1.0 info: title: PREXSELL REST v2 version: 5.97.1 description: REST API for the PREXSELL bus booking management platform. servers: - url: https://staging.api.prexsell.com description: Staging - url: https://api.prexsell.com description: Production security: [] paths: /v2/offers: get: tags: - Offers summary: Search bookable offers description: >- Returns bookable offers for the given city pair, date, and passenger count. Authenticated via the api-key header; data scoped to the caller's partner. Offer ids are 20-minute signed JWT booking tokens — use expiresAt to detect expiry before attempting to book. operationId: searchOffers parameters: - schema: type: string minLength: 1 description: URL-friendly slug of the departure city. example: kyiv required: false description: URL-friendly slug of the departure city. name: departureCitySlug in: query - schema: type: string minLength: 1 description: URL-friendly slug of the arrival city. example: warsaw required: false description: URL-friendly slug of the arrival city. name: arrivalCitySlug in: query - schema: type: string minLength: 1 description: >- Database ID of the departure city. Use slug addressing where possible; id addressing is kept pending Moesif usage analysis (ADR-0033 §7). example: city-abc123 required: false description: >- Database ID of the departure city. Use slug addressing where possible; id addressing is kept pending Moesif usage analysis (ADR-0033 §7). name: departureCityId in: query - schema: type: string minLength: 1 description: >- Database ID of the arrival city. Use slug addressing where possible; id addressing is kept pending Moesif usage analysis (ADR-0033 §7). example: city-def456 required: false description: >- Database ID of the arrival city. Use slug addressing where possible; id addressing is kept pending Moesif usage analysis (ADR-0033 §7). name: arrivalCityId in: query - schema: type: string format: date description: >- Departure date in ISO 8601 format (YYYY-MM-DD). Garbage values yield 400. example: '2026-06-15' required: true description: >- Departure date in ISO 8601 format (YYYY-MM-DD). Garbage values yield 400. name: departureDate in: query - schema: type: integer minimum: 1 description: >- Number of passengers (renamed from legacy passengersQty). Minimum 1. example: 2 required: true description: Number of passengers (renamed from legacy passengersQty). Minimum 1. name: passengers in: query responses: '200': description: Offer search results. content: application/json: schema: type: object properties: data: type: object properties: offers: type: array items: type: object properties: id: type: string description: >- Offer id — a 20-minute signed JWT booking token. Pass as offerId when creating a booking. Expired at expiresAt. example: eyJhbGciOiJIUzI1NiJ9... source: type: string description: Data source. example: PrexSell seatsLeft: type: - number - 'null' description: Seats remaining. example: 12 arrivalDate: type: - string - 'null' description: Arrival datetime ISO 8601. example: '2026-06-15T08:00:00.000Z' expiresAt: type: - string - 'null' description: >- ISO 8601 datetime at which this offer token expires (decoded from the JWT exp claim; per-offer exact). Booking an expired token yields 400 OFFER_EXPIRED. Null when the claim is undecodable. example: '2026-06-14T00:20:00.000Z' prices: type: array items: type: object properties: id: type: string amount: description: Price amount (numeric). example: 1450 currency: type: string enum: - CZK - UAH - EUR - USD - PLN description: Price currency. example: UAH required: - id - currency description: Price option for this offer. description: Available prices for this offer. slices: type: array items: type: object properties: id: type: - string - 'null' description: Slice segment ID. example: seg-123 duration: type: - number - 'null' description: Journey duration in minutes. example: 480 arrivalDate: type: - string - 'null' description: Arrival datetime ISO 8601. example: '2026-06-15T08:00:00.000Z' departureDate: type: - string - 'null' description: Departure datetime ISO 8601. example: '2026-06-15T00:00:00.000Z' bus: type: - object - 'null' properties: id: type: string seatsQty: type: integer registrationNumber: type: string brand: type: string model: type: string images: type: array items: type: object properties: id: type: string name: type: - string - 'null' url: type: string description: >- Image URL (ipfs:// rewritten to the gateway). example: https://example.com/bus.jpg required: - id - name - url description: Bus image. description: Bus images. required: - id - seatsQty - registrationNumber - brand - model - images description: Bus operating this slice. carriage: type: - object - 'null' properties: id: type: string name: type: string phones: type: array items: type: string description: >- Carrier contact phones (with leading + sign). example: - '+380501234567' required: - id - name - phones description: Carriage (carrier) details. route: type: - object - 'null' properties: id: type: string name: type: string slug: type: - string - 'null' description: type: - string - 'null' company: type: object properties: id: type: string name: type: - string - 'null' slug: type: - string - 'null' email: type: string website: type: - string - 'null' rules: type: - string - 'null' logoUrl: type: - string - 'null' ceo: type: - string - 'null' description: >- Company CEO name. NOTE: pending per-partner confirmation before removal (ADR-0033 §3). example: null socials: type: array items: type: string description: >- Company social media links. NOTE: pending per-partner confirmation before removal (ADR-0033 §3). example: [] partnerCompany: type: - string - 'null' description: >- Partner company identifier. NOTE: pending per-partner confirmation before removal (ADR-0033 §3). example: null required: - id - name - slug - email - website - rules - logoUrl - ceo - socials - partnerCompany description: Bus company operating this route. permissions: type: array items: type: object properties: id: type: string role: type: - string - 'null' enum: - Dispatcher - Driver - Carrier - Admin - Agent - null accesses: type: array items: type: string enum: - Order - Booking - Management type: type: string enum: - Partner - Website required: - id - role - accesses - type description: >- Route permission. The permissions array is filtered to type=Partner AND role=Agent by the response schema. description: >- Partner-visible permissions (type=Partner, role=Agent only). services: type: array items: type: object properties: id: type: string description: Service ID. example: svc-1 name: type: string description: Service name (e.g. Wi-Fi). example: Wi-Fi required: - id - name description: Service offered on this route. description: Services offered on this route. required: - id - name - slug - description - company - permissions - services description: Route metadata. stops: type: array items: type: object properties: id: type: - string - 'null' description: Stop ID. example: stop-1 cityStopId: type: - string - 'null' description: >- ID of the underlying CityStop this stop maps to. example: cs-1 arrivalTime: type: - string - 'null' description: Arrival time (HH:mm). example: '08:00' departureTime: type: - string - 'null' description: Departure time (HH:mm). example: '06:30' platform: type: - string - 'null' description: Platform number. example: '3' place: type: - string - 'null' description: Stop place description. example: Центральний автовокзал latitude: type: - number - 'null' description: Stop latitude. example: 50.4501 longitude: type: - number - 'null' description: Stop longitude. example: 30.5234 city: type: object properties: id: type: string name: type: string slug: type: string country: type: string enum: - UA - TR - PL - CZ - IT - DE - SK - HU - BE - NL - RO - BG - FR - AT - LT - LV - EE - ES - LU - CH - GR - MD - SI timeZone: type: - string - 'null' required: - id - name - slug - country - timeZone description: City with timezone and country. description: >- Route stop with departure/arrival times and city. description: Stops for this slice. required: - id - duration - arrivalDate - departureDate - route - stops description: A single leg of the journey. description: Journey legs (slices). refundRules: type: array items: type: object properties: id: type: string hours: description: >- Hours before departure within which this rule applies. example: 24 amount: description: Refund amount (numeric). example: 500 required: - id description: Refund rule for this offer. description: Applicable refund rules. discounts: type: array items: type: object properties: id: type: string name: type: string description: type: - string - 'null' rule: type: string enum: - Amount - Percent - Overwrite startDate: type: - string - 'null' format: date-time endDate: type: - string - 'null' format: date-time amount: description: Discount amount (numeric). example: 100 required: - id - name - description - rule - startDate - endDate description: Discount applicable to this offer. description: Applicable discounts. required: - id - source - seatsLeft - arrivalDate - expiresAt - prices - slices - refundRules - discounts description: A bookable offer returned by the engine. description: Bookable offers matching the query. source: type: string description: Data source identifier. example: PrexSell required: - offers - source description: Offer search results. required: - data example: data: offers: - id: eyJhbGciOiJIUzI1NiJ9... source: PrexSell seatsLeft: 12 arrivalDate: '2026-06-15T08:00:00.000Z' expiresAt: '2026-06-14T00:20:00.000Z' prices: - id: price-1 amount: 1450 currency: UAH slices: - id: seg-123 duration: 480 departureDate: '2026-06-15T00:00:00.000Z' arrivalDate: '2026-06-15T08:00:00.000Z' bus: id: bus-1 seatsQty: 50 registrationNumber: AA1234BB brand: Mercedes-Benz model: Tourismo images: - id: img-1 name: Bus exterior url: https://example.com/bus.jpg carriage: id: carriage-1 name: Автопарк №1 phones: - '+380501234567' route: id: route-1 name: Київ — Варшава slug: kyiv-warsaw description: Щоденний нічний рейс company: id: company-1 name: PrexSell Lines slug: prexsell-lines email: ops@prexsell-lines.com website: https://prexsell-lines.com rules: >- Пасажир має прибути за 20 хвилин до відправлення. logoUrl: https://example.com/logo.png ceo: Олена Коваль socials: - https://facebook.com/prexsell.lines partnerCompany: null permissions: - id: perm-1 role: Agent accesses: - book - cancel type: Partner services: - id: svc-1 name: Wi-Fi - id: svc-2 name: Кондиціонер stops: - id: stop-1 cityStopId: cs-1 departureTime: '06:30' arrivalTime: null platform: '3' place: Центральний автовокзал latitude: 50.4501 longitude: 30.5234 city: id: city-kyiv name: Київ slug: kyiv country: UA timeZone: Europe/Kyiv - id: stop-2 cityStopId: cs-2 departureTime: null arrivalTime: '08:00' platform: '5' place: Dworzec Zachodni latitude: 52.2297 longitude: 21.0122 city: id: city-warsaw name: Варшава slug: warsaw country: PL timeZone: Europe/Warsaw refundRules: - id: rule-1 hours: 24 amount: 800 - id: rule-2 hours: 6 amount: 400 discounts: - id: disc-1 name: Студентська знижка description: Знижка 10% для студентів з дійсним квитком rule: Percent startDate: '2026-06-01T00:00:00.000Z' endDate: '2026-12-31T23:59:59.000Z' amount: 100 source: PrexSell '401': description: Standard error response body. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: AUTH_INVALID_CREDENTIALS errorCode: type: string example: UNAUTHORIZED details: {} required: - message required: - errors example: errors: - message: AUTH_INVALID_CREDENTIALS errorCode: UNAUTHORIZED security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Partner API key, sent in the `x-api-key` request header. Required for bookable offer search and all booking operations. To obtain a key, register as a PREXSELL partner in the backoffice (backoffice.prexsell.com, or staging.backoffice.prexsell.com for staging) and contact support if you need help. ````