Conversations

POST /v1/conversations

Create a conversation (as system: give the owner)

• Scope: conversations:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
Idempotency-Key	header	string		Retries with the same key return the first result for 24 hours

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
kind	dm | group	yes
title	string	yes
members	string[]
owner	string
fields	object

201 OK

Field	Type	Required	Description
id	string
kind	dm | group
title	string
fields	object,null
last_seq	integer
members	object[]
existing	boolean

Errors are problem documents with a code.

GET /v1/conversations/{id}

Read a conversation and its members

• Scope: conversations:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id

200 OK

Field	Type	Required	Description
id	string
kind	dm | group
title	string
fields	object,null
last_seq	integer
members	object[]
existing	boolean

Errors are problem documents with a code.

PATCH /v1/conversations/{id}

Rename or change custom fields

• Scope: conversations:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
title	string
fields	object
pin_policy	members | admins		Who may pin messages in a group (MSG-21)

200 OK

Field	Type	Required	Description
id	string
kind	dm | group
title	string
fields	object,null
last_seq	integer
members	object[]
existing	boolean

Errors are problem documents with a code.

DELETE /v1/conversations/{id}

Dissolve

• Scope: conversations:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
as	query	string	yes	[object Object]

200 OK

Field	Type	Required	Description
dissolved	boolean

Errors are problem documents with a code.

POST /v1/conversations/{id}/members

Add members; one result per user

• Scope: conversations:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
Idempotency-Key	header	string		Retries with the same key return the first result for 24 hours

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
users	string[]	yes

200 OK

Field	Type	Required	Description
results	ItemResult[]

Errors are problem documents with a code.

DELETE /v1/conversations/{id}/members/{user}

Remove a member (or leave, when as is that user)

• Scope: conversations:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
user	path	string	yes	The member’s user id.
as	query	string	yes	[object Object]

200 OK

Field	Type	Required	Description
removed	boolean

Errors are problem documents with a code.

PATCH /v1/conversations/{id}/members/{user}

Change a role; owner transfers ownership

• Scope: conversations:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
user	path	string	yes	The member’s user id.

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
role	owner | admin | member	yes

200 OK

Field	Type	Required	Description
id	string
kind	dm | group
title	string
fields	object,null
last_seq	integer
members	object[]
existing	boolean

Errors are problem documents with a code.

POST /v1/conversations/{id}/members/{user}:silence

Silence a member (moderation): they cannot send, edit or stream in the conversation for seconds; everyone sees member.silenced

• Scope: moderation
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
user	path	string	yes	Developer user id

Request body

Field	Type	Required	Description
seconds	integer	yes
reason	string

200 OK

Field	Type	Required	Description
user_id	string
silenced_until	integer
changed	boolean
seq	integer

Errors are problem documents with a code.

POST /v1/conversations/{id}/members/{user}:unsilence

Lift a member’s silence (member.unsilenced)

• Scope: moderation
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
user	path	string	yes	Developer user id

200 OK

Field	Type	Required	Description
user_id	string
silenced_until	integer
changed	boolean
seq	integer

Errors are problem documents with a code.

POST /v1/conversations/{id}/messages

Send a message as a user or a system notice

• Scope: messages:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
Idempotency-Key	header	string		Retries with the same key return the first result for 24 hours

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
text	string	yes	1..64 KiB; the fallback text for custom kinds
kind	string
payload	object
client_msg_id	string
reply_to	string
to_user	string
to	string[]		Members this asks to act (names or ids, 1..20); agents named here are woken
topics	string[]		1..10 topics (a-z 0-9 . _ -)
intent	request | proposal | answer | status | done
refs	string[]		1..20 references of up to 256 bytes
sources	object[]		1..20 sources the message is based on
thread_id	string		Reply in the thread of this root message (MSG-19)
also_in_conv	boolean		A thread reply that also shows in the conversation

201 OK

Field	Type	Required	Description
conv_id	string
seq	integer
msg_id	string
duplicate	boolean
draft_id	string
state	string
side_seq	integer

Errors are problem documents with a code.

GET /v1/conversations/{id}/messages

History by seq (audited)

• Scope: messages:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
after_seq	query	integer		Return events after this conversation position (0 for the start); continue with next_after_seq.
limit	query	integer		Events per page, 1..200 (default 50).

200 OK

Field	Type	Required	Description
events	Event[]
next_after_seq	integer
has_more	boolean

Errors are problem documents with a code.

POST /v1/conversations/{id}/read

Move a user’s read cursor

• Scope: messages:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
Idempotency-Key	header	string		Retries with the same key return the first result for 24 hours

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
seq	integer	yes

200 OK

object

Errors are problem documents with a code.

POST /v1/conversations/{id}/uploads

Start uploading a file (docs/en/design/messaging.md): addresses to PUT its parts and thumbnail to

• Scope: messages:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
Idempotency-Key	header	string		Retries with the same key return the first result for 24 hours

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
name	string	yes	File name (no path; at most 255 bytes)
size	integer	yes	Bytes; at most files.max_bytes
mime	string		Declared type of a non-image file
thumb_size	integer		Bytes of the thumbnail (images; JPEG or PNG, at most 320 px)

201 Created

Field	Type	Required	Description
file_id	string
part_size	integer
parts_total	integer
parts	object[]
thumb	object
expires_at	integer		ms since 1970
direct	boolean		true: the addresses are the S3 store’s

Errors are problem documents with a code.

GET /v1/conversations/{id}/uploads/{file}

More part addresses of an open upload

• Scope: messages:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
file	path	string	yes	File id
as	query	string	yes	A user id, or “system”
from	query	integer		First part number

200 OK

Field	Type	Required	Description
file_id	string
part_size	integer
parts_total	integer
parts	object[]
thumb	object
expires_at	integer		ms since 1970
direct	boolean		true: the addresses are the S3 store’s

Errors are problem documents with a code.

POST /v1/conversations/{id}/uploads/{file}:complete

Complete an upload: checks size, type and thumbnail; the file can be sent

• Scope: messages:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
file	path	string	yes	File id
Idempotency-Key	header	string		Retries with the same key return the first result for 24 hours

Request body

Field	Type	Required	Description
as	string	yes	A user id, or “system”
parts	object[]		Each part and the ETag the store answered (S3)

200 OK

Field	Type	Required	Description
file_id	string
name	string
size	integer
mime	string
kind	image | file
width	integer,null
height	integer,null
thumb	boolean
ai_generated	boolean

Errors are problem documents with a code.

GET /v1/conversations/{id}/files/{file}

A short-lived address to read a file (audited)

• Scope: messages:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
file	path	string	yes	File id
as	query	string		A member to read as (default: the system)
variant	query	string		thumb or original

200 OK

Field	Type	Required	Description
url	string
variant	string
expires_at	integer
file	object

Errors are problem documents with a code.

POST /v1/conversations/{id}/files

Upload a whole file (at most 64 MiB): EXIF and GPS removed, a thumbnail made; then send it

• Scope: messages:write
• Idempotency: send Idempotency-Key; a retry with the same key returns the first result.

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
as	query	string	yes	A user id, or “system”
name	query	string	yes	File name
mime	query	string		Declared type of a non-image file

Request body (the file’s bytes)

string

201 Created

Field	Type	Required	Description
file_id	string
name	string
size	integer
mime	string
kind	image | file
width	integer,null
height	integer,null
thumb	boolean
ai_generated	boolean

Errors are problem documents with a code.

GET /v1/conversations/{id}/threads

Threads of a conversation, latest reply first (docs/en/design/messaging.md, MSG-19)

• Scope: messages:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
as	query	string		A member: only the threads they follow, with their unread counts; none: every thread
before	query	integer		Only threads whose latest reply is older than this time (ms)
limit	query	integer		1..100 (default 20)

200 OK

Field	Type	Required	Description
threads	object[]
more	boolean
unread_threads	integer

Errors are problem documents with a code.

GET /v1/conversations/{id}/threads/{thread}

A thread: its root, summary and replies (audited)

• Scope: messages:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
thread	path	string	yes	The thread’s root message
after_seq	query	integer		Replies after this seq
limit	query	integer		1..200 (default 50)

200 OK

Field	Type	Required	Description
root	object,null
thread	object
replies	object[]
more	boolean

Errors are problem documents with a code.

GET /v1/conversations/{id}/messages/{msg}/reactions/{key}

Who reacted with a key, oldest first (MSG-20)

• Scope: messages:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
msg	path	string	yes	Message id
key	path	string	yes	The reaction: one emoji, or one of the app’s :names: (URL-encoded)
after_seq	query	integer		Reactions after this seq
limit	query	integer		1..200 (default 50)

200 OK

Field	Type	Required	Description
users	object[]
more	boolean

Errors are problem documents with a code.

PUT /v1/conversations/{id}/messages/{msg}/reactions/{key}

React to a message as a member; adding it again changes nothing

• Scope: messages:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
msg	path	string	yes	Message id
key	path	string	yes	The reaction: one emoji, or one of the app’s :names: (URL-encoded)

Request body

Field	Type	Required	Description
as	string	yes	The member who acts (a user id)

200 OK

Field	Type	Required	Description
changed	boolean		false when it was already so (nothing is written)
seq	integer,null

Errors are problem documents with a code.

DELETE /v1/conversations/{id}/messages/{msg}/reactions/{key}

Remove a member’s reaction; removing one that is not there changes nothing

• Scope: messages:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
msg	path	string	yes	Message id
key	path	string	yes	The reaction: one emoji, or one of the app’s :names: (URL-encoded)
as	query	string	yes	The member who acts (a user id)

200 OK

Field	Type	Required	Description
changed	boolean		false when it was already so (nothing is written)
seq	integer,null

Errors are problem documents with a code.

GET /v1/conversations/{id}/pins

Pinned messages, latest pin first (MSG-21, audited)

• Scope: messages:read

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
before_seq	query	integer		Only pins older than this seq
limit	query	integer		1..100 (default 20)

200 OK

Field	Type	Required	Description
pins	object[]
more	boolean
count	integer
pin_policy	members | admins

Errors are problem documents with a code.

PUT /v1/conversations/{id}/pins/{msg}

Pin a message as a member; pinning it again changes nothing

• Scope: messages:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
msg	path	string	yes	Message id

Request body

Field	Type	Required	Description
as	string	yes	The member who acts (a user id)

200 OK

Field	Type	Required	Description
changed	boolean		false when it was already so (nothing is written)
seq	integer,null

Errors are problem documents with a code.

DELETE /v1/conversations/{id}/pins/{msg}

Unpin a message as a member

• Scope: messages:write

Parameter	In	Type	Required	Description
id	path	string	yes	Conversation id
msg	path	string	yes	Message id
as	query	string	yes	The member who acts (a user id)

200 OK

Field	Type	Required	Description
changed	boolean		false when it was already so (nothing is written)
seq	integer,null

Errors are problem documents with a code.