{"openapi":"3.1.0","info":{"title":"Matrix.org (BYOK) API","version":"0.1.0","description":"Matrix.org (BYOK) lets an AI assistant read your own Matrix.org data through the Matrix.org API with a key you supply (Matrix access token of a matrix.org account). Read-only: 11 tools (whoami, get_server_capabilities, get_profile, list_joined_rooms, get_room_name, get_room_topic, list_room_joined_members, list_room_aliases, resolve_room_alias, list_public_rooms, search_public_rooms). The BYOK...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-matrix-org.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-matrix-org/docs"},"termsOfService":"https://connectorbay.com/byok-matrix-org/terms"},"servers":[{"url":"https://byok-matrix-org.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-matrix-org/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/whoami":{"post":{"operationId":"whoami","summary":"Show the Matrix user ID and device ID the access token belongs to, and whether it is a guest account. Use for \"Which Mat","description":"Show the Matrix user ID and device ID the access token belongs to, and whether it is a guest account. Use for \"Which Matrix account is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"whoamiArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_server_capabilities":{"post":{"operationId":"get_server_capabilities","summary":"Show what the matrix.org homeserver lets this account do: password changes, supported room versions and other capabiliti","description":"Show what the matrix.org homeserver lets this account do: password changes, supported room versions and other capabilities. Use for \"What room versions does the matrix.org server support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_server_capabilitiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_profile":{"post":{"operationId":"get_profile","summary":"Get a Matrix user's public profile: display name and avatar URL. Use for \"What is the display name of @alice:matrix.org\"","description":"Get a Matrix user's public profile: display name and avatar URL. Use for \"What is the display name of @alice:matrix.org\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Full Matrix user ID, for example '@alice:matrix.org'.","maxLength":255,"title":"User Id","type":"string"}},"required":["user_id"],"title":"get_profileArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_joined_rooms":{"post":{"operationId":"list_joined_rooms","summary":"List the IDs of every room the account has joined (IDs only; use the room tools for names and topics). Use for \"Which Ma","description":"List the IDs of every room the account has joined (IDs only; use the room tools for names and topics). Use for \"Which Matrix rooms am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_joined_roomsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_room_name":{"post":{"operationId":"get_room_name","summary":"Get the name of a room the account is in (the m.room.name state event). Use for \"What is the name of Matrix room !abcdef","description":"Get the name of a room the account is in (the m.room.name state event). Use for \"What is the name of Matrix room !abcdefg:matrix.org\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"room_id":{"description":"Matrix room ID such as '!abcdefg:matrix.org' (not the alias).","maxLength":255,"title":"Room Id","type":"string"}},"required":["room_id"],"title":"get_room_nameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_room_topic":{"post":{"operationId":"get_room_topic","summary":"Get the topic of a room the account is in (the m.room.topic state event). Use for \"What is the topic of Matrix room !abc","description":"Get the topic of a room the account is in (the m.room.topic state event). Use for \"What is the topic of Matrix room !abcdefg:matrix.org\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"room_id":{"description":"Matrix room ID such as '!abcdefg:matrix.org' (not the alias).","maxLength":255,"title":"Room Id","type":"string"}},"required":["room_id"],"title":"get_room_topicArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_room_joined_members":{"post":{"operationId":"list_room_joined_members","summary":"List the users currently joined to a room with their display names and avatar URLs (no messages). Use for \"Who is in Mat","description":"List the users currently joined to a room with their display names and avatar URLs (no messages). Use for \"Who is in Matrix room !abcdefg:matrix.org\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"room_id":{"description":"Matrix room ID such as '!abcdefg:matrix.org' (not the alias).","maxLength":255,"title":"Room Id","type":"string"}},"required":["room_id"],"title":"list_room_joined_membersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_room_aliases":{"post":{"operationId":"list_room_aliases","summary":"List the local room aliases (like #name:matrix.org) that point to a room. Use for \"What aliases does Matrix room !abcdef","description":"List the local room aliases (like #name:matrix.org) that point to a room. Use for \"What aliases does Matrix room !abcdefg:matrix.org have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"room_id":{"description":"Matrix room ID such as '!abcdefg:matrix.org' (not the alias).","maxLength":255,"title":"Room Id","type":"string"}},"required":["room_id"],"title":"list_room_aliasesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/resolve_room_alias":{"post":{"operationId":"resolve_room_alias","summary":"Resolve a room alias to its room ID and the servers that know the room. Use for \"Which room ID is #matrix:matrix.org\".","description":"Resolve a room alias to its room ID and the servers that know the room. Use for \"Which room ID is #matrix:matrix.org\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"room_alias":{"description":"Room alias including the # and server, for example '#matrix:matrix.org'.","maxLength":255,"title":"Room Alias","type":"string"}},"required":["room_alias"],"title":"resolve_room_aliasArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_public_rooms":{"post":{"operationId":"list_public_rooms","summary":"List rooms published in the public room directory with name, topic, member count and join rule. Paged with the since tok","description":"List rooms published in the public room directory with name, topic, member count and join rule. Paged with the since token. Use for \"Which public Matrix rooms exist on matrix.org\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rooms to return (server default if unset).","title":"Limit"},"since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination token from next_batch of a previous answer.","title":"Since"},"server":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Directory of this other server instead of matrix.org, for example 'mozilla.org'.","title":"Server"}},"title":"list_public_roomsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_public_rooms":{"post":{"operationId":"search_public_rooms","summary":"Search the public room directory for a word in room names, topics or aliases (a read-only query). Use for \"Find public M","description":"Search the public room directory for a word in room names, topics or aliases (a read-only query). Use for \"Find public Matrix rooms about python\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_term":{"description":"Word or phrase to look for in room name, topic or alias.","maxLength":100,"title":"Search Term","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rooms to return (1 to 100).","title":"Limit"},"since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination token from next_batch of a previous answer.","title":"Since"}},"required":["search_term"],"title":"search_public_roomsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}