mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 09:58:38 +01:00
6c66bfc755
As a side effect, I got rid of all of the horrible symlinks and just put in all of the proper relative paths. Because the horrible symlinks were horrible.
462 lines
17 KiB
YAML
462 lines
17 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server v1 Rooms API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/api/v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
accessToken:
|
|
type: apiKey
|
|
description: The user_id or application service access_token
|
|
name: access_token
|
|
in: query
|
|
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. Defaults to the empty string.
|
|
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.
|
|
|
|
"/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",
|
|
"user_id": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 6547561012,
|
|
"content": {
|
|
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
|
|
"displayname": null,
|
|
"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",
|
|
"user_id": "@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",
|
|
"user_id": "@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",
|
|
"user_id": "@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",
|
|
"user_id": "@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": "../../event-schemas/schema/core-event-schema/state_event.json"
|
|
403:
|
|
description: >
|
|
You aren't a member of the room and weren't previously a
|
|
member of the room.
|
|
|
|
"/rooms/{roomId}/initialSync":
|
|
get:
|
|
summary: Snapshot the current state of a room and its most recent messages.
|
|
description: |-
|
|
Get a copy of the current state and the most recent messages in a room.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: roomId
|
|
description: The room to get the data.
|
|
required: true
|
|
x-example: "!636q39766251:example.com"
|
|
responses:
|
|
200:
|
|
description: The current state of the room
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"membership": "join",
|
|
"messages": {
|
|
"chunk": [
|
|
{
|
|
"age": 343513403,
|
|
"content": {
|
|
"body": "foo",
|
|
"msgtype": "m.text"
|
|
},
|
|
"event_id": "$14328044851tzTJS:example.com",
|
|
"origin_server_ts": 1432804485886,
|
|
"room_id": "!636q39766251:example.com",
|
|
"type": "m.room.message",
|
|
"user_id": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 343511809,
|
|
"content": {
|
|
"body": "bar",
|
|
"msgtype": "m.text"
|
|
},
|
|
"event_id": "$14328044872spjFg:example.com",
|
|
"origin_server_ts": 1432804487480,
|
|
"room_id": "!636q39766251:example.com",
|
|
"type": "m.room.message",
|
|
"user_id": "@bob:example.com"
|
|
}
|
|
],
|
|
"end": "s3456_9_0",
|
|
"start": "t44-3453_9_0"
|
|
},
|
|
"room_id": "!636q39766251:example.com",
|
|
"state": [
|
|
{
|
|
"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",
|
|
"user_id": "@alice:example.com"
|
|
},
|
|
{
|
|
"age": 6547561012,
|
|
"content": {
|
|
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
|
|
"displayname": null,
|
|
"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",
|
|
"user_id": "@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",
|
|
"user_id": "@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",
|
|
"user_id": "@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",
|
|
"user_id": "@alice:example.com"
|
|
}
|
|
],
|
|
"visibility": "private",
|
|
"account_data": [{
|
|
"type": "m.tag",
|
|
"content": {"tags": {"work": {"order": "1"}}}
|
|
}]
|
|
}
|
|
schema:
|
|
title: RoomInfo
|
|
type: object
|
|
properties:
|
|
room_id:
|
|
type: string
|
|
description: "The ID of this room."
|
|
membership:
|
|
type: string
|
|
description: "The user's membership state in this room."
|
|
enum: ["invite", "join", "leave", "ban"]
|
|
messages:
|
|
type: object
|
|
title: PaginationChunk
|
|
description: "The pagination chunk for this room."
|
|
properties:
|
|
start:
|
|
type: string
|
|
description: |-
|
|
A token which correlates to the first value in ``chunk``.
|
|
Used for pagination.
|
|
end:
|
|
type: string
|
|
description: |-
|
|
A token which correlates to the last value in ``chunk``.
|
|
Used for pagination.
|
|
chunk:
|
|
type: array
|
|
description: |-
|
|
If the user is a member of the room this will be a
|
|
list of the most recent messages for this room. If
|
|
the user has left the room this will be the
|
|
messages that preceeded them leaving. This array
|
|
will consist of at most ``limit`` elements.
|
|
items:
|
|
type: object
|
|
title: RoomEvent
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
|
|
required: ["start", "end", "chunk"]
|
|
state:
|
|
type: array
|
|
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 this will be the state of the
|
|
room when they left it.
|
|
items:
|
|
title: StateEvent
|
|
type: object
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
|
|
visibility:
|
|
type: string
|
|
enum: ["private", "public"]
|
|
description: |-
|
|
Whether this room is visible to the ``/publicRooms`` API
|
|
or not."
|
|
account_data:
|
|
type: array
|
|
description: |-
|
|
The private data that this user has attached to this room.
|
|
items:
|
|
title: Event
|
|
type: object
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
|
|
required: ["room_id"]
|
|
403:
|
|
description: >
|
|
You aren't a member of the room and weren't previously a
|
|
member of the room.
|
|
|
|
"/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",
|
|
"displayname": null,
|
|
"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",
|
|
"user_id": "@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",
|
|
"user_id": "@bob:example.com"
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
chunk:
|
|
type: array
|
|
items:
|
|
title: MemberEvent
|
|
type: object
|
|
allOf:
|
|
- "$ref": "../../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.
|
|
|