Skip to content

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

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