---
title: Ask the AI Assistant
protocol: rest
method: POST
endpoint: /v1/projects/{projectId}/chat
description: "Ask the project's AI assistant a question and stream the answer."
---

# Ask the AI Assistant

Ask a question against a project's documentation. The answer is generated with RAG over the project's indexed content and **streamed back as Server-Sent Events** with citations.

This is the endpoint the embeddable chat widget uses — it's public (no API key required) but subject to [visitor rate limits](/api-reference/rate-limits) and the organization's monthly AI query quota.

<Endpoint method="POST" path="/v1/projects/{projectId}/chat" />

## Path Parameters

<ParamField path="projectId" type="string" required>
  The project ID.
</ParamField>

## Request Body

<ParamField body="question" type="string" required>
  The question to ask. 1–2000 characters.
</ParamField>

<ParamField body="sessionId" type="string">
  UUID of an existing chat session for multi-turn context. Omit to start a new session — the response returns the new session ID in the `X-Session-Id` header.
</ParamField>

<ParamField body="visitorId" type="string">
  Anonymous visitor identifier (max 100 chars). Used for per-visitor rate limiting and analytics, and — in [agentic mode](/platform/doc-site-features) — for the visitor's [conversation history](/api-reference/chat/sessions) and cross-conversation memory: the assistant distills durable facts from each exchange and uses them to tailor future answers for the same visitor.
</ParamField>

<ParamField body="pageContext" type="string">
  The doc page path the visitor is currently on. Improves retrieval for inline "ask about this page" experiences.
</ParamField>

## Response

`200` with `Content-Type: text/event-stream`. The `X-Session-Id` response header contains the session UUID to pass on follow-up questions.

The stream emits token deltas followed by a final message containing citations (source page paths) and a confidence score.

## Example

<CodeGroup>
```bash cURL
curl -N https://api.syntext.dev/v1/projects/prj_abc123/chat \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I add a custom domain?",
    "visitorId": "vis_9f8e7d"
  }'
```

```typescript SDK
import { Syntext } from '@syntext/sdk'

const client = new Syntext('stx_abc12345_...')

const stream = await client.chat.ask('prj_abc123', {
  question: 'How do I add a custom domain?',
})

for await (const chunk of stream) {
  process.stdout.write(chunk.delta)
}
```
</CodeGroup>

## Error Responses

### 429 Rate Limited

The visitor asked too many questions in a short window. Configurable per project.

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait before asking another question.",
    "retryAfterSeconds": 30
  }
}
```

### 403 Usage Limit Exceeded

The organization's monthly AI query quota is exhausted.

```json
{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly AI query limit reached (1000/1000). Upgrade your plan for more AI queries.",
    "current": 1000,
    "limit": 1000
  }
}
```

### 503 Service Unavailable

The AI assistant is not configured for this deployment.

<Note>
Unanswered and low-confidence questions are tracked as **documentation gaps** — see [Analytics](/api-reference/analytics/content-health).
</Note>