mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-29 03:58:38 +01:00
9d267795e0
It's a bit incongruous to have to read through the deprecated /initialSync to get to the good stuff. Separate out intialSync so that we can move it later in the spec.
289 lines
10 KiB
YAML
289 lines
10 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server Rooms API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/rooms/{roomId}/state/{eventType}/{stateKey}":
|
|
get:
|
|
summary: Get the state identified by the type and key.
|
|
description: |-
|
|
Looks up the contents of a state event in a room. If the user is
|
|
joined to the room then the state is taken from the current
|
|
state of the room. If the user has left the room then the state is
|
|
taken from the state of the room when they left.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomId
|
|
description: The room to look up the state in.
|
|
required: true
|
|
x-example: "!636q39766251:example.com"
|
|
- in: path
|
|
type: string
|
|
name: eventType
|
|
description: The type of state to look up.
|
|
required: true
|
|
x-example: "m.room.name"
|
|
- in: path
|
|
type: string
|
|
name: stateKey
|
|
description: The key of the state to look up.
|
|
required: true
|
|
x-example: ""
|
|
responses:
|
|
200:
|
|
description: The content of the state event.
|
|
examples:
|
|
application/json: |-
|
|
{"name": "Example room name"}
|
|
schema:
|
|
type: object
|
|
404:
|
|
description: The room has no state with the given type or key.
|
|
403:
|
|
description: >
|
|
You aren't a member of the room and weren't previously a
|
|
member of the room.
|
|
tags:
|
|
- Room participation
|
|
"/rooms/{roomId}/state/{eventType}":
|
|
get:
|
|
summary: Get the state identified by the type, with the empty state key.
|
|
description: |-
|
|
Looks up the contents of a state event in a room. If the user is
|
|
joined to the room then the state is taken from the current
|
|
state of the room. If the user has left the room then the state is
|
|
taken from the state of the room when they left.
|
|
|
|
This looks up the state event with the empty state key.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomId
|
|
description: The room to look up the state in.
|
|
required: true
|
|
x-example: "!636q39766251:example.com"
|
|
- in: path
|
|
type: string
|
|
name: eventType
|
|
description: The type of state to look up.
|
|
required: true
|
|
x-example: "m.room.name"
|
|
responses:
|
|
200:
|
|
description: The content of the state event.
|
|
examples:
|
|
application/json: |-
|
|
{"name": "Example room name"}
|
|
schema:
|
|
type: object
|
|
404:
|
|
description: The room has no state with the given type or key.
|
|
403:
|
|
description: >
|
|
You aren't a member of the room and weren't previously a
|
|
member of the room.
|
|
tags:
|
|
- Room participation
|
|
"/rooms/{roomId}/state":
|
|
get:
|
|
summary: Get all state events in the current state of a room.
|
|
description: |-
|
|
Get the state events for the current state of a room.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomId
|
|
description: The room to look up the state for.
|
|
required: true
|
|
x-example: "!636q39766251:example.com"
|
|
responses:
|
|
200:
|
|
description: The current state of the room
|
|
examples:
|
|
application/json: |-
|
|
[
|
|
{
|
|
"age": 7148266897,
|
|
"content": {
|
|
"join_rule": "public"
|
|
},
|
|
"event_id": "$14259997323TLwtb:example.com",
|
|
"origin_server_ts": 1425999732392,
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "",
|
|
"type": "m.room.join_rules",
|
|
"sender": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 6547561012,
|
|
"content": {
|
|
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
|
|
"membership": "join"
|
|
},
|
|
"event_id": "$1426600438280zExKY:example.com",
|
|
"membership": "join",
|
|
"origin_server_ts": 1426600438277,
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "@alice:example.com",
|
|
"type": "m.room.member",
|
|
"sender": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 7148267200,
|
|
"content": {
|
|
"creator": "@alice:example.com"
|
|
},
|
|
"event_id": "$14259997320KhbwJ:example.com",
|
|
"origin_server_ts": 1425999732089,
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "",
|
|
"type": "m.room.create",
|
|
"sender": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 1622568720,
|
|
"content": {
|
|
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
|
|
"displayname": "Bob",
|
|
"membership": "join"
|
|
},
|
|
"event_id": "$1431525430134MxlLX:example.com",
|
|
"origin_server_ts": 1431525430569,
|
|
"replaces_state": "$142652023736BSXcM:example.com",
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "@bob:example.com",
|
|
"type": "m.room.member",
|
|
"sender": "@bob:example.com"
|
|
},
|
|
{
|
|
"age": 7148267004,
|
|
"content": {
|
|
"ban": 50,
|
|
"events": {
|
|
"m.room.name": 100,
|
|
"m.room.power_levels": 100
|
|
},
|
|
"events_default": 0,
|
|
"kick": 50,
|
|
"redact": 50,
|
|
"state_default": 50,
|
|
"users": {
|
|
"@alice:example.com": 100
|
|
},
|
|
"users_default": 0
|
|
},
|
|
"event_id": "$14259997322mqfaq:example.com",
|
|
"origin_server_ts": 1425999732285,
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "",
|
|
"type": "m.room.power_levels",
|
|
"sender": "@alice:example.com"
|
|
}
|
|
]
|
|
schema:
|
|
type: array
|
|
title: RoomState
|
|
description: |-
|
|
If the user is a member of the room this will be the
|
|
current state of the room as a list of events. If the user
|
|
has left the room then this will be the state of the room
|
|
when they left as a list of events.
|
|
items:
|
|
title: StateEvent
|
|
type: object
|
|
allOf:
|
|
- "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
|
|
403:
|
|
description: >
|
|
You aren't a member of the room and weren't previously a
|
|
member of the room.
|
|
tags:
|
|
- Room participation
|
|
"/rooms/{roomId}/members":
|
|
get:
|
|
summary: Get the m.room.member events for the room.
|
|
description:
|
|
Get the list of members for this room.
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomId
|
|
description: The room to get the member events for.
|
|
required: true
|
|
x-example: "!636q39766251:example.com"
|
|
responses:
|
|
200:
|
|
description: |-
|
|
A list of members of the room. If you are joined to the room then
|
|
this will be the current members of the room. If you have left te
|
|
room then this will be the members of the room when you left.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"chunk": [
|
|
{
|
|
"age": 6547561012,
|
|
"content": {
|
|
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
|
|
"membership": "join"
|
|
},
|
|
"event_id": "$1426600438280zExKY:example.com",
|
|
"membership": "join",
|
|
"origin_server_ts": 1426600438277,
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "@alice:example.com",
|
|
"type": "m.room.member",
|
|
"sender": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 1622568720,
|
|
"content": {
|
|
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
|
|
"displayname": "Bob",
|
|
"membership": "join"
|
|
},
|
|
"event_id": "$1431525430134MxlLX:example.com",
|
|
"origin_server_ts": 1431525430569,
|
|
"replaces_state": "$142652023736BSXcM:example.com",
|
|
"room_id": "!636q39766251:example.com",
|
|
"state_key": "@bob:example.com",
|
|
"type": "m.room.member",
|
|
"sender": "@bob:example.com"
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
chunk:
|
|
type: array
|
|
items:
|
|
title: MemberEvent
|
|
type: object
|
|
allOf:
|
|
- "$ref": "definitions/event-schemas/schema/m.room.member"
|
|
403:
|
|
description: >
|
|
You aren't a member of the room and weren't previously a
|
|
member of the room.
|
|
tags:
|
|
- Room participation
|