HTTP API
POST /v1/sessions/sdk
Start a session from the SDK with the app’s publishable key: a guest, or a signed-in person by the host’s token
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
guest_token |
string | |
user_token |
string |
Answers: 201
POST /v1/sessions
Mint a Rafiq session for one client and one person, with an app secret or a client’s key
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
external_ref |
string | |
name |
string | |
subject |
string | yes |
subject_name |
string | |
scopes |
string[] | |
ttl_seconds |
integer |
Answers: 201
GET /v1/sessions/me
The session the bearer token is: its app, client, person and scopes
Sent with: authorization
Answers: 200
GET /v1/connections/tools
The tools the session’s app and client can use
Sent with: authorization
Answers: 200
GET /v1/chats
The caller’s chats, the latest first
Sent with: authorization
Answers: 200
POST /v1/chats
Start a chat
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
title |
string | |
language |
en · ar |
|
members |
ChatMemberIn[] |
Answers: 201
GET /v1/chats/events
When the caller’s chat list changes, as it happens (server-sent events)
Sent with: authorization
Answers: 200
GET /v1/chats/{chat_id}
A chat from a message on, with its run
Sent with: authorization
Answers: 200
PATCH /v1/chats/{chat_id}
Rename a chat, archive it or bring it back, or switch it between private and team
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
title |
string | |
archived |
boolean | |
visibility |
private · team |
Answers: 200
DELETE /v1/chats/{chat_id}
Delete a chat, for everyone
Sent with: authorization
Answers: 204
GET /v1/chats/{chat_id}/events
What happens in the chat, as it happens (server-sent events)
Sent with: authorization
Answers: 200
POST /v1/chats/{chat_id}/read
Read up to a message
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
seq |
integer | yes |
Answers: 204
POST /v1/chats/{chat_id}/typing
Say the caller is writing in the chat, for a few seconds
Sent with: authorization
Answers: 204
GET /v1/chats/{chat_id}/members
Who is in the chat
Sent with: authorization
Answers: 200
POST /v1/chats/{chat_id}/members
Add someone to the chat
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
subject |
string | yes |
name |
string |
Answers: 201
DELETE /v1/chats/{chat_id}/members/{subject}
Remove someone from the chat, or leave it
Sent with: authorization
Answers: 204
POST /v1/chats/{chat_id}/messages
Write to the team or to the AI
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
text |
string | |
to |
team · ai |
|
mentions |
ChatMentionIn[] | |
things |
ChatThingIn[] | |
attachments |
string (uuid)[] | |
reply_to |
string (uuid) | |
request_id |
string | |
tools |
AppToolIn[] |
Answers: 201
PATCH /v1/chats/{chat_id}/messages/{message_id}
Edit one’s own message
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
text |
string | yes |
rerun |
boolean |
Answers: 200
PUT /v1/chats/{chat_id}/messages/{message_id}/rating
Rate one of the AI’s answers: a thumbs up or down, with what was wrong
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
value |
up · down |
yes |
comment |
string |
Answers: 200
DELETE /v1/chats/{chat_id}/messages/{message_id}/rating
Take the caller’s rating of an answer back
Sent with: authorization
Answers: 204
POST /v1/chats/{chat_id}/messages/{message_id}/regenerate
Set the AI’s answer aside and ask again
Sent with: authorization
Answers: 202
POST /v1/chats/{chat_id}/answers
Answer the part a run waits on, or press a view’s button
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
message_id |
string (uuid) | yes |
part_id |
string | yes |
value |
yes |
Answers: 200
POST /v1/chats/{chat_id}/runs/{run_id}/tool-result
The app’s answer to the call a run handed it
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
id |
string | yes |
content |
string | yes |
is_error |
boolean |
Answers: 200
POST /v1/chats/{chat_id}/messages/{message_id}/unsend
Take back one’s newest message: it and what its run wrote after it go, the run stops
Sent with: authorization
Answers: 200
POST /v1/chats/{chat_id}/runs/{run_id}/stop
Stop a run
Sent with: authorization
Answers: 200
POST /v1/chats/{chat_id}/files
Upload an image, a file or a voice note: the raw body, with its Content-Type
Sent with: content-type, content-length, authorization
Answers: 201
GET /v1/chats/files/{signed}
A chat’s file, for whoever holds a link from a read
Answers: 200
POST /v1/chats/{chat_id}/messages/{message_id}/teach
Teach the assistant: save a message or an answer as the client’s knowledge
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
title |
string |
Answers: 201
POST /v1/agui
Run the chat named by threadId over AG-UI: its events, as Server-Sent Events
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
threadId |
string | yes |
runId |
string | yes |
protocolVersion |
string | |
parentRunId |
string | |
state |
||
messages |
DeveloperMessage or SystemMessage or AssistantMessage or UserMessage or ToolMessage or ActivityMessage or ReasoningMessage[] | yes |
tools |
Tool[] | |
context |
Context[] | |
forwardedProps |
||
resume |
ResumeEntry[] |
Answers: 200
GET /v1/mentions
Where the caller was mentioned and hasn’t read yet
Sent with: authorization
Answers: 200
GET /v1/people
The people of the caller’s client a message can mention
Sent with: authorization
Answers: 200
GET /v1/things
The things the caller can point at in a message
Sent with: authorization
Answers: 200
GET /v1/usage-limits
How much AI the caller’s org has left today and this week
Sent with: authorization
Answers: 200
GET /v1/app
The app the session is in, its look, and the client’s settings
Sent with: authorization
Answers: 200
GET /v1/design/bundle
The app’s design: its theme, components and templates (ETag)
Sent with: if-none-match, authorization
Answers: 200, 304
GET /v1/settings
The client’s settings for its assistant
Sent with: authorization
Answers: 200
PATCH /v1/settings
Change the client’s settings
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
language |
en · ar |
|
assistant_name |
string | |
instructions |
string |
Answers: 200
GET /v1/knowledge
The client’s own AI knowledge
Sent with: authorization
Answers: 200
POST /v1/knowledge
Add something the assistant knows
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
title |
string | yes |
facts |
string | yes |
enabled |
boolean |
Answers: 201
PUT /v1/knowledge/{entry_id}
Change an entry, or switch it off
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
title |
string | yes |
facts |
string | yes |
enabled |
boolean |
Answers: 200
GET /v1/skills
The client’s private Skills
Sent with: authorization
Answers: 200
POST /v1/skills
Add Skill
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
name |
string | yes |
content |
string | yes |
trigger_words |
string[] | |
facts |
string | yes |
apply_to |
text · image · video[] |
|
when |
always · matching · on_request |
|
status |
active · inactive |
Answers: 201
PUT /v1/skills/{skill_id}
Change Skill
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
name |
string | yes |
content |
string | yes |
trigger_words |
string[] | |
facts |
string | yes |
apply_to |
text · image · video[] |
|
when |
always · matching · on_request |
|
status |
active · inactive |
|
revision |
integer | yes |
Answers: 200
Identity, events and consent
Every SDK sends the person’s identity, events and consent here, with the same publishable key.
POST /sdk/v1/identify
Who the app’s user is; email and phone are hashed on arrival
Sent with: X-User-Hash, X-App-Install, X-App-Key
Body
| Field | Type | Required |
|---|---|---|
external_id |
string | |
email |
string | |
phone |
string | |
email_sha256 |
string | |
phone_sha256 |
string | |
attributes |
object |
Answers: 200
POST /sdk/v1/events
What the identified user did
Sent with: X-User-Hash, X-App-Key
Body
| Field | Type | Required |
|---|---|---|
external_id |
string | yes |
events |
EventIn[] | yes |
Answers: 200
PUT /sdk/v1/consent
What the user agreed to, per channel
Sent with: X-User-Hash, X-App-Key
Body
| Field | Type | Required |
|---|---|---|
external_id |
string | yes |
channel |
push · in_app · email · whatsapp · sms · telegram |
yes |
granted |
boolean | yes |
occurred_at |
string (date-time) |
Answers: 200
POST /sdk/v1/install/events
What the app’s user did before the app identified them
Sent with: X-App-Install, X-App-Key
Body
| Field | Type | Required |
|---|---|---|
events |
EventIn[] | yes |
Answers: 200
PUT /sdk/v1/install/consent
What the app’s user agreed to before the app identified them
Sent with: X-App-Install, X-App-Key
Body
| Field | Type | Required |
|---|---|---|
channel |
push · in_app · email · whatsapp · sms · telegram |
yes |
granted |
boolean | yes |
occurred_at |
string (date-time) |
Answers: 200
POST /server/v1/identify
Create or update a profile by the match rule
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
external_id |
string | |
email |
string | |
phone |
string | |
email_sha256 |
string | |
phone_sha256 |
string | |
attributes |
object |
Answers: 200
POST /server/v1/events
Events, each naming its person
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
events |
ServerEventIn[] | yes |
Answers: 200
POST /server/v1/orders
Orders; one sent again by its order_id is updated
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
orders |
OrderIn[] | yes |
Answers: 200
PUT /server/v1/consent
What a person agreed to, per channel
Sent with: authorization
Body
| Field | Type | Required |
|---|---|---|
external_id |
string | yes |
channel |
push · in_app · email · whatsapp · sms · telegram |
yes |
granted |
boolean | yes |
occurred_at |
string (date-time) |
Answers: 200
POST /server/v1/import
A batch of end users as text/csv or application/json (at most 10,000 rows)
Sent with: authorization
Answers: 200
GET /server/v1/profiles/{external_id}
A person, by the org’s external id
Sent with: authorization
Answers: 200
DELETE /server/v1/profiles/{external_id}
Delete a person and everything about them; every service forgets them too
Sent with: authorization
Answers: 204