POST /api/chat — streaming AI assistant for prices

The PRIXO AI assistant answers food delivery questions in Arabic and English using live price data from the community database. You send a conversation history and receive a streaming response over Server-Sent Events — the assistant may invoke tools mid-stream to fetch prices, locate branches, or recall your saved preferences before it replies.

Endpoint

POST /api/chat

Authentication

Required. You must be signed in with a valid session cookie. Calls without a session receive a 401 response. See the Authentication guide for how to obtain a session.

Rate limit

30 requests per minute per authenticated user. Exceeding this limit returns a 429 response.

When you exceed the rate limit, the endpoint immediately returns HTTP 429 with the body {"error": "rate_limit_exceeded"}. Your client should back off and retry after at least 60 seconds.

Request

Set Content-Type: application/json and send a JSON body containing the full conversation history.

Body parameters

array

required

The conversation history as an array of message objects. Each message must have a role and content field.

Show messages[n] fields

string

required

The author of the message. One of "user" or "assistant".

string

required

The text content of the message. Accepts Arabic and English.

Example request

{
  "messages": [
    { "role": "user", "content": "شاورما ماما نورة بكم على جاهز؟" }
  ]
}

curl -X POST https://prixo.ai/api/chat \
  -H "Content-Type: application/json" \
  -H "Cookie: <your-session-cookie>" \
  -d '{
    "messages": [
      { "role": "user", "content": "شاورما ماما نورة بكم على جاهز؟" }
    ]
  }'

Response

The response is a Server-Sent Events (SSE) stream with Content-Type: text/event-stream. The stream delivers the assistant’s reply in incremental text chunks, interleaved with tool call events when the assistant needs to look up live data. The stream closes automatically when the assistant finishes its response.

Stream events

The assistant emits several types of events during a response:

Event type	Description
Text chunk	A fragment of the assistant’s reply text, delivered as it is generated.
Tool call start	Signals that the assistant is invoking a tool to fetch live data.
Tool call result	The data returned from a tool, which the assistant uses to compose its reply.
Finish	Marks the end of the stream.

Tool names

The assistant has access to these tools. Tool call events in the stream identify which tool is running:

Tool name	What it does
`search_restaurant`	Looks up a restaurant by name in the PRIXO database.
`get_price_comparison`	Fetches ranked delivery prices for a specific dish at a restaurant.
`get_nearest_branches`	Finds the closest branches of a restaurant to a given location.
`suggest_similar_items`	Performs a semantic search to find dishes similar to the one you asked about.
`save_user_fact`	Saves a preference or fact about you for future conversations. Requires authentication.
`recall_user_memory`	Retrieves previously saved preferences or facts about you.

Use a streaming-capable client to consume this endpoint. Any SSE-capable HTTP client or EventSource implementation can consume the stream. The stream closes automatically when the assistant finishes its response.

Example stream output

The following shows an abbreviated stream for a price query. Each line beginning with data: is one SSE event.

data: {"type":"text-delta","textDelta":"على"}

data: {"type":"text-delta","textDelta":" جاهز"}

data: {"type":"tool-call","toolName":"get_price_comparison","args":{"restaurant":"ماما نورة","item":"شاورما","platform":"jahez"}}

data: {"type":"tool-result","toolName":"get_price_comparison","result":{"total":18.0,"itemPrice":10.5,"deliveryFee":7.5}}

data: {"type":"text-delta","textDelta":"، السعر الكلي ١٨ ريال"}

data: {"type":"finish","finishReason":"stop"}

Error responses

Status	Body	Meaning
`401`	`{"error": "unauthorized"}`	No valid session cookie was provided.
`429`	`{"error": "rate_limit_exceeded"}`	You have exceeded 30 requests per minute.
`400`	`{"error": "invalid_request"}`	The request body is missing or malformed.
`500`	`{"error": "internal_error"}`	An unexpected server error occurred.

For multi-turn conversations, include the full conversation history in every request — not just the latest message. The assistant uses earlier turns to provide context-aware answers, especially when recalling saved preferences.

Overview

Endpoints

POST /api/chat — streaming AI assistant for prices

Endpoint

Authentication

Rate limit

Request

Body parameters

Example request

Response

Stream events

Tool names

Example stream output

Error responses

​Endpoint

​Authentication

​Rate limit

​Request

​Body parameters

​Example request

​Response

​Stream events

​Tool names

​Example stream output

​Error responses

Endpoint

Authentication

Rate limit

Request

Body parameters

Example request

Response

Stream events

Tool names

Example stream output

Error responses