{ "openapi": "3.0.3", "info": { "title": "Matrix Client-Server API (Curated)", "version": "1.0.0", "description": "Curated Matrix client-server OpenAPI schema for common read/write workflows through UXC." }, "servers": [ { "url": "https://matrix.org/_matrix/client/v3", "description": "Example Matrix homeserver client-server base URL. Replace with your own homeserver base when linking UXC." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/account/whoami": { "get": { "operationId": "get:/account/whoami", "summary": "Get information about the owner of an access token.", "description": "Returns the user ID and optional device metadata for the supplied access token.", "tags": [ "session" ], "responses": { "200": { "description": "The token belongs to a known user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmIResponse" } } } }, "401": { "description": "The access token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/joined_rooms": { "get": { "operationId": "get:/joined_rooms", "summary": "List the rooms the user is currently joined to.", "description": "Returns the room IDs for the current user membership state of join.", "tags": [ "rooms" ], "responses": { "200": { "description": "A list of room IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinedRoomsResponse" } } } }, "401": { "description": "The access token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/rooms/{roomId}/state": { "get": { "operationId": "get:/rooms/{roomId}/state", "summary": "Get all state events in the current state of a room.", "description": "Returns the room's current state events visible to the access token.", "tags": [ "rooms" ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "description": "The Matrix room ID, for example `!room:example.org`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The current state events for the room.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixStateEvent" } } } } }, "401": { "description": "The access token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller cannot view the room state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/rooms/{roomId}/state/{eventType}/{stateKey}": { "get": { "operationId": "get:/rooms/{roomId}/state/{eventType}/{stateKey}", "summary": "Get a specific state event by type and state key.", "description": "Returns the content object for a specific state event in the room.", "tags": [ "rooms" ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "description": "The Matrix room ID, for example `!room:example.org`.", "schema": { "type": "string" } }, { "name": "eventType", "in": "path", "required": true, "description": "The Matrix event type, for example `m.room.topic`.", "schema": { "type": "string" } }, { "name": "stateKey", "in": "path", "required": true, "description": "The Matrix state key. Use the empty string when the state event type requires an empty state key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The event content object.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "The access token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller cannot view the requested state event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The room or event state was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sync": { "get": { "operationId": "get:/sync", "summary": "Synchronise the client's state and receive updates.", "description": "Performs a request/response sync against the homeserver. This is normal invocation only and not a background subscription runtime.", "tags": [ "sync" ], "parameters": [ { "name": "filter", "in": "query", "description": "A filter ID or a full JSON filter encoded as a string.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "description": "A sync token from a previous `/sync` response.", "schema": { "type": "string" } }, { "name": "full_state", "in": "query", "description": "When true, return the full state for joined rooms.", "schema": { "type": "boolean" } }, { "name": "set_presence", "in": "query", "description": "Set the client's presence for this sync request.", "schema": { "type": "string", "enum": [ "offline", "online", "unavailable" ] } }, { "name": "timeout", "in": "query", "description": "Long-poll timeout in milliseconds.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "A sync snapshot plus a token for the next request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncResponse" } } } }, "401": { "description": "The access token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "This request was rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedError" } } } } } } }, "/profile/{userId}": { "get": { "operationId": "get:/profile/{userId}", "summary": "Get all profile information for a user.", "description": "Returns common profile fields such as display name and avatar URL.", "tags": [ "profile" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The Matrix user ID, for example `@alice:example.org`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user's profile information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } }, "404": { "description": "The user profile was not found or is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/presence/{userId}/status": { "get": { "operationId": "get:/presence/{userId}/status", "summary": "Get the presence state for a user.", "description": "Returns presence, optional status message, and activity hints for the given user.", "tags": [ "presence" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The Matrix user ID, for example `@alice:example.org`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user's presence state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceStatus" } } } }, "401": { "description": "The access token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller cannot view the presence state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/rooms/{roomId}/send/{eventType}/{txnId}": { "put": { "operationId": "put:/rooms/{roomId}/send/{eventType}/{txnId}", "summary": "Send a message event to a room.", "description": "Sends an event content object to the room using a client-generated transaction ID for idempotency.", "tags": [ "rooms" ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "description": "The Matrix room ID, for example `!room:example.org`.", "schema": { "type": "string" } }, { "name": "eventType", "in": "path", "required": true, "description": "The Matrix event type, typically `m.room.message` for chat messages.", "schema": { "type": "string" } }, { "name": "txnId", "in": "path", "required": true, "description": "A client-generated transaction ID used for idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEventRequest" }, "example": { "msgtype": "m.text", "body": "Hello from UXC" } } } }, "responses": { "200": { "description": "The event was accepted and assigned an event ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEventResponse" } } } }, "400": { "description": "The request body or parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller cannot send this event into the room.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Matrix access token sent as `Authorization: Bearer `." } }, "schemas": { "WhoAmIResponse": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "The Matrix user ID that owns the access token." }, "device_id": { "type": "string", "description": "The device ID associated with the access token, when present." }, "is_guest": { "type": "boolean", "description": "Whether the token belongs to a guest user." } }, "additionalProperties": false }, "JoinedRoomsResponse": { "type": "object", "required": [ "joined_rooms" ], "properties": { "joined_rooms": { "type": "array", "items": { "type": "string" }, "description": "Room IDs where the user currently has join membership." } }, "additionalProperties": false }, "MatrixStateEvent": { "type": "object", "required": [ "type", "content" ], "properties": { "type": { "type": "string" }, "state_key": { "type": "string" }, "event_id": { "type": "string" }, "room_id": { "type": "string" }, "sender": { "type": "string" }, "origin_server_ts": { "type": "integer", "format": "int64" }, "unsigned": { "type": "object", "additionalProperties": true }, "content": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "TimelineChunk": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixTimelineEvent" } }, "limited": { "type": "boolean" }, "prev_batch": { "type": "string" } }, "additionalProperties": true }, "RoomSyncSection": { "type": "object", "properties": { "state": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixStateEvent" } } }, "additionalProperties": true }, "timeline": { "$ref": "#/components/schemas/TimelineChunk" }, "ephemeral": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixTimelineEvent" } } }, "additionalProperties": true }, "account_data": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixTimelineEvent" } } }, "additionalProperties": true }, "unread_notifications": { "type": "object", "properties": { "notification_count": { "type": "integer" }, "highlight_count": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "SyncResponse": { "type": "object", "required": [ "next_batch" ], "properties": { "next_batch": { "type": "string", "description": "Opaque token to supply as `since` on the next `/sync` call." }, "account_data": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixTimelineEvent" } } }, "additionalProperties": true }, "presence": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixTimelineEvent" } } }, "additionalProperties": true }, "to_device": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixTimelineEvent" } } }, "additionalProperties": true }, "rooms": { "type": "object", "properties": { "join": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RoomSyncSection" } }, "invite": { "type": "object", "additionalProperties": true }, "leave": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RoomSyncSection" } }, "knock": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "UserProfile": { "type": "object", "properties": { "avatar_url": { "type": "string", "description": "The Matrix Content URI (`mxc://...`) for the user's avatar, when present." }, "displayname": { "type": "string", "description": "The user's display name, when present." } }, "additionalProperties": true }, "PresenceStatus": { "type": "object", "required": [ "presence" ], "properties": { "presence": { "type": "string", "enum": [ "online", "offline", "unavailable" ] }, "status_msg": { "type": "string" }, "last_active_ago": { "type": "integer", "format": "int64" }, "currently_active": { "type": "boolean" } }, "additionalProperties": true }, "SendEventRequest": { "type": "object", "description": "The event content object. For chat messages, use Matrix message content such as `{ \"msgtype\": \"m.text\", \"body\": \"Hello\" }`.", "additionalProperties": true, "properties": { "msgtype": { "type": "string" }, "body": { "type": "string" }, "m.relates_to": { "type": "object", "additionalProperties": true } } }, "SendEventResponse": { "type": "object", "required": [ "event_id" ], "properties": { "event_id": { "type": "string", "description": "The event ID assigned by the homeserver." } }, "additionalProperties": false }, "MatrixTimelineEvent": { "type": "object", "properties": { "type": { "type": "string" }, "event_id": { "type": "string" }, "room_id": { "type": "string" }, "sender": { "type": "string" }, "origin_server_ts": { "type": "integer", "format": "int64" }, "state_key": { "type": "string" }, "unsigned": { "type": "object", "additionalProperties": true }, "content": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ErrorResponse": { "type": "object", "required": [ "errcode", "error" ], "properties": { "errcode": { "type": "string", "description": "Matrix error code such as `M_UNKNOWN_TOKEN`, `M_FORBIDDEN`, or `M_NOT_FOUND`." }, "error": { "type": "string", "description": "Human-readable error message." } }, "additionalProperties": true }, "RateLimitedError": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "retry_after_ms": { "type": "integer", "format": "int64", "description": "Milliseconds to wait before retrying." } }, "additionalProperties": true } ] } } } }