Skip to main content
POST
/
api
/
chat
curl -X POST "https://app.neariq.io/api/chat" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "messages": [
      { "role": "user", "content": "Which competitor should I watch this week?" }
    ],
    "stream": false,
    "currentPage": "dashboard"
  }'
Chat endpoints power the dashboard assistant and public site assistant. They use the signed-in dashboard session when available. Anonymous chat is more tightly rate limited, while authenticated chat uses plan-based message limits.
This page documents application chat endpoints first, then the v1 API-key chat endpoint. For CRM-style customer conversations, see Conversations.

​
POST /api/chat

Sends chat messages to the assistant. Supports streaming responses when stream is true, text-only messages, and bounded image attachments in supported formats. For signed-in users, the assistant also reads saved AI preferences from Settings: tone, response length, language, whether memory is enabled, and saved context notes. Chat memory commands such as “Remember X”, “Forget X”, and “What do you remember?” update or summarize active memories. Active memories are capped at 10 and are treated as business context, not as free-form system instructions. 
curl -X POST "https://app.neariq.io/api/chat" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "messages": [
      { "role": "user", "content": "Which competitor should I watch this week?" }
    ],
    "stream": false,
    "currentPage": "dashboard"
  }'
​
messages
array
required
Ordered chat messages. User message text is bounded and validated before processing.
​
stream
boolean
When true, returns a text/event-stream response with incremental data: events.
​
currentPage
string
Optional page context used to make the assistant more relevant.
{
  "reply": "Watch Apex Grove Strength this week. Their review velocity is up and their latest content is targeting the same service area."
}
Streaming responses use this shape: 
data: {"text":"Watch Apex Grove Strength"}

data: {"text":" this week."}

data: [DONE]

​
GET /api/chat/history

Loads recent persisted chat messages for the signed-in user. 
curl "https://app.neariq.io/api/chat/history?limit=50" \
  -H "Cookie: <dashboard session cookie>"
​
limit
number
Maximum messages to return. The route caps the value.
​
businessId
string
Optional business UUID to filter history.
{
  "messages": [
    {
      "id": "e74404d4-8338-4c47-8586-a369f2a42fcb",
      "role": "user",
      "content": "Summarize my newest alerts.",
      "businessId": "5d49faca-17f3-45f6-a0ef-60bd93754771",
      "createdAt": "2026-05-30T15:00:00.000Z"
    }
  ]
}

​
POST /api/chat/history

Persists one chat message for cross-device history. 
curl -X POST "https://app.neariq.io/api/chat/history" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "role": "assistant",
    "content": "Your newest alert is a competitor review surge.",
    "businessId": "5d49faca-17f3-45f6-a0ef-60bd93754771"
  }'

{
  "message": {
    "id": "e74404d4-8338-4c47-8586-a369f2a42fcb",
    "role": "assistant",
    "content": "Your newest alert is a competitor review surge.",
    "created_at": "2026-05-30T15:01:00.000Z"
  }
}

​
DELETE /api/chat/history

Clears the signed-in user’s chat history. 
curl -X DELETE "https://app.neariq.io/api/chat/history" \
  -H "Cookie: <dashboard session cookie>"

{
  "cleared": true
}

​
POST /api/chat/feedback

Records a thumbs-up or thumbs-down signal for one assistant message. 
curl -X POST "https://app.neariq.io/api/chat/feedback" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "rating": "good",
    "messageContent": "Your newest alert is a competitor review surge.",
    "messageTs": "2026-05-30T15:01:00.000Z"
  }'
​
rating
string
required
good or bad.
​
messageContent
string
required
Assistant message content being rated.
​
messageTs
string
Client timestamp or stable message timestamp used for de-duplication.
{
  "ok": true
}

​
POST /api/v1/chat

Sends one non-streaming message to the API assistant for the caller’s active business context. Requires the chat:write scope. 
curl -X POST "https://app.neariq.io/api/v1/chat" \
  -H "X-NearIQ-Key: niq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What should I focus on this week?",
    "context": "competitors"
  }'
​
message
string
required
User message text, 1-4000 characters after trimming.
​
context
string
default:"general"
One of general, competitors, reviews, content, or marketing.
{
  "message": "Focus on the competitor whose review velocity increased this week.",
  "context": "competitors",
  "usage": { "used": 12, "limit": 100 },
  "_receipt": { "request_id": "...", "timestamp": "...", "sha256": "..." }
}

​
Errors

StatusMeaning
400Invalid JSON, unsupported attachment, or invalid feedback payload
401Missing session for history or feedback endpoints
429Anonymous or plan-based chat limit exceeded
500Chat, persistence, or feedback storage failed