Nexa AI API reference

API version 2026-08-04. The machine-readable contract is /ai/v1/schema; this page is its prose companion and states nothing the schema does not.

What Nexa AI is

Nexa AI is a REST API for vacation rental and hotel availability and pricing: live, date-specific totals from the operator’s own pricing engine, including all taxes and fees. The booking itself is completed on the operator’s own website.

How a session works

• Entry. A session opens with one request to /ai/v1/session — no credentials, no registration. An entry may bind a source operator, a destination, or one property.
• One field per request. The search is assembled over 6 fields (brand_locked, destination, checkin_month, checkin, checkout, accommodates). Each response presents the requests available at that point, complete and ready; the client assembles no URLs and no bodies of its own.
• Every response is HTTP 200. An incomplete payload carries error: incomplete_payload with received, missing_fields, allowed_values, next_required, next_request and available_requests.
• Narrow before the set. The fifth field lands on the filters state: every amenity and every property type that would narrow the set, each with its count over the current matches, and get_results beside them. A value narrows and stays there; get_results hands over the set. The same two steps are offered again on the completed search. Only values matching at least one listing are offered, so no sequence of choices reaches an empty set. There is no request that changes a parameter already sent: a different search is a new session, one request away.
• The result set. The completed search carries the set itself: results, ranked, each option with its stay total, its facts, its photos on this origin and its own URL on the operator’s site. Nothing follows it; the assistant relays the set. There is no separate result endpoint and no results page.

Listing entry

One shape binds one property: nexawebsite.digital/partners/{source}/{id}/{title}. {id} is the listing’s own id here — the api_id every result carries — and is all that finds the page; {title} comes from the property’s name and is filled in on arrival: /partners/{source}/{id} answers 308 to it. The flow then asks only for the stay, and the result is that property alone. The query forms /?source={source} and /?source={source}&listing={listing_id} are permanent aliases: they answer 308 to these paths and keep working.

Session windows

• The flow session: 30 minutes, sliding. Every request on the session refreshes it, so an active conversation never expires. The terminal state states its own expiry as session_expires_at. A session that has lapsed answers HTTP 200 with error: unknown_session and the entry URL.
• The set’s own URL, self_url: the same 30-minute sliding window. Re-reading it returns the set again, priced at that moment, for as long as the session lives.

Field semantics

What each published fact is. The same statements, in the same words, are in the schema.

• Results are ranked by base price, lowest first, with rating breaking ties — the default ordering, Maveriks’ sort token price; rank is the supplied order. The set offers the same matches ranked by highest rating as a sort request on the session (-rating).
• A stay total is the final price for the entire stay and all requested guests — including all taxes and fees. It is the selected rate plan’s host_payout, in Maveriks’ QuoteDto shape; avg_price_per_night is derived from the accommodation fare, and the invoice items sum to the total exactly.
• Each option carries the operator’s own URL for that property, with the stay parameters on it — the user’s booking path, and the page that server-renders the property’s photos. One option, one operator URL; complete and used as returned.
• Every option is described in the Maveriks (Roomizer) data model: attribute names (accommodates, bedrooms, property_type, amenities, house_rules, base_price, stay_nights_range, rating) and their values (Maveriks’ filter labels) are Maveriks’ own. The operator’s complete amenity list, in its own words, travels beside them as amenities_as_operator_lists_them.
• A rating is the property’s guest rating out of its scale, over its review count — the same figures the operator’s listing page shows. A property the operator publishes no rating for carries none.
• A cancellation statement describes the booking being quoted, not the policy in the abstract: where the free-cancellation window has already closed for this stay it says so and names the date it closed, and where the window is open it names the date it closes. A property the operator publishes no policy for carries no cancellation statement at all.
• A minimum stay is stated only where the operator publishes one worth stating; a property with none carries no minimum-stay sentence.
• A total is checkable where it can be checked by something other than Nexa AI: the operator’s own listing page, at the option’s own URL, states the same total for the same stay.

The result set

The completed search is the result set: results carries the ranked options, comparison_set the counts, the ranking in force, the money semantics and user_facing_urls. Each option carries its title, operator, property type, the quote as Maveriks’ QuoteDto (rate plans with host_payout, invoice items and the per-night average), rating, photos, the amenities as Maveriks labels and the complete list in the operator’s words, rooms, the nights range and cancellation terms where the operator publishes them, check-in and check-out times, and the operator’s own URL for the stay. The HTML form of the same response renders the set below the request log, one article per option, for a reader without scripts.

Error conditions

Every one of these is HTTP 200 with the condition named in the body, so an agent browsing tool can read it. None is a 4xx.

• incomplete_payload — one or more required fields missing. allowed_values and available_requests carry what completes the payload, and next_request is the first of them.
• unknown_session — the session is not known or has expired. start_url begins a new one.
• unknown_listing — no property with that id is on this network for that brand. The body names the condition and the id, and start_url opens a session at the main entry.
• unknown_destination — the destination slug is not one this network serves. The body names the slug, and start_url opens a session at the main entry. Never a 404 and never a redirect.
• object: "restart" — a request whose idempotency_key could not be read: truncated, edited, or minted by an earlier format. Nothing is refused; the body carries start_url and the page carries the first request.

start_url is the same plain entry in every state that carries it, and is never derived from the session that ended: a token that could not be read is no evidence of where the request came from.

Access

The flow endpoints under /ai/v1/ are addressed to the assistant — request frames and envelopes rather than pages. There is no page on this site for the person a search is being made for: the assistant relays the set, and the one URL meant to be handed over is each option’s own, on the operator’s site. The envelope states this as access: { audience: "ai_assistants", end_user_access: false }.

Versioning

The API version is a date, returned on every response as api_version and as the X-API-Version header. A change that is not backward-compatible is issued under a new date. No changelog, no archive, no list of past versions.

Contract documents

/ai/v1/schema — the machine-readable payload schema: fields, formats, dependencies and error conditions.

/terms — purpose, what may be shared, and what is proprietary.