Matrix Openapi Skill

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:
  • 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

This skill covers a practical request/response Matrix surface:

• 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

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: https://<homeserver>/_matrix/client/v3
• example form: https://matrix.org/_matrix/client/v3

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:

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

Fallback path when you already have an access token:

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

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

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

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. 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}}}'