Package {mx.api}

Type:	Package
Title:	Minimal Matrix Client-Server API
Version:	0.3.0
Date:	2026-06-10
Description:	A minimal-dependency client for the 'Matrix' Client-Server HTTP API https://spec.matrix.org/, suitable for talking to a 'Synapse' https://element-hq.github.io/synapse/ or 'Conduit' https://conduit.rs/ homeserver. Covers login, room management, message send and history, media upload or download, and the transport endpoints needed to coordinate end-to-end encryption (device-key and one-time-key publication, key query and claim, to-device events). Encryption itself is out of scope; pair with a separate crypto package.
License:	MIT + file LICENSE
URL:	https://github.com/cornball-ai/mx.api
BugReports:	https://github.com/cornball-ai/mx.api/issues
Imports:	curl, jsonlite
Suggests:	tinytest
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2026-06-10 17:50:22 UTC; troy
Author:	Troy Hernandez [aut, cre], cornball.ai [cph]
Maintainer:	Troy Hernandez <troy@cornball.ai>
Repository:	CRAN
Date/Publication:	2026-06-10 18:00:02 UTC

Minimal Matrix Client-Server API

Description

A minimal-dependency client for the 'Matrix' Client-Server HTTP API <https://spec.matrix.org/>, suitable for talking to a 'Synapse' <https://element-hq.github.io/synapse/> or 'Conduit' <https://conduit.rs/> homeserver. Covers login, room management, message send and history, media upload or download, and the transport endpoints needed to coordinate end-to-end encryption (device-key and one-time-key publication, key query and claim, to-device events). Encryption itself is out of scope; pair with a separate crypto package.

Package Content

Index of help topics:

mx.api-package          Minimal Matrix Client-Server API
mx_canonical_json       Encode a value as Matrix canonical JSON
mx_delete_device        Delete a device
mx_devices              List this account's devices
mx_download             Download a media file by mxc URI
mx_get_account_data     Get account data
mx_get_state            Get a room state event
mx_guess_mime           Guess a MIME type from a file extension
mx_keys_claim           Claim one-time keys for an Olm handshake
mx_keys_query           Query device keys for one or more users
mx_keys_upload          Upload device identity and one-time keys
mx_login                Log in to a Matrix homeserver
mx_logout               Log out of a Matrix session
mx_media_config         Query the homeserver's media configuration
mx_messages             Fetch historical messages from a room
mx_profile              Get a user's profile
mx_react                Send a reaction (annotation) to a room event
mx_read_receipt         Send a read receipt for a room event
mx_redact               Redact an event
mx_register             Register a new account on a Matrix homeserver
mx_room_create          Create a room
mx_room_invite          Invite a user to a room
mx_room_join            Join a room by ID or alias
mx_room_leave           Leave a room
mx_room_members         List the members of a room
mx_room_name            Get a room's human-readable name
mx_room_topic           Get a room's topic
mx_rooms                List rooms the user has joined
mx_send                 Send a message to a room
mx_send_event           Send an arbitrary room event
mx_send_media           Send a media file to a room
mx_send_to_device       Send a to-device event
mx_session              Reconstruct a session from saved credentials
mx_set_account_data     Set account data
mx_set_avatar_url       Set this user's avatar
mx_set_displayname      Set this user's display name
mx_set_state            Set a room state event
mx_sync                 One-shot sync against the homeserver
mx_typing               Send a typing notification
mx_upload               Upload a file to the homeserver media
                        repository
mx_whoami               Return the identity of the current session

Maintainer

Troy Hernandez <troy@cornball.ai>

Author(s)

Troy Hernandez [aut, cre] (ORCID: <https://orcid.org/0009-0005-4248-604X>), cornball.ai [cph]

Encode a value as Matrix canonical JSON

Description

Produces the canonical JSON byte sequence the Matrix specification requires for signed objects: object keys sorted by UTF-8 byte sequence, no insignificant whitespace, raw UTF-8 for non-ASCII strings, integers only (no floats, no exponents, no decimal places, within [-(2^53)+1, (2^53)-1]), and rejection of NaN, Inf, NA values, and NA or duplicate object keys. The output is the exact byte sequence to feed into an ed25519 signer.

Usage

mx_canonical_json(x)

Arguments

Details

R named lists become JSON objects; unnamed lists and length > 1 atomic vectors become arrays. Length-1 atomics become scalars. To force a length-1 value to encode as an array, wrap it in a single-element list(...) or in I() (AsIs values are always encoded as arrays, names dropped, mirroring jsonlite).

Value

A length-1 UTF-8 character string. The result is the exact byte sequence to write to disk or feed to an ed25519 signer; non-ASCII content is preserved as raw UTF-8 bytes (jsonlite-style \uXXXX escaping is not used).

Examples

mx_canonical_json(list(b = 2, a = 1))
# "{\"a\":1,\"b\":2}"

mx_canonical_json(list(key = "abc"))
# "{\"key\":\"abc\"}"

Delete a device

Description

Removes a device and invalidates its access token. Most homeservers protect this with user-interactive authentication: the first call fails with M_FORBIDDEN or a 401 carrying a flows object, and the caller retries with a completed auth payload, e.g. list(type = "m.login.password", identifier = list(type = "m.id.user", user = "bot"), password = "...", session = "<from the 401>"). mx.api deliberately does not automate that exchange.

Usage

mx_delete_device(session, device_id, auth = NULL)

Arguments

Value

Invisibly TRUE on success.

Examples

## Not run: 
mx_delete_device(s, "OLDDEVICE", auth = list(
    type = "m.login.password",
    identifier = list(type = "m.id.user", user = "bot"),
    password = "secret"
))

## End(Not run)

List this account's devices

Description

List this account's devices

Usage

mx_devices(session)

Arguments

Value

A list of devices, each with device_id, display_name, last_seen_ip, and last_seen_ts.

Examples

## Not run: 
vapply(mx_devices(s), function(d) d$device_id, character(1))

## End(Not run)

Download a media file by mxc URI

Description

Download a media file by mxc URI

Usage

mx_download(session, mxc_url, dest)

Arguments

Value

The destination path, invisibly.

Examples

## Not run: 
mx_download(s, "mxc://matrix.example/abc123", tempfile())

## End(Not run)

Get account data

Description

Reads a global account-data event for a user, e.g. "m.direct" (the DM room map) or any custom namespaced type.

Usage

mx_get_account_data(session, type, user_id = session$user_id)

Arguments

Value

The account-data content as a list, or NULL when the type has never been set.

Examples

## Not run: 
direct <- mx_get_account_data(s, "m.direct")

## End(Not run)

Get a room state event

Description

Read-side counterpart of mx_set_state, e.g. to check whether a room is encrypted before joining the send path.

Usage

mx_get_state(session, room_id, event_type, state_key = "")

Arguments

Value

The state event content as a list, or NULL when the state event is not set.

Examples

## Not run: 
enc <- mx_get_state(s, "!abc:example", "m.room.encryption")
is.null(enc)   # FALSE in an encrypted room

## End(Not run)

Guess a MIME type from a file extension

Description

The extension table mx.api uses for uploads, exported so callers do not maintain their own. Unknown extensions fall back to "application/octet-stream".

Usage

mx_guess_mime(path)

Arguments

Value

Character MIME type.

Examples

mx_guess_mime("clip.mp4")
mx_guess_mime("notes.txt")

Claim one-time keys for an Olm handshake

Description

POST /_matrix/client/v3/keys/claim. The one_time_keys argument selects which algorithm to claim for each (user_id, device_id) pair.

Usage

mx_keys_claim(session, one_time_keys, timeout = 10000L)

Arguments

Value

Parsed response with the claimed keys keyed by user_id -> device_id -> "<algorithm>:<key_id>" -> key_object.

Examples

## Not run: 
mx_keys_claim(s, list(
  "@alice:example.org" = list(ABCD1234 = "signed_curve25519")
))

## End(Not run)

Query device keys for one or more users

Description

POST /_matrix/client/v3/keys/query. Each entry in device_keys maps a Matrix user id to a character vector of device ids to request. An empty character vector requests all of the user's devices.

Usage

mx_keys_query(session, device_keys, timeout = 10000L)

Arguments

Value

Parsed response with a device_keys map of user_id -> device_id -> device_keys_object.

Examples

## Not run: 
mx_keys_query(s, list("@alice:example.org" = character()))

## End(Not run)

Upload device identity and one-time keys

Description

POST /_matrix/client/v3/keys/upload. The device_keys and one_time_keys arguments must be fully formed and signed per the Matrix specification; mx.api will not canonicalise or sign them. Use mx_canonical_json to produce the byte sequence to sign.

Usage

mx_keys_upload(session, device_keys = NULL, one_time_keys = NULL,
               fallback_keys = NULL)

Arguments

Value

The parsed homeserver response, including one_time_key_counts.

Examples

## Not run: 
mx_keys_upload(s, device_keys = signed_dk, one_time_keys = signed_otks)

## End(Not run)

Log in to a Matrix homeserver

Description

Authenticates with a Matrix homeserver using password login and returns a session object carrying the access token and device id.

Usage

mx_login(server, user, password, device_id = NULL)

Arguments

Value

An object of class "mx_session".

Examples

## Not run: 
s <- mx_login("https://matrix.example", "alice", "hunter2")

## End(Not run)

Log out of a Matrix session

Description

Invalidates the access token on the homeserver.

Usage

mx_logout(session)

Arguments

Value

Invisible NULL.

Examples

## Not run: 
mx_logout(s)

## End(Not run)

Query the homeserver's media configuration

Description

Asks the server for its media limits, chiefly m.upload.size (maximum upload bytes), so callers can check a file fits before uploading. Tries the v1 endpoint and falls back to the legacy location for older homeservers.

Usage

mx_media_config(session)

Arguments

Value

A list; $`m.upload.size` is the upload cap in bytes (may be absent if the server does not advertise one).

Examples

## Not run: 
cap <- mx_media_config(s)$`m.upload.size`
file.size("clip.mp4") <= cap

## End(Not run)

Fetch historical messages from a room

Description

Thin wrapper over the /rooms/{id}/messages endpoint.

Usage

mx_messages(session, room_id, from = NULL, dir = "b", limit = 50L)

Arguments

Value

A list with fields chunk, start, end.

Examples

## Not run: 
mx_messages(s, "!abc:matrix.example", limit = 20L)

## End(Not run)

Get a user's profile

Description

Get a user's profile

Usage

mx_profile(session, user_id = session$user_id)

Arguments

Value

A list with displayname and avatar_url (either may be absent when unset).

Examples

## Not run: 
mx_profile(s)$displayname

## End(Not run)

Send a reaction (annotation) to a room event

Description

Posts an m.reaction event tying key (usually a thumbs-up or other emoji) to event_id. Matrix reactions are plain events under the hood; they relate to the target via m.annotation.

Usage

mx_react(session, room_id, event_id, key)

Arguments

Value

The event ID of the sent reaction.

Examples

## Not run: 
mx_react(s, "!abc:matrix.example", "$eventid", "thumbs-up")

## End(Not run)

Send a read receipt for a room event

Description

Public receipt (m.read) advances the "seen" marker in other clients; private receipt (m.read.private) only advances the bot's own view. Defaults to public so user clients show "seen by @bot".

Usage

mx_read_receipt(session, room_id, event_id,
                receipt_type = c("m.read", "m.read.private"))

Arguments

Value

Invisible NULL.

Examples

## Not run: 
mx_read_receipt(s, "!abc:matrix.example", "$eventid")

## End(Not run)

Redact an event

Description

Removes the content of a message, reaction, or other event. This is how Matrix deletes things.

Usage

mx_redact(session, room_id, event_id, reason = NULL, txn_id = NULL)

Arguments

Value

The event ID of the redaction event.

Examples

## Not run: 
mx_redact(s, "!abc:example", "$someevent", reason = "typo")

## End(Not run)

Register a new account on a Matrix homeserver

Description

Creates a new user via POST /_matrix/client/v3/register using the m.login.dummy auth flow. Most homeservers only accept this when open registration is enabled (or a registration token is supplied). On success returns a ready-to-use mx_session — registration also logs the new user in.

Usage

mx_register(server, username, password, device_id = NULL,
            initial_device_display_name = NULL, inhibit_login = FALSE)

Arguments

Value

An mx_session object on login, or a list with user_id when inhibit_login = TRUE.

Examples

## Not run: 
s <- mx_register("https://matrix.example", "alice", "hunter2")

## End(Not run)

Create a room

Description

Create a room

Usage

mx_room_create(session, name = NULL, topic = NULL, visibility = "private",
               preset = NULL, invite = character())

Arguments

Value

The new room ID as a character string.

Examples

## Not run: 
room_id <- mx_room_create(s, name = "test", topic = "hello")

## End(Not run)

Invite a user to a room

Description

Invitation at creation time is covered by mx_room_create(); this covers the other common lifecycle case, inviting into an existing room.

Usage

mx_room_invite(session, room_id, user_id)

Arguments

Value

Invisibly TRUE on success.

Examples

## Not run: 
mx_room_invite(s, "!abc:example", "@friend:example.org")

## End(Not run)

Join a room by ID or alias

Description

Join a room by ID or alias

Usage

mx_room_join(session, room)

Arguments

Value

The joined room ID.

Examples

## Not run: 
mx_room_join(s, "#general:matrix.example")

## End(Not run)

Leave a room

Description

Leave a room

Usage

mx_room_leave(session, room_id)

Arguments

Value

Invisible NULL.

Examples

## Not run: 
mx_room_leave(s, "!abc:matrix.example")

## End(Not run)

List the members of a room

Description

List the members of a room

Usage

mx_room_members(session, room_id)

Arguments

Value

Character vector of Matrix user IDs currently joined.

Examples

## Not run: 
mx_room_members(s, "!abc:matrix.example")

## End(Not run)

Get a room's human-readable name

Description

Reads the m.room.name state event. Returns NULL if the room has no name set or the state event is inaccessible.

Usage

mx_room_name(session, room_id)

Arguments

Value

Character scalar or NULL.

Examples

## Not run: 
mx_room_name(s, "!abc:matrix.example")

## End(Not run)

Get a room's topic

Description

Reads the m.room.topic state event. Returns NULL if the room has no topic set or the state event is inaccessible.

Usage

mx_room_topic(session, room_id)

Arguments

Value

Character scalar or NULL.

Examples

## Not run: 
mx_room_topic(s, "!abc:matrix.example")

## End(Not run)

List rooms the user has joined

Description

List rooms the user has joined

Usage

mx_rooms(session)

Arguments

Value

Character vector of room IDs.

Examples

## Not run: 
mx_rooms(s)

## End(Not run)

Send a message to a room

Description

Send a message to a room

Usage

mx_send(session, room_id, body, msgtype = "m.text", extra = NULL)

Arguments

Value

The event ID of the sent message.

Examples

## Not run: 
mx_send(s, "!abc:matrix.example", "hello world")

## End(Not run)

Send an arbitrary room event

Description

Generic counterpart to mx_send for event types other than m.room.message, such as m.room.encrypted. The content is sent verbatim.

Usage

mx_send_event(session, room_id, event_type, content, txn_id = NULL)

Arguments

Value

The event ID of the sent event.

Examples

## Not run: 
mx_send_event(s, "!abc:example", "m.room.encrypted", encrypted_content)

## End(Not run)

Send a media file to a room

Description

Uploads path to the media repository and posts an m.room.message referencing it. The default info carries mimetype and size; pass richer metadata (width, height, duration) yourself – mx.api deliberately does not inspect media files.

Usage

mx_send_media(session, room_id, path, body = basename(path), msgtype = NULL,
              content_type = NULL, info = list())

mx_send_file(session, room_id, path, body = basename(path),
             content_type = NULL, info = list())

mx_send_image(session, room_id, path, body = basename(path),
              content_type = NULL, info = list())

mx_send_audio(session, room_id, path, body = basename(path),
              content_type = NULL, info = list())

mx_send_video(session, room_id, path, body = basename(path),
              content_type = NULL, info = list())

Arguments

Value

The event ID of the sent message.

Examples

## Not run: 
mx_send_media(s, "!abc:example", "clip.mp4", msgtype = "m.video")

## End(Not run)

Send a to-device event

Description

PUT /_matrix/client/v3/sendToDevice/{eventType}/{txnId}. Used to ship encrypted Olm payloads (e.g. m.room_key carriers wrapped as m.room.encrypted) to specific (user_id, device_id) targets.

Usage

mx_send_to_device(session, event_type, messages, txn_id = NULL)

Arguments

Value

Invisible NULL (the server returns an empty body on success).

Examples

## Not run: 
mx_send_to_device(s, "m.room.encrypted", list(
  "@bob:example.org" = list(BBBB = encrypted_content)
))

## End(Not run)

Reconstruct a session from saved credentials

Description

Reconstruct a session from saved credentials

Usage

mx_session(server, token, user_id, device_id)

Arguments

Value

An object of class "mx_session".

Examples

s <- mx_session(
    server = "https://matrix.example",
    token = "syt_...",
    user_id = "@alice:matrix.example",
    device_id = "ABC123"
)

Set account data

Description

Writes a global account-data event for a user. The content replaces whatever was stored under type.

Usage

mx_set_account_data(session, type, content, user_id = session$user_id)

Arguments

Value

Invisibly TRUE on success.

Examples

## Not run: 
mx_set_account_data(s, "ai.cornball.notes", list(theme = "dark"))

## End(Not run)

Set this user's avatar

Description

Set this user's avatar

Usage

mx_set_avatar_url(session, avatar_url)

Arguments

Value

Invisibly TRUE on success.

Examples

## Not run: 
uri <- mx_upload(s, "avatar.png")
mx_set_avatar_url(s, uri)

## End(Not run)

Set this user's display name

Description

Set this user's display name

Usage

mx_set_displayname(session, displayname)

Arguments

Value

Invisibly TRUE on success.

Examples

## Not run: 
mx_set_displayname(s, "cornelius")

## End(Not run)

Set a room state event

Description

Generic state setter, e.g. to mark a room encrypted by putting an m.room.encryption event.

Usage

mx_set_state(session, room_id, event_type, content, state_key = "")

Arguments

Value

The event ID of the state event.

Examples

## Not run: 
mx_set_state(s, "!abc:example", "m.room.encryption",
             list(algorithm = "m.megolm.v1.aes-sha2"))

## End(Not run)

One-shot sync against the homeserver

Description

Calls /sync once and returns immediately. For streaming behaviour, the caller writes its own loop, passing the previous batch's next_batch token as since.

Usage

mx_sync(session, since = NULL, timeout = 0L, filter = NULL)

Arguments

Value

The parsed sync response, including next_batch.

Examples

## Not run: 
batch <- mx_sync(s)
next_batch <- batch$next_batch

## End(Not run)

Send a typing notification

Description

Shows (or clears) the session user's typing indicator in a room. Useful bot polish while a slow reply is being generated.

Usage

mx_typing(session, room_id, typing = TRUE, timeout = 30000L)

Arguments

Value

Invisibly TRUE on success.

Examples

## Not run: 
mx_typing(s, "!abc:example", TRUE)
# ... generate the reply ...
mx_typing(s, "!abc:example", FALSE)

## End(Not run)

Upload a file to the homeserver media repository

Description

Upload a file to the homeserver media repository

Usage

mx_upload(session, path, content_type = NULL, filename = NULL)

Arguments

Value

An "mxc://" URI as a character string.

Examples

## Not run: 
uri <- mx_upload(s, "photo.png")

## End(Not run)

Return the identity of the current session

Description

Return the identity of the current session

Usage

mx_whoami(session)

Arguments

Value

A list with user_id and device_id.

Examples

## Not run: 
mx_whoami(s)

## End(Not run)