The same consultant that works in the cabinet is available from your app. You create a session, open the stream, send a message and receive the answer in parts. Needs the tools:chat scope.
How it works
- Create a session - it keeps the conversation context.
- Open the session's event stream.
- Send a message.
- The answer arrives in the stream in parts until it is complete.
Open the stream before sending the message, otherwise the first parts of the answer pass you by.
Sessions
| Request | What it does |
|---|---|
POST /chat/sessions | create a session |
GET /chat/sessions | your sessions: limit 1-50 (default 20, more is 400), cursor, q (search in titles), projectId, archivedOnly, sort (recent, title) |
PATCH /chat/sessions/{id} | change a session; at least one field |
DELETE /chat/sessions/{id} | archive |
POST /chat/sessions body (all optional):
| Field | Description |
|---|---|
title | session name, up to 200 characters |
projectId | project the session belongs to |
mode | chat_consult (default); any other value is replaced with chat_consult |
PATCH /chat/sessions/{id} fields:
| Field | Description |
|---|---|
title | new name, up to 200 characters |
projectId | move to a project; null - out of the project |
isPinned | pin or unpin |
isUnread | mark as unread or read |
isArchived | only false - restore an archived session; archive with DELETE |
curl -X POST https://developers.grem.capital/api/v1/chat/sessions \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"title":"Client question about a mortgage"}'
The response holds sessionId - pass it to every following call. Creating a session needs a completed account profile; without one - 400.
The API offers the general consultant mode. The auto-responder mode that works inside the cabinet CRM cannot be switched on from outside.
Send a message
curl -X POST https://developers.grem.capital/api/v1/chat/messages \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"sessionId":"SESSION_ID","text":"How much is a 2-room flat in Podil?","clientMessageId":"msg-0001"}'
clientMessageId- your required message id. The same id is answered and charged once - reuse it when you retry; it is the chat'sIdempotency-Key.style(optional) - answer length:short,normalordetailed.
The response is only an acknowledgement; the assistant's answer comes through the stream.
Response stream
GET /chat/stream?sessionId=SESSION_ID
Authorization: Bearer gsk_live_xxx
Accept: text/event-stream
The connection is long-lived; events arrive as the answer is generated:
| Event | Meaning |
|---|---|
assistant.started | the assistant began answering |
assistant.delta | the next piece of text, in delta |
assistant.done | the answer is complete, the full text is in text |
If the connection drops, reconnect with the same sessionId: the server replays the current answer from the start. So on assistant.started clear the text you accumulated for this message, or it will double up.
History
GET /chat/history?sessionId=SESSION_ID&limit=50 - the session's stored messages, oldest first. limit 1 to 200 (default 50); the next page - cursor with nextCursor from the previous answer. Use it to restore the conversation after your UI reloads.
Billing
| Action | Charge |
|---|---|
POST /chat/messages | API call + message price |
POST, PATCH, DELETE on sessions | API call |
GET list, history, stream | free |
The Free plan has a daily message limit. After it you get 429 - continue tomorrow or change the plan. The answer carries code: free_daily_limit and Retry-After until 00:00 UTC, when the limit resets.
Related
- TypeScript SDK - a ready client with stream support.
- Limits and billing
- Errors