Ask an AI Representative (Streaming)
The streaming ask endpoint sends a question to a professional's AI Representative and returns the response as a real-time Server-Sent Events (SSE) stream. This is the primary endpoint for building interactive chat experiences.
/api/v1/public/ai/askAsk a question and receive a streaming SSE response
Request body
profileIdstringRequiredThe unique identifier of the professional whose AI Representative you want to ask.
questionstringRequiredThe question to ask the AI Representative. Maximum 1,000 characters.
modestringOptionalConversation mode. Use 'public' for visitor interactions or 'owner' for the profile owner interacting with their own AI Rep. Defaults to 'public'.
Allowed values: public, owner
visitorFingerprintstringOptionalA unique identifier for the visitor. Used for rate limiting and conversation continuity. Generate a stable fingerprint per device or browser session.
sessionIdstringOptionalSession identifier for grouping related questions into a single conversation thread.
conversationHistoryarrayOptionalPrevious messages in the conversation for multi-turn context. Each entry has a role and content field.
rolestringRequiredThe message author. Either 'user' or 'assistant'.
contentstringRequiredThe message text.
postSlugstringOptionalIf the question relates to a specific blog post, include the post slug for additional context.
exchangeCountnumberOptionalThe number of question-answer exchanges so far in this session. Used for rate limit tracking.
SSE event types
The response is a Server-Sent Events stream. Each event has a type field that tells you what kind of data it contains.
| Event | Description |
|---|---|
connected | Connection established. The stream is ready. |
meta | Metadata about the AI Representative (name, profile info). |
post_context | Blog post context loaded, if postSlug was provided. |
text | A chunk of the AI Representative's response. Concatenate these to build the full answer. |
error | An error occurred during generation. Contains an error message. |
done | The response is complete. Includes suggested follow-up questions. |
Code examples
Basic streaming request
Multi-turn conversation
To maintain conversation context across multiple questions, pass the conversationHistory and sessionId fields.
Rate limiting
The ask endpoint is rate-limited per profile and visitor fingerprint combination. When you exceed the limit, the stream returns an error event with details about when you can retry.
Rate limit behavior
Rate limits are variable based on the profile owner's plan. Free profiles allow fewer questions per visitor. The done event includes a remaining_questions field so you can show users how many questions they have left.
Error handling
Errors can arrive in two ways:
- HTTP errors (4xx, 5xx) before the stream starts, returned as standard JSON error responses.
- Stream errors during generation, sent as SSE events with
type: "error".
Always handle both cases in your integration.
| HTTP Status | Meaning |
|---|---|
400 | Invalid request body (missing profileId or question) |
404 | Profile not found |
429 | Rate limit exceeded |
500 | Internal server error |