2014-08-22 14:40:37 +02:00
{
"apiVersion": "1.0.0",
"swaggerVersion": "1.2",
2014-09-03 11:47:00 +02:00
"basePath": "http://localhost:8008/_matrix/client/api/v1",
2014-08-22 14:40:37 +02:00
"resourcePath": "/rooms",
"produces": [
"application/json"
],
"consumes": [
"application/json"
],
"authorizations": {
"token": []
},
"apis": [
2014-08-27 17:16:40 +02:00
{
2014-08-29 15:12:12 +02:00
"path": "/rooms/{roomId}/send/{eventType}",
2014-08-27 17:16:40 +02:00
"operations": [
{
2014-08-29 15:12:12 +02:00
"method": "POST",
2014-08-27 17:16:40 +02:00
"summary": "Send a generic non-state event to this room.",
2014-08-29 15:12:12 +02:00
"notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-27 17:16:40 +02:00
"type": "EventId",
"nickname": "send_non_state_event",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The event contents",
"required": true,
"type": "EventContent",
"paramType": "body"
},
{
"name": "roomId",
"description": "The room to send the message in.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "eventType",
"description": "The type of event to send.",
"required": true,
"type": "string",
"paramType": "path"
}
]
}
]
},
{
"path": "/rooms/{roomId}/state/{eventType}/{stateKey}",
"operations": [
{
"method": "PUT",
"summary": "Send a generic state event to this room.",
"notes": "The state key can be omitted, such that you can PUT to /rooms/{roomId}/state/{eventType}. The state key defaults to a 0 length string in this case.",
"type": "void",
"nickname": "send_state_event",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The event contents",
"required": true,
"type": "EventContent",
"paramType": "body"
},
{
"name": "roomId",
"description": "The room to send the message in.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "eventType",
"description": "The type of event to send.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "stateKey",
"description": "An identifier used to specify clobbering semantics. State events with the same (roomId, eventType, stateKey) will be replaced.",
"required": true,
"type": "string",
"paramType": "path"
}
]
}
]
},
2014-08-22 14:40:37 +02:00
{
2014-08-29 15:12:12 +02:00
"path": "/rooms/{roomId}/send/m.room.message",
2014-08-22 14:40:37 +02:00
"operations": [
{
2014-08-29 15:12:12 +02:00
"method": "POST",
2014-08-22 14:40:37 +02:00
"summary": "Send a message in this room.",
2014-08-29 15:12:12 +02:00
"notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-27 17:16:40 +02:00
"type": "EventId",
2014-08-22 14:40:37 +02:00
"nickname": "send_message",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The message contents",
"required": true,
"type": "Message",
"paramType": "body"
},
{
"name": "roomId",
"description": "The room to send the message in.",
"required": true,
"type": "string",
"paramType": "path"
}
]
}
]
},
{
2014-08-27 13:14:26 +02:00
"path": "/rooms/{roomId}/state/m.room.topic",
2014-08-22 14:40:37 +02:00
"operations": [
{
"method": "PUT",
"summary": "Set the topic for this room.",
"notes": "Set the topic for this room.",
"type": "void",
"nickname": "set_topic",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The topic contents",
"required": true,
"type": "Topic",
"paramType": "body"
},
{
"name": "roomId",
"description": "The room to set the topic in.",
"required": true,
"type": "string",
"paramType": "path"
}
]
},
{
"method": "GET",
"summary": "Get the topic for this room.",
"notes": "Get the topic for this room.",
"type": "Topic",
"nickname": "get_topic",
"parameters": [
{
"name": "roomId",
"description": "The room to get topic in.",
"required": true,
"type": "string",
"paramType": "path"
}
],
"responseMessages": [
{
"code": 404,
"message": "Topic not found."
}
]
}
]
},
2014-09-03 14:42:56 +02:00
{
"path": "/rooms/{roomId}/state/m.room.name",
"operations": [
{
"method": "PUT",
"summary": "Set the name of this room.",
"notes": "Set the name of this room.",
"type": "void",
"nickname": "set_room_name",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The name contents",
"required": true,
"type": "RoomName",
"paramType": "body"
},
{
"name": "roomId",
"description": "The room to set the name of.",
"required": true,
"type": "string",
"paramType": "path"
}
]
},
{
"method": "GET",
"summary": "Get the room's name.",
"notes": "",
"type": "RoomName",
"nickname": "get_room_name",
"parameters": [
{
"name": "roomId",
"description": "The room to get the name of.",
"required": true,
"type": "string",
"paramType": "path"
}
],
"responseMessages": [
{
"code": 404,
"message": "Name not found."
}
]
}
]
},
2014-08-22 14:40:37 +02:00
{
2014-08-29 15:12:12 +02:00
"path": "/rooms/{roomId}/send/m.room.message.feedback",
2014-08-22 14:40:37 +02:00
"operations": [
{
2014-08-29 15:12:12 +02:00
"method": "POST",
2014-08-22 14:40:37 +02:00
"summary": "Send feedback to a message.",
2014-08-29 15:12:12 +02:00
"notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-27 17:16:40 +02:00
"type": "EventId",
2014-08-22 14:40:37 +02:00
"nickname": "send_feedback",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The feedback contents",
"required": true,
"type": "Feedback",
"paramType": "body"
},
{
"name": "roomId",
"description": "The room to send the feedback in.",
"required": true,
"type": "string",
"paramType": "path"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad feedback type."
}
]
}
]
},
{
2014-08-29 15:12:12 +02:00
"path": "/rooms/{roomId}/invite",
2014-08-27 16:41:19 +02:00
"operations": [
{
2014-08-29 15:12:12 +02:00
"method": "POST",
2014-08-27 16:41:19 +02:00
"summary": "Invite a user to this room.",
2014-08-29 15:12:12 +02:00
"notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-27 16:41:19 +02:00
"type": "void",
"nickname": "invite",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "roomId",
"description": "The room which has this user.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "body",
"description": "The user to invite.",
"required": true,
"type": "InviteRequest",
"paramType": "body"
}
]
}
]
},
{
2014-08-29 15:12:12 +02:00
"path": "/rooms/{roomId}/join",
2014-08-27 16:41:19 +02:00
"operations": [
{
2014-08-29 15:12:12 +02:00
"method": "POST",
2014-08-27 16:41:19 +02:00
"summary": "Join this room.",
2014-08-29 15:12:12 +02:00
"notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-27 16:41:19 +02:00
"type": "void",
"nickname": "join_room",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "roomId",
"description": "The room to join.",
"required": true,
"type": "string",
"paramType": "path"
2014-09-03 14:32:25 +02:00
},
{
"name": "body",
"required": true,
"type": "JoinRequest",
"paramType": "body"
2014-08-27 16:41:19 +02:00
}
]
}
]
},
{
2014-08-29 15:12:12 +02:00
"path": "/rooms/{roomId}/leave",
2014-08-27 16:41:19 +02:00
"operations": [
{
2014-08-29 15:12:12 +02:00
"method": "POST",
2014-08-27 16:41:19 +02:00
"summary": "Leave this room.",
2014-08-29 15:12:12 +02:00
"notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-27 16:41:19 +02:00
"type": "void",
"nickname": "leave",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "roomId",
"description": "The room to leave.",
"required": true,
"type": "string",
"paramType": "path"
2014-09-03 14:32:25 +02:00
},
{
"name": "body",
"required": true,
"type": "LeaveRequest",
"paramType": "body"
2014-08-27 16:41:19 +02:00
}
]
}
]
},
2014-09-02 12:53:53 +02:00
{
"path": "/rooms/{roomId}/ban",
"operations": [
{
"method": "POST",
"summary": "Ban a user in the room.",
"notes": "This operation can also be done as a PUT by suffixing /{txnId}. The caller must have the required power level to do this operation.",
"type": "void",
"nickname": "ban",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "roomId",
"description": "The room which has the user to ban.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "body",
"description": "The user to ban.",
"required": true,
"type": "BanRequest",
"paramType": "body"
}
]
}
]
},
2014-08-27 16:41:19 +02:00
{
"path": "/rooms/{roomId}/state/m.room.member/{userId}",
2014-08-22 14:40:37 +02:00
"operations": [
{
"method": "PUT",
"summary": "Change the membership state for a user in a room.",
"notes": "Change the membership state for a user in a room.",
"type": "void",
"nickname": "set_membership",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
"description": "The new membership state",
"required": true,
"type": "Member",
"paramType": "body"
},
{
"name": "userId",
"description": "The user whose membership is being changed.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "roomId",
"description": "The room which has this user.",
"required": true,
"type": "string",
"paramType": "path"
}
],
"responseMessages": [
{
"code": 400,
"message": "No membership key."
},
{
"code": 400,
"message": "Bad membership value."
},
{
"code": 403,
"message": "When inviting: You are not in the room."
},
{
"code": 403,
"message": "When inviting: <target> is already in the room."
},
{
"code": 403,
"message": "When joining: Cannot force another user to join."
},
{
"code": 403,
"message": "When joining: You are not invited to this room."
}
]
},
{
"method": "GET",
"summary": "Get the membership state of a user in a room.",
"notes": "Get the membership state of a user in a room.",
"type": "Member",
"nickname": "get_membership",
"parameters": [
{
"name": "userId",
"description": "The user whose membership state you want to get.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "roomId",
"description": "The room which has this user.",
"required": true,
"type": "string",
"paramType": "path"
}
],
"responseMessages": [
{
"code": 404,
"message": "Member not found."
}
]
}
]
},
{
2014-08-27 13:14:26 +02:00
"path": "/join/{roomAliasOrId}",
2014-08-22 14:40:37 +02:00
"operations": [
{
2014-09-03 14:32:25 +02:00
"method": "POST",
2014-08-27 13:14:26 +02:00
"summary": "Join a room via a room alias or room ID.",
"notes": "Join a room via a room alias or room ID.",
2014-09-03 14:32:25 +02:00
"type": "JoinRoomInfo",
2014-08-27 13:14:26 +02:00
"nickname": "join",
2014-08-22 14:40:37 +02:00
"consumes": [
"application/json"
],
"parameters": [
{
2014-08-27 13:14:26 +02:00
"name": "roomAliasOrId",
"description": "The room alias or room ID to join.",
2014-08-22 14:40:37 +02:00
"required": true,
"type": "string",
"paramType": "path"
}
],
"responseMessages": [
{
"code": 400,
"message": "Bad room alias."
}
]
}
]
},
{
2014-08-27 13:14:26 +02:00
"path": "/createRoom",
2014-08-22 14:40:37 +02:00
"operations": [
{
"method": "POST",
"summary": "Create a room.",
"notes": "Create a room.",
"type": "RoomInfo",
"nickname": "create_room",
"consumes": [
"application/json"
],
"parameters": [
{
"name": "body",
2014-08-29 15:12:12 +02:00
"description": "The desired configuration for the room. This operation can also be done as a PUT by suffixing /{txnId}.",
2014-08-22 14:40:37 +02:00
"required": true,
"type": "RoomConfig",
"paramType": "body"
}
],
"responseMessages": [
{
"code": 400,
"message": "Body must be JSON."
},
{
"code": 400,
"message": "Room alias already taken."
}
]
}
]
},
{
2014-08-27 13:14:26 +02:00
"path": "/rooms/{roomId}/messages",
2014-08-22 14:40:37 +02:00
"operations": [
{
"method": "GET",
"summary": "Get a list of messages for this room.",
"notes": "Get a list of messages for this room.",
"type": "MessagePaginationChunk",
"nickname": "get_messages",
"parameters": [
{
"name": "roomId",
"description": "The room to get messages in.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "from",
"description": "The token to start getting results from.",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "to",
"description": "The token to stop getting results at.",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "limit",
"description": "The maximum number of messages to return.",
"required": false,
"type": "integer",
"paramType": "query"
}
]
}
]
},
{
2014-08-27 13:14:26 +02:00
"path": "/rooms/{roomId}/members",
2014-08-22 14:40:37 +02:00
"operations": [
{
"method": "GET",
"summary": "Get a list of members for this room.",
"notes": "Get a list of members for this room.",
"type": "MemberPaginationChunk",
"nickname": "get_members",
"parameters": [
{
"name": "roomId",
"description": "The room to get a list of members from.",
"required": true,
"type": "string",
"paramType": "path"
},
{
"name": "from",
"description": "The token to start getting results from.",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "to",
"description": "The token to stop getting results at.",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "limit",
"description": "The maximum number of members to return.",
"required": false,
"type": "integer",
"paramType": "query"
}
]
}
]
2014-08-27 18:02:00 +02:00
},
{
"path": "/rooms/{roomId}/state",
"operations": [
{
"method": "GET",
"summary": "Get a list of all the current state events for this room.",
2014-09-03 14:32:25 +02:00
"notes": "NOT YET IMPLEMENTED.",
2014-08-27 18:02:00 +02:00
"type": "array",
"items": {
"$ref": "Event"
},
"nickname": "get_state_events",
"parameters": [
{
"name": "roomId",
"description": "The room to get a list of current state events from.",
"required": true,
"type": "string",
"paramType": "path"
}
]
}
]
},
{
"path": "/rooms/{roomId}/initialSync",
"operations": [
{
"method": "GET",
"summary": "Get all the current information for this room, including messages and state events.",
2014-09-03 14:32:25 +02:00
"notes": "NOT YET IMPLEMENTED.",
2014-08-27 18:02:00 +02:00
"type": "InitialSyncRoomData",
"nickname": "get_room_sync_data",
"parameters": [
{
"name": "roomId",
"description": "The room to get information for.",
"required": true,
"type": "string",
"paramType": "path"
}
]
}
]
2014-08-22 14:40:37 +02:00
}
],
"models": {
"Topic": {
"id": "Topic",
"properties": {
"topic": {
"type": "string",
"description": "The topic text"
}
}
},
2014-09-03 14:42:56 +02:00
"RoomName": {
"id": "RoomName",
"properties": {
"name": {
"type": "string",
"description": "The human-readable name for the room. Can contain spaces."
}
}
},
2014-08-22 14:40:37 +02:00
"Message": {
"id": "Message",
"properties": {
"msgtype": {
"type": "string",
"description": "The type of message being sent, e.g. \"m.text\"",
"required": true
},
"_msgtype_defined_keys_": {
"description": "Additional keys as defined by the msgtype, e.g. \"body\""
}
}
},
"Feedback": {
"id": "Feedback",
"properties": {
2014-09-03 14:08:17 +02:00
"target_event_id": {
"type": "string",
"description": "The event ID being acknowledged.",
"required": true
},
"type": {
"type": "string",
"description": "The type of feedback. Either 'delivered' or 'read'.",
"required": true
}
2014-08-22 14:40:37 +02:00
}
},
"Member": {
"id": "Member",
"properties": {
"membership": {
"type": "string",
"description": "Enum: The membership state of this member.",
"enum": [
"invite",
"join",
"leave",
2014-09-03 14:32:25 +02:00
"ban"
2014-08-22 14:40:37 +02:00
]
}
}
},
"RoomInfo": {
"id": "RoomInfo",
"properties": {
"room_id": {
"type": "string",
"description": "The allocated room ID.",
"required": true
},
"room_alias": {
"type": "string",
"description": "The alias for the room.",
"required": false
}
}
},
2014-09-03 14:32:25 +02:00
"JoinRoomInfo": {
"id": "JoinRoomInfo",
"properties": {
"room_id": {
"type": "string",
"description": "The room ID joined, if joined via a room alias only.",
"required": true
}
}
},
2014-08-22 14:40:37 +02:00
"RoomConfig": {
"id": "RoomConfig",
"properties": {
"visibility": {
"type": "string",
"description": "Enum: The room visibility.",
"required": false,
"enum": [
"public",
"private"
]
},
"room_alias_name": {
"type": "string",
"description": "The alias to give the new room.",
"required": false
2014-09-02 12:53:53 +02:00
},
"name": {
"type": "string",
"description": "Sets the name of the room. Send a m.room.name event after creating the room with the 'name' key specified.",
"required": false
},
"topic": {
"type": "string",
"description": "Sets the topic for the room. Send a m.room.topic event after creating the room with the 'topic' key specified.",
"required": false
2014-08-22 14:40:37 +02:00
}
}
},
"PaginationRequest": {
"id": "PaginationRequest",
"properties": {
"from": {
"type": "string",
"description": "The token to start getting results from."
},
"to": {
"type": "string",
"description": "The token to stop getting results at."
},
"limit": {
"type": "integer",
"description": "The maximum number of entries to return."
}
}
},
"PaginationChunk": {
"id": "PaginationChunk",
"properties": {
"start": {
"type": "string",
"description": "A token which correlates to the first value in \"chunk\" for paginating.",
"required": true
},
"end": {
"type": "string",
"description": "A token which correlates to the last value in \"chunk\" for paginating.",
"required": true
}
},
"subTypes": [
"MessagePaginationChunk"
]
},
"MessagePaginationChunk": {
"id": "MessagePaginationChunk",
"properties": {
"chunk": {
"type": "array",
"description": "A list of message events.",
"items": {
"$ref": "MessageEvent"
},
"required": true
}
}
},
"MemberPaginationChunk": {
"id": "MemberPaginationChunk",
"properties": {
"chunk": {
"type": "array",
"description": "A list of member events.",
"items": {
"$ref": "MemberEvent"
},
"required": true
}
}
},
"Event": {
"id": "Event",
"properties": {
"event_id": {
"type": "string",
2014-08-27 17:16:40 +02:00
"description": "An ID which uniquely identifies this event. This is automatically set by the server.",
2014-08-22 14:40:37 +02:00
"required": true
},
"room_id": {
"type": "string",
2014-08-27 17:16:40 +02:00
"description": "The room in which this event occurred. This is automatically set by the server.",
"required": true
},
"type": {
"type": "string",
"description": "The event type.",
2014-08-22 14:40:37 +02:00
"required": true
}
},
"subTypes": [
"MessageEvent"
]
},
2014-08-27 17:16:40 +02:00
"EventId": {
"id": "EventId",
"properties": {
"event_id": {
"type": "string",
"description": "The allocated event ID for this event.",
"required": true
}
}
},
"EventContent": {
"id": "EventContent",
"properties": {
"__event_content_keys__": {
"type": "string",
"description": "Event-specific content keys and values.",
"required": false
}
}
},
2014-08-22 14:40:37 +02:00
"MessageEvent": {
"id": "MessageEvent",
"properties": {
"content": {
"type": "Message"
}
}
},
"MemberEvent": {
"id": "MemberEvent",
"properties": {
"content": {
"type": "Member"
}
}
2014-08-27 16:41:19 +02:00
},
"InviteRequest": {
"id": "InviteRequest",
"properties": {
"user_id": {
"type": "string",
"description": "The fully-qualified user ID."
}
}
2014-08-27 18:02:00 +02:00
},
2014-09-03 14:32:25 +02:00
"JoinRequest": {
"id": "JoinRequest",
"properties": {}
},
"LeaveRequest": {
"id": "LeaveRequest",
"properties": {}
},
2014-09-02 12:53:53 +02:00
"BanRequest": {
"id": "BanRequest",
"properties": {
"user_id": {
"type": "string",
"description": "The fully-qualified user ID."
},
"reason": {
"type": "string",
"description": "The reason for the ban."
}
}
},
2014-08-27 18:02:00 +02:00
"InitialSyncRoomData": {
"id": "InitialSyncRoomData",
"properties": {
"membership": {
"type": "string",
"description": "This user's membership state in this room.",
"required": true
},
"room_id": {
"type": "string",
"description": "The ID of this room.",
"required": true
},
"messages": {
"type": "MessagePaginationChunk",
"description": "The most recent messages for this room, governed by the limit parameter.",
"required": false
},
"state": {
"type": "array",
"description": "A list of state events representing the current state of the room.",
"required": false,
"items": {
"$ref": "Event"
}
}
}
2014-08-22 14:40:37 +02:00
}
}
}
