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

# Chat

> Session-authenticated AI chat, chat history, and chat feedback endpoints.

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.

<Note>
  This page documents application chat endpoints first, then the v1 API-key chat endpoint. For CRM-style customer conversations, see [Conversations](/api-reference/endpoints/conversations).
</Note>

## 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.

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ParamField body="messages" type="array" required>
  Ordered chat messages. User message text is bounded and validated before processing.
</ParamField>

<ParamField body="stream" type="boolean">
  When `true`, returns a `text/event-stream` response with incremental `data:` events.
</ParamField>

<ParamField body="currentPage" type="string">
  Optional page context used to make the assistant more relevant.
</ParamField>

```json theme={null}
{
  "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:

```text theme={null}
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.

```bash theme={null}
curl "https://app.neariq.io/api/chat/history?limit=50" \
  -H "Cookie: <dashboard session cookie>"
```

<ParamField query="limit" type="number">
  Maximum messages to return. The route caps the value.
</ParamField>

<ParamField query="businessId" type="string">
  Optional business UUID to filter history.
</ParamField>

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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.

```bash theme={null}
curl -X DELETE "https://app.neariq.io/api/chat/history" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "cleared": true
}
```

## POST /api/chat/feedback

Records a thumbs-up or thumbs-down signal for one assistant message.

```bash theme={null}
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"
  }'
```

<ParamField body="rating" type="string" required>
  `good` or `bad`.
</ParamField>

<ParamField body="messageContent" type="string" required>
  Assistant message content being rated.
</ParamField>

<ParamField body="messageTs" type="string">
  Client timestamp or stable message timestamp used for de-duplication.
</ParamField>

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

<ParamField body="message" type="string" required>
  User message text, 1-4000 characters after trimming.
</ParamField>

<ParamField body="context" type="string" default="general">
  One of `general`, `competitors`, `reviews`, `content`, or `marketing`.
</ParamField>

```json theme={null}
{
  "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                     |