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

# AI chat API

Stream AI responses about any ShopSniffer report via Server-Sent Events, plus suggested prompts per report.

## Overview

The chat API lets you ask AI questions about any completed report — "what are the top-selling categories?", "compare pricing to competitor X", "what apps does this store use?" — and receive responses as a Server-Sent Events stream. Authenticated users get higher rate and token limits than anonymous users.

Base URL: `https://shopsniffer.com/api`

**Model:** `x-ai/grok-4.1-fast` via OpenRouter. Responses are tool-augmented: the model can query the report's products, collections, pages, PageSpeed, and apps data through internal tool calls (up to 5 tool-call rounds before returning a final answer).

## `POST /chat` Stable

Stream a chat response about a report. Returns an SSE stream, not a JSON body.

**Auth:** Optional. Anonymous requests are heavily rate-limited; authenticated requests (API key or session) get the full budget. See [rate limits](/rate-limits).

Job UUID of the report to ask about. The model's context is scoped to this report only.

Chat message history. Each message is `{ role: "user" | "assistant", content: string }`. Include the full conversation for multi-turn context.

**Ask about a report**

```bash
curl -X POST https://shopsniffer.com/api/chat \
  -H "X-API-Key: ss_your_key_here" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messages": [
      { "role": "user", "content": "What are the top-selling product categories?" }
    ]
  }'
```

**SSE stream**

```
event: status
data: {"status": "thinking"}

event: content
data: {"text": "Based on the catalog for allbirds.com, "}

event: content
data: {"text": "the top categories are:\n1. Shoes (82 products)\n2. Apparel (54 products)"}

event: done
data: {}
```

### Event types

| Event | Payload | Meaning |
| --- | --- | --- |
| `status` | `{ status: "thinking" \| "tool_call" \| "generating" }` | Stage updates |
| `content` | `{ text: string }` | Append to the displayed answer |
| `tool_call` | `{ tool: string, args: object }` | Model is querying the report (informational) |
| `done` | `{}` | End of stream; close the connection |
| `error` | `{ error: string }` | Fatal error; stream will close |

### Error responses

```json title="400 Bad Request"
{ "error": "Missing jobId or messages" }
```

```json title="404 Not Found"
{ "error": "Report not found" }
```

```json title="429 Too Many Requests"
{
  "error": "Rate limit exceeded",
  "retry_after": 42,
  "limit_type": "per_minute"
}
```

```json title="429 Too Many Requests"
{
  "error": "Daily token budget exceeded",
  "limit_type": "daily_tokens",
  "budget": 200000,
  "used": 200143
}
```

See [rate limits](/rate-limits) for concrete numbers.

---

## `GET /chat/suggestions/:jobId` Stable

Get suggested chat prompts for a specific report. Use these to seed the UI with starter questions tailored to the store's data.

**Auth:** None.

Job UUID.

**Suggestions**

```json
{
  "suggestions": [
    "What are the top-selling product categories?",
    "How does pricing compare across the collection?",
    "Which Shopify apps are installed?",
    "What's the overall PageSpeed score?",
    "Summarize recent changes to the catalog"
  ]
}
```

```json title="404 Not Found"
{ "error": "Report not found" }
```

## Next steps

**[Rate limits](/rate-limits)**

Per-minute and daily token budgets for chat.
  **[AI agent integration](/agent-integration)**

Wire chat into an agent loop with tool use.