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.
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.
bashcurl -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?" } ] }'
textevent: 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{ "error": "Missing jobId or messages" }
json{ "error": "Report not found" }
json{ "error": "Rate limit exceeded", "retry_after": 42, "limit_type": "per_minute" }
json{ "error": "Daily token budget exceeded", "limit_type": "daily_tokens", "budget": 200000, "used": 200143 }
See 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.
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{ "error": "Report not found" }