Retailer Agent

The Retailer Agent is an AI agent that helps travellers find trips and explore alternatives through a natural-language interface — chat or voice. It guides the user through the whole journey: destination and station discovery, connection search, fare and offer comparison, vacancy and seat checks, cart and checkout-link generation, carrier terms and conditions, and post-sales support for existing bookings.

The agent is exposed as a plain HTTP + WebSocket API, so it can be embedded in your own chat UI, voice channel, contact-centre tooling, or back-office application. Distribusion also ships a ready-made chat widget on top of it.

Base URL

All endpoints are served under the /agent prefix:

Authentication

The Retailer Agent endpoints expect an API key in the headers:

 
POST https://api.distribusion.com/agent/chat
api-key: <your-agent-api-key>
Content-Type: application/json
Accept: application/json

This key is specific to the Retailer Agent and the MCP Server, and is not your regular Retailer API key — see API Authentication. Contact your Partnership Manager to get access to your Retailer Agent API key.

The key identifies your retailer account, so no retailer code has to be passed in the request. The Retailer API key that the agent uses to reach Distribusion's booking services is resolved server-side and is never exposed to the client.

Voice WebSockets cannot carry custom headers. There, the same key is sent as api_key inside the first JSON message on the socket (see Voice below).

Conversation Model

Every chat request carries two identifiers (user ID and conversation ID) that you choose and keep stable, as well as the user's message text:

Conversation state is stored server-side, so you do not have to replay the transcript on each turn. Use the /history and /conversations endpoints to re-populate a UI after a page refresh or a checkout round-trip.

Endpoints

Travel agent (main chat)

Post-sales

A dedicated agent for travellers who already hold a booking: booking lookup, ticket retrieval, change and cancellation guidance, and carrier T&C answers. It also works anonymously (FAQ and T&C only) when no booking credentials are supplied.

The post-sales request body accepts an optional bookings array. Each entry identifies a booking either by booking_id, or by booking_number + last_name + email. Omit it (or send []) for anonymous support.

Supporting endpoints

How to Use — Chat

POST /chat

Request Body

 
{
  "user_id": "<unique user id>",
  "conversation_id": "<unique conversation id>",
  "text": "<text input>"
}

Optional fields for personalisation: user_preferences, user_location ({"latitude": …, "longitude": …}, enables "from my location" queries), context_mode (memory | profile | none), and bookings when the user has already verified booking credentials.

Response

 
{
  "text": "<response from agent>",
  "response_event_id": "<id of the event that produced the text>"
}

response_event_id correlates the reply with the stored conversation — the history endpoints return the same value as event_id. It is null when the text is not agent output, for example a safety block or a fallback message.

POST /chat/stream

Same request body. The response is application/x-ndjson: one JSON object per line, emitted as the run progresses.

{
  "event_type": "final_output | partial_output | function_call | function_response | unknown",
  "text_chunk": "<response chunk from agent>" | null,
  "function_calls": [{ "name": "…", "args": { … }, "thought": "…" }] | null,
  "function_responses": [{ "name": "…", "response": { … }, "thought": "…" }] | null,
  "response_event_id": "…" | null
} {
  "event_type": "final_output | partial_output | function_call | function_response | unknown",
  "text_chunk": "<response chunk from agent>" | null,
  "function_calls": [{ "name": "…", "args": { … }, "thought": "…" }] | null,
  "function_responses": [{ "name": "…", "response": { … }, "thought": "…" }] | null,
  "response_event_id": "…" | null
}

Handling the stream

1. Open the stream Send the request and read the response line by line.
2. Accumulate text On partial_output, append text_chunk to the message currently being rendered.
3. Show tool activity On function_call / function_response, show the thought as a "thinking" indicator, and optionally use the raw response to render richer output.
4. Finish the turn On final_output, the turn is over.

A sequence of partial_output events followed by an event of a different type marks the end of a message, not of the turn. One turn can contain several messages, for example: "I'll search for your trip" → tool call → tool response → "I found these trips…".

Example

 
curl --no-buffer -N -X POST "https://s.api.distribusion.com/agent/chat/stream" \
  -H "Content-Type: application/json" \
  -H "api-key: <your-agent-api-key>" \
  -d '{
    "user_id": "user-123",
    "conversation_id": "conv-456",
    "text": "from Mexico City to Monterrey today from 7pm"
  }'

{"event_type":"function_call","function_calls":[{"args":{"query":"Mexico City","locale":"en"},"name":"search_cities","thought":"Searching for Mexico City"}]}
{"event_type":"function_response","function_responses":[{"name":"search_cities","response":{"cities":[{"code":"MXMCI","name":"Mexico City","country_code":"MX"}]}}]}
{"event_type":"function_call","function_calls":[{"args":{"departure_city_code":"MXMCI","arrival_city_code":"MXMTY","departure_date":"2026-03-20","departure_start_time":"19:00","locale":"en"},"name":"connections_find","thought":"Finding trips..."}]}
{"event_type":"function_response","function_responses":[{"name":"connections_find","response":{"connections":[{"connection_id":"SDIA-MXMCICIU-MXMTYMBU-…","departure_time":"2026-03-20T19:00:00","arrival_time":"2026-03-21T08:40:00","price":61.68,"currency":"EUR","carrier":{"code":"SDIA","name":"Senda Diamante"}}]}}]}
{"event_type":"partial_output","text_chunk":"Here are the connections I found from Mexico City to Monterrey"}
{"event_type":"partial_output","text_chunk":" for today, departing from 7 PM: …"}
{"event_type":"final_output","text_chunk":"","response_event_id":"…"} {"event_type":"function_call","function_calls":[{"args":{"query":"Mexico City","locale":"en"},"name":"search_cities","thought":"Searching for Mexico City"}]}
{"event_type":"function_response","function_responses":[{"name":"search_cities","response":{"cities":[{"code":"MXMCI","name":"Mexico City","country_code":"MX"}]}}]}
{"event_type":"function_call","function_calls":[{"args":{"departure_city_code":"MXMCI","arrival_city_code":"MXMTY","departure_date":"2026-03-20","departure_start_time":"19:00","locale":"en"},"name":"connections_find","thought":"Finding trips..."}]}
{"event_type":"function_response","function_responses":[{"name":"connections_find","response":{"connections":[{"connection_id":"SDIA-MXMCICIU-MXMTYMBU-…","departure_time":"2026-03-20T19:00:00","arrival_time":"2026-03-21T08:40:00","price":61.68,"currency":"EUR","carrier":{"code":"SDIA","name":"Senda Diamante"}}]}}]}
{"event_type":"partial_output","text_chunk":"Here are the connections I found from Mexico City to Monterrey"}
{"event_type":"partial_output","text_chunk":" for today, departing from 7 PM: …"}
{"event_type":"final_output","text_chunk":"","response_event_id":"…"}

Voice

Voice is a bidirectional WebSocket. Connect to wss://s.api.distribusion.com/agent/voice/stream (or the post-sales equivalent).

1. Open the socket Send one JSON message first, containing user_id, conversation_id and api_key.
2. Exchange audio Then exchange binary PCM audio frames, plus JSON control messages.

The voice agent shares the travel agent's tools and conversation storage, so a voice session and a chat session on the same conversation_id continue the same thread.

Suggested UI

These endpoints are meant to be integrated in a chat-like UI, as showcased below (streaming response displaying function calls).

Features

Notes

• Streaming and voice need a long-lived connection. Use s.api.distribusion.com for those; the standard host times out first.
• Do not buffer the NDJSON response. Disable client-side buffering (for example curl --no-buffer -N) or the stream will only appear at the end.
• Errors are returned as {"error": "…", "detail": "…"}. 400 means the request or the API key is wrong, 401/403 an authentication or permission problem, 404 a missing conversation or resource, 422 a validation error, and 503 a temporary upstream problem worth retrying.
• Operational endpoints (/health, /metrics, /docs, /openapi.json) are not exposed publicly.