> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prixo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/chat — streaming AI assistant for prices

> Send messages to the PRIXO AI assistant and receive a streaming SSE response. The assistant calls tools mid-stream to look up prices and locate branches.

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](/api/authentication) for how to obtain a session.

## Rate limit

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

<Warning>
  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.
</Warning>

## Request

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

### Body parameters

<ParamField body="messages" type="array" required>
  The conversation history as an array of message objects. Each message must have a `role` and `content` field.

  <Expandable title="messages[n] fields">
    <ParamField body="messages[n].role" type="string" required>
      The author of the message. One of `"user"` or `"assistant"`.
    </ParamField>

    <ParamField body="messages[n].content" type="string" required>
      The text content of the message. Accepts Arabic and English.
    </ParamField>
  </Expandable>
</ParamField>

### Example request

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

```bash theme={null}
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.                              |

<Note>
  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.
</Note>

### 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.      |

<Tip>
  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.
</Tip>