Matrix Client-Server API Skill

uxc

uxc

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:

  • https://raw.githubusercontent.com/holon-run/uxc/main/skills/matrix-openapi-skill/references/matrix-client-server.openapi.json

• A Matrix access token for the target homeserver.

Scope

• token owner lookup
• joined room discovery
• room state lookup

• /sync

  polling reads, including daemon-backed poll subscribe
• user profile and presence lookup
• room message sends

• 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

• typical form:

  https://<homeserver>/_matrix/client/v3

• example form:

  https://matrix.org/_matrix/client/v3

/_matrix/client/v3

Authentication

Authorization: Bearer <access_token>

uxc auth oauth start matrix-oauth \
  --endpoint https://matrix.org/_matrix/client/v3 \
  --redirect-uri http://127.0.0.1:8788/callback \
  --client-id <client_id>

uxc auth oauth complete matrix-oauth \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...'

uxc auth binding add \
  --id matrix-oauth \
  --host matrix.org \
  --path-prefix /_matrix/client/v3 \
  --scheme https \
  --credential matrix-oauth \
  --priority 100

uxc auth credential set matrix-access \
  --auth-type bearer \
  --secret-env MATRIX_ACCESS_TOKEN

uxc auth binding add \
  --id matrix-access \
  --host matrix.org \
  --path-prefix /_matrix/client/v3 \
  --scheme https \
  --credential matrix-access \
  --priority 100

matrix.org

uxc auth binding match https://matrix.org/_matrix/client/v3

• 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. Use the fixed link command by default:

   • command -v matrix-openapi-cli

   • If missing, create it:

     uxc link matrix-openapi-cli https://matrix.org/_matrix/client/v3 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/matrix-openapi-skill/references/matrix-client-server.openapi.json

   • matrix-openapi-cli -h

2. Inspect operation schema first:

   • matrix-openapi-cli get:/account/whoami -h

   • matrix-openapi-cli get:/sync -h

   • matrix-openapi-cli put:/rooms/{roomId}/send/{eventType}/{txnId} -h

3. Prefer read validation before writes:

   • matrix-openapi-cli get:/account/whoami

   • matrix-openapi-cli get:/joined_rooms

   • matrix-openapi-cli get:/rooms/{roomId}/state roomId=!abc123:example.org

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

     matrix-openapi-cli get:/sync timeout=30000 filter={"room":{"timeline":{"limit":10}}}

   • positional JSON:

     matrix-openapi-cli put:/rooms/{roomId}/send/{eventType}/{txnId} '{"roomId":"!abc123:example.org","eventType":"m.room.message","txnId":"uxc-001","msgtype":"m.text","body":"Hello from UXC"}'

5. For background

   /sync

   polling, call

   uxc subscribe start

   directly against the homeserver base URL:

   • uxc subscribe start https://matrix.org/_matrix/client/v3 get:/sync --auth matrix-oauth --mode poll --poll-config '{"interval_secs":2,"extract_items_pointer":"/rooms/join/!abc123:example.org/timeline/events","missing_extract_items_pointer_as_empty":true,"request_cursor_arg":"since","response_cursor_pointer":"/next_batch","checkpoint_strategy":{"type":"cursor_only"}}' --sink file:$HOME/.uxc/subscriptions/matrix-sync.ndjson timeout=1000 'filter={"room":{"rooms":["!abc123:example.org"],"timeline":{"limit":5}}}'

Operation Groups

Session / Discovery

• get:/account/whoami

• get:/joined_rooms

• get:/sync

Room Reads

• get:/rooms/{roomId}/state

• get:/rooms/{roomId}/state/{eventType}/{stateKey}

User Reads

• get:/profile/{userId}

• get:/presence/{userId}/status

Messaging

• put:/rooms/{roomId}/send/{eventType}/{txnId}

Guardrails

• Keep automation on the JSON output envelope; do not use

  --text

  .
• Parse stable fields first:

  ok

  ,

  kind

  ,

  protocol

  ,

  data

  ,

  error

  .

• get:/sync

  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.

• put:/rooms/{roomId}/send/{eventType}/{txnId}

  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.

• matrix-openapi-cli <operation> ...

  is equivalent to

  uxc <homeserver_client_base> --schema-url <matrix_openapi_schema> <operation> ...

  .

References

• Usage patterns:

  references/usage-patterns.md

• Curated OpenAPI schema:

  references/matrix-client-server.openapi.json

• 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