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