Chat

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"
  }'

array

required

Ordered chat messages. User message text is bounded and validated before processing.

boolean

When true, returns a text/event-stream response with incremental data: events.

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>"

number

Maximum messages to return. The route caps the value.

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"
  }'

string

required

good or bad.

string

required

Assistant message content being rated.

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"
  }'

string

required

User message text, 1-4000 characters after trimming.

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

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

API Reference

Endpoints

Webhooks

POST /api/chat

GET /api/chat/history

POST /api/chat/history

DELETE /api/chat/history

POST /api/chat/feedback

POST /api/v1/chat

Errors

​POST /api/chat

​GET /api/chat/history

​POST /api/chat/history

​DELETE /api/chat/history

​POST /api/chat/feedback

​POST /api/v1/chat

​Errors

POST /api/chat

GET /api/chat/history

POST /api/chat/history

DELETE /api/chat/history

POST /api/chat/feedback

POST /api/v1/chat

Errors