Users

`DELETE /v1/users/{id}/tokens`

Log a person out everywhere: drop their devices and refuse client tokens issued until now (an agent: revoke all its keys)

Scope: tokens:revoke

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

200 OK

Field	Type	Required	Description
`revoked`	integer

Errors are problem documents with a code.

`GET /v1/users/{id}/friends`

A user’s friends and the friend requests waiting both ways

Scope: users:read

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

200 OK

Field	Type	Required	Description
`friends`	object[]
`incoming`	object[]
`outgoing`	object[]
`friend_policy`	`anyone` \| `confirm` \| `nobody`

Errors are problem documents with a code.

`PUT /v1/users/{id}/friends/{other}`

Make two users friends at once (importing an existing relationship); clears requests between them

Scope: users:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	Developer user id
`other`	path	string	yes	The other user

200 OK

Field	Type	Required	Description
`friends`	boolean
`changed`	boolean

Errors are problem documents with a code.

`DELETE /v1/users/{id}/friends/{other}`

End a friendship

Scope: users:write

Parameter	In	Type	Required	Description
`id`	path	string	yes	Developer user id
`other`	path	string	yes	The other user

200 OK

Field	Type	Required	Description
`friends`	boolean
`changed`	boolean

Errors are problem documents with a code.

`GET /v1/users/{id}/agents`

A person’s agents (never the keys’ secrets)

Scope: agents:read

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

200 OK

Field	Type	Required	Description
`agents`	object[]

Errors are problem documents with a code.

`PUT /v1/users/{id}`

Create or update a user (idempotent). A new agent gets its first key in the response (key, connect), shown once.

Scope: users:write

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

Request body

Field	Type	Required	Description
`id`	string
`kind`	`human` \| `agent`
`owner`	string
`unit`	string
`display_name`	string
`avatar`	string
`fields`	object

200 OK

Field	Type	Description
`id`	string
`kind`	`human` \| `agent`
`owner`	string,null
`unit`	string
`display_name`	string,null
`avatar`	string,null
`fields`	object,null
`deactivated`	boolean
`created_at`	integer
`team`	boolean	A team agent (docs/en/design/agents.md)

Errors are problem documents with a code.

`GET /v1/users/{id}`

Read a user

Scope: users:read

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

200 OK

Field	Type	Description
`id`	string
`kind`	`human` \| `agent`
`owner`	string,null
`unit`	string
`display_name`	string,null
`avatar`	string,null
`fields`	object,null
`deactivated`	boolean
`created_at`	integer
`team`	boolean	A team agent (docs/en/design/agents.md)

Errors are problem documents with a code.

`PATCH /v1/users/{id}`

Change profile and custom fields

Scope: users:write

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

Request body

Field	Type	Required	Description
`display_name`	string
`avatar`	string
`fields`	object

200 OK

Field	Type	Description
`id`	string
`kind`	`human` \| `agent`
`owner`	string,null
`unit`	string
`display_name`	string,null
`avatar`	string,null
`fields`	object,null
`deactivated`	boolean
`created_at`	integer
`team`	boolean	A team agent (docs/en/design/agents.md)

Errors are problem documents with a code.

`DELETE /v1/users/{id}`

Delete the account (GDPR art. 17): at once no sign-in; content erased in the background

Scope: compliance

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

202 Erasure started (or already running or done)

object

Errors are problem documents with a code.

`POST /v1/users/{id}:deactivate`

Deactivate: tokens revoked, connections closed, cannot act

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

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

200 OK

Field	Type	Description
`id`	string
`kind`	`human` \| `agent`
`owner`	string,null
`unit`	string
`display_name`	string,null
`avatar`	string,null
`fields`	object,null
`deactivated`	boolean
`created_at`	integer
`team`	boolean	A team agent (docs/en/design/agents.md)

Errors are problem documents with a code.

`POST /v1/users/{id}:reactivate`

Reactivate

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

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

200 OK

Field	Type	Description
`id`	string
`kind`	`human` \| `agent`
`owner`	string,null
`unit`	string
`display_name`	string,null
`avatar`	string,null
`fields`	object,null
`deactivated`	boolean
`created_at`	integer
`team`	boolean	A team agent (docs/en/design/agents.md)

Errors are problem documents with a code.

`POST /v1/users:batch`

Create or update up to 100 users; one result per item

Scope: users: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
`users`	UserInput[]

200 OK

Field	Type	Required	Description
`results`	ItemResult[]

Errors are problem documents with a code.

`GET /v1/users/{id}/conversations`

A user’s conversations

Scope: conversations:read

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

200 OK

Field	Type	Required	Description
`convs`	object[]

Errors are problem documents with a code.

`GET /v1/users/{id}/devices`

A user’s devices (an agent’s: its keys)

Scope: users:read

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

200 OK

Field	Type	Required	Description
`devices`	Device[]

Errors are problem documents with a code.

`DELETE /v1/users/{id}/devices/{device}`

Log one device out at once: a person’s tokens issued until now are refused on it; an agent’s key is revoked

Scope: tokens:revoke

Parameter	In	Type	Required	Description
`id`	path	string	yes	Developer user id
`device`	path	string	yes	Device id

200 OK

Field	Type	Required	Description
`revoked`	integer

Errors are problem documents with a code.

`POST /v1/users/{id}/messages`

Send to a person: opens the direct conversation if needed

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	Developer user 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/users/{id}/erasure`

Progress of an account deletion

Scope: compliance

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

200 OK

object

Errors are problem documents with a code.

`GET /v1/users/{id}/export`

Export a user’s own data (GDPR art. 15 and 20) as NDJSON

Scope: compliance

Parameter	In	Type	Required	Description
`id`	path	string	yes	Developer user id
`after`	query	string		Continue after this conversation id (the cursor of a conversation line)

200 One JSON object per line

Errors are problem documents with a code.