Matrix Client-Server API Skill

Use this skill to run Matrix Client-Server operations through uxc + OpenAPI.

Reuse the uxc skill for shared execution, auth, and error-handling guidance.

Prerequisites

• - uxc is installed and available in PATH.
• Network access to your Matrix homeserver's client-server base URL, usually https://<homeserver>/_matrix/client/v3.
• Access to the curated OpenAPI schema URL:

• - A Matrix access token for the target homeserver.

Scope

This skill covers a practical request/response Matrix surface:

• - token owner lookup
• joined room discovery
• room state lookup
• INLINECODE6 polling reads, including daemon-backed poll subscribe
• user profile and presence lookup
• room message sends

This skill does not cover:

• - login, SSO, device registration, or generic token acquisition flows
• appservice, federation, or bot framework abstractions
• webhook or long-running event receiver runtime
• full Matrix spec coverage

Homeserver Base URL

Matrix is homeserver-specific. The endpoint you link must include the Matrix client-server base path:

• - typical form: INLINECODE7
• example form: INLINECODE8

Do not link only the homeserver origin without /_matrix/client/v3.

Authentication

Matrix Client-Server API uses Authorization: Bearer <access_token>.

Preferred path for OAuth-aware homeservers:

CODEBLOCK0

Fallback path when you already have an access token:

CODEBLOCK1

If your homeserver is not matrix.org, replace the host while keeping the same path prefix. Validate the active mapping when auth looks wrong:

CODEBLOCK2

Notes:

• - uxc auth oauth works only for homeservers that expose Matrix OAuth metadata.
• Prefer a loopback redirect URI on an uncommon high port, such as http://127.0.0.1:8788/callback, to avoid conflicts with local services on common ports.
• Legacy Matrix login and SSO fallback flows are not covered by this skill yet.

Core Workflow

1. 1. Use the fixed link command by default:

1. 2. Inspect operation schema first:

1. 3. Prefer read validation before writes:

1. 4. Execute with key/value or positional JSON:

1. 5. For background /sync polling, call uxc subscribe start directly against the homeserver base URL:

Operation Groups

Session / Discovery

• - INLINECODE28
• INLINECODE29
• INLINECODE30

Room Reads

• - INLINECODE31
• INLINECODE32

User Reads

• - INLINECODE33
• INLINECODE34

Messaging

• - INLINECODE35

Guardrails

• - Keep automation on the JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• INLINECODE42 works both as a normal polling/read call and as a validated daemon-backed poll subscription when invoked through uxc subscribe start.
• For room-scoped /sync subscriptions, set missing_extract_items_pointer_as_empty=true so sparse responses without new room timeline events are treated as an empty batch instead of a fatal error.
• INLINECODE46 is high-risk and should default to m.room.message text sends unless the user explicitly asks for another event type.
• Reuse a unique txnId per send attempt to avoid accidental duplicates.
• Many homeservers restrict presence visibility and room state/event access based on membership and server policy; auth success does not imply every room or profile read will succeed.
• INLINECODE49 is equivalent to uxc <homeserver_client_base> --schema-url <matrix_openapi_schema> <operation> ....

References

• - Usage patterns: INLINECODE51
• Curated OpenAPI schema: INLINECODE52
• Matrix Client-Server API: https://spec.matrix.org/latest/client-server-api/
• Matrix spec source: https://github.com/matrix-org/matrix-spec/tree/main/data/api/client-server