Query API

The query endpoint is the core of Retail Mind. Send a natural language question, get back an answer, the generated SQL, tabular data, and chart-ready JSON.

POST /v1/query

Synchronous query — waits for the full response.

Request

{
  "source_id": "src_abc123",
  "question": "What were the top 5 products by revenue last month?",
  "ai_provider_id": "aip_xyz456",
  "options": {
    "max_rows": 1000,
    "include_sql": true,
    "include_chart": true,
    "chart_type": "auto"
  }
}

Field	Type	Required	Description
`source_id`	string	✓	ID of your connected data source
`question`	string	✓	Natural language question
`ai_provider_id`	string		Override the default AI provider
`options.max_rows`	int		Max rows to return (default: 1000)
`options.include_sql`	bool		Include generated SQL in response
`options.include_chart`	bool		Include chart-ready JSON
`options.chart_type`	string		`auto` \| `bar` \| `line` \| `pie` \| `scatter`

Response

{
  "id": "qry_def789",
  "status": "completed",
  "question": "What were the top 5 products by revenue last month?",
  "sql": "SELECT p.name, SUM(oi.unit_price * oi.qty) AS revenue FROM order_items oi JOIN products p ON p.id = oi.product_id JOIN orders o ON o.id = oi.order_id WHERE o.created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month') AND o.created_at < DATE_TRUNC('month', NOW()) GROUP BY p.name ORDER BY revenue DESC LIMIT 5",
  "answer": "The top 5 products by revenue last month were Nike Air Max ($142,500), Adidas Ultraboost ($98,200), Levi's 501 Jeans ($87,400), Apple AirPods ($76,300), and Samsung Galaxy Buds ($54,100).",
  "data": {
    "columns": ["name", "revenue"],
    "rows": [
      ["Nike Air Max", 142500],
      ["Adidas Ultraboost", 98200],
      ["Levi's 501 Jeans", 87400],
      ["Apple AirPods", 76300],
      ["Samsung Galaxy Buds", 54100]
    ],
    "row_count": 5,
    "total_rows": 5,
    "page": 1,
    "page_size": 1000
  },
  "chart": {
    "type": "bar",
    "title": "Top 5 Products by Revenue — Last Month",
    "x_axis": "name",
    "y_axis": "revenue",
    "series": [
      {
        "name": "Revenue",
        "data": [
          { "label": "Nike Air Max", "value": 142500 },
          { "label": "Adidas Ultraboost", "value": 98200 }
        ]
      }
    ],
    "metadata": {}
  },
  "execution_ms": 1240,
  "tokens_used": 892,
  "cache_hit": false,
  "created_at": "2026-04-02T10:30:00Z"
}

Code Examples

curl -X POST https://api.retailmind.dev/v1/query \
  -H "Authorization: Bearer $RETAIL_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "question": "Top 5 products by revenue last month"
  }'

import httpx
 
response = httpx.post(
    "https://api.retailmind.dev/v1/query",
    headers={"Authorization": f"Bearer {RETAIL_MIND_KEY}"},
    json={
        "source_id": "src_abc123",
        "question": "Top 5 products by revenue last month",
    },
)
result = response.json()
print(result["answer"])
print(result["chart"])

const response = await fetch("https://api.retailmind.dev/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.RETAIL_MIND_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source_id: "src_abc123",
    question: "Top 5 products by revenue last month",
  }),
});
 
const result = await response.json();
console.log(result.answer);

$response = \Illuminate\Support\Facades\Http::withToken(env('RETAIL_MIND_KEY'))
    ->post('https://api.retailmind.dev/v1/query', [
        'source_id' => 'src_abc123',
        'question'  => 'Top 5 products by revenue last month',
    ]);
 
$result = $response->json();
echo $result['answer'];

payload := map[string]any{
    "source_id": "src_abc123",
    "question":  "Top 5 products by revenue last month",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.retailmind.dev/v1/query", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("RETAIL_MIND_KEY"))
req.Header.Set("Content-Type", "application/json")

For real-time streaming responses (token by token), see the Streaming page.

AI Providers Streaming (SSE)