wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge remote-tracking branch 'origin/master' into erikj/search_yet_agian

Browse source
This commit is contained in:
Erik Johnston 2015-12-07 16:28:14 +00:00
commit 856dd9100e
172 changed files with 1728 additions and 1719 deletions
Download patch file Download diff file Expand all files Collapse all files

6
api/client-server/account-data.yaml
View file

@ -6,7 +6,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -57,6 +57,8 @@ paths:
200:
description:
The account_data was successfully added.
tags:
- User data
"/user/{userId}/rooms/{roomId}/account_data/{type}":
put:
summary: Set some account_data for the user.
@ -103,3 +105,5 @@ paths:
200:
description:
The account_data was successfully added.
tags:
- User data

105
api/client-server/admin.yaml Normal file
View file

@ -0,0 +1,105 @@
swagger: '2.0'
info:
title: "Matrix Client-Server Administration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
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:
"/admin/whois/{userId}":
get:
summary: Gets information about a particular user.
description: |-
Gets information about a particular user.
This API may be restricted to only be called by the user being looked
up, or by a server admin. Server-local administrator privileges are not
specified in this document.
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user to look up.
required: true
x-example: "@peter:rabbit.rocks"
responses:
200:
description: The lookup was successful.
examples:
application/json: |-
{
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
"sessions": [
{
"connections": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
}
]
}
]
}
}
}
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: |-
Each key is an identitfier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: number
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
tags:
- Server administration

16
api/client-server/administrative_contact.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Account Administrative Contact API"
title: "Matrix Client-Server Account Administrative Contact API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -25,7 +25,7 @@ paths:
This API endpoint uses the User-Interactive Authentication API.
An access token should be submitted to this endpoint if the client has
an active session.
The Home Server may change the flows available depending on whether a
The homeserver may change the flows available depending on whether a
valid access token is provided.
security:
- accessToken: []
@ -54,6 +54,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data
"/account/3pid":
get:
summary: Gets a list of a user's third party identifiers.
@ -64,7 +66,7 @@ paths:
This is *not* the same as the list of third party identifiers bound to
the user's Matrix ID in Identity Servers.
Identifiers in this list may be used by the Home Server as, for example,
Identifiers in this list may be used by the homeserver as, for example,
identifiers that it will accept to reset the user's account password.
security:
- accessToken: []
@ -97,6 +99,8 @@ paths:
address:
type: string
description: The third party identifier address.
tags:
- User data
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
@ -126,7 +130,7 @@ paths:
bind:
type: boolean
description: |-
Whether the home server should also bind this third party
Whether the homeserver should also bind this third party
identifier to the account's Matrix ID with the passed identity
server. Default: ``false``.
x-example: true
@ -155,3 +159,5 @@ paths:
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
tags:
- User data

201
api/client-server/application_service.yaml
View file

@ -1,201 +0,0 @@
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: "/"
consumes:
- application/json
produces:
- application/json
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the HS when the HS wants to push an event (or
batch of events) to the AS.
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events
schema:
type: object
example: |-
{
"events": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
},
{
"age": 1984,
"content": {
"body": "another incoming message",
"msgtype": "m.text"
},
"event_id": "$1228055551ffsef:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
}
]
}
description: "Transaction informations"
properties:
events:
type: array
description: A list of events
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: |-
{}
schema:
type: object
"/rooms/{roomAlias}":
get:
summary: Query if a room alias should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given room alias. The homeserver will only query room
aliases inside the application service's ``aliases`` namespace. The
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
parameters:
- in: path
name: roomAlias
type: string
description: The room alias being queried.
required: true
x-example: "#magicforest:example.com"
responses:
200:
description: |-
The application service indicates that this room alias exists. The
application service MUST have created a room and associated it with
the queried room alias using the client-server API. Additional
information about the room such as its name and topic can be set
before responding.
examples:
application/json: |-
{}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
type: object
"/users/{userId}":
get:
summary: Query if a user should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given user ID. The homeserver will only query user IDs
inside the application service's ``users`` namespace. The homeserver will
send this request when it receives an event for an unknown user ID in
the application service's namespace.
parameters:
- in: path
name: userId
type: string
description: The user ID being queried.
required: true
x-example: "@alice:example.com"
responses:
200:
description: |-
The application service indicates that this user exists. The application
service MUST create the user using the client-server API.
examples:
application/json: |-
{}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
type: object

6
api/client-server/banning.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Banning API"
title: "Matrix Client-Server Room Banning API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,3 +74,5 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
tags:
- Room membership

12
api/client-server/content-repo.yaml
View file

@ -1,11 +1,11 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Content Repository API"
title: "Matrix Client-Server Content Repository API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/media/v1
basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
produces:
- application/json
- "*/*"
@ -43,6 +43,8 @@ paths:
{
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
tags:
- Media
"/download/{serverName}/{mediaId}":
get:
summary: "Download content from the content repository."
@ -74,6 +76,8 @@ paths:
type: "string"
schema:
type: file
tags:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
@ -123,5 +127,5 @@ paths:
enum: ["image/jpeg", "image/png"]
schema:
type: file
tags:
- Media

8
api/client-server/create_room.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Creation API"
title: "Matrix Client-Server Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -57,7 +57,7 @@ paths:
description: |-
The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created
room. The alias will belong on the *same* home server which
room. The alias will belong on the *same* homeserver which
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``.
@ -146,3 +146,5 @@ paths:
400:
description: >
The request body is malformed or the room alias specified is already taken.
tags:
- Room creation

53
api/client-server/definitions/event.json
View file

@ -1,53 +0,0 @@
{
"type": "object",
"title": "Event",
"properties": {
"content": {
"type": "object",
"title": "EventContent",
"description": "The content of this event. The fields in this object will vary depending on the type of event."
},
"origin_server_ts": {
"type": "integer",
"format": "int64",
"description": "Timestamp in milliseconds on originating homeserver when this event was sent."
},
"sender": {
"type": "string",
"description": "The MXID of the user who sent this event."
},
"state_key": {
"type": "string",
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state."
},
"type": {
"type": "string",
"description": "The type of event."
},
"unsigned": {
"type": "object",
"title": "Unsigned",
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"type": "integer",
"format": "int64",
"description": "Time in milliseconds since the event was sent."
},
"prev_content": {
"title": "EventContent",
"type": "object",
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
},
"replaces_state": {
"type": "string",
"description": "Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
},
"transaction_id": {
"type": "string",
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API."
}
}
}
}
}

45
api/client-server/definitions/event.yaml Normal file
View file

@ -0,0 +1,45 @@
properties:
content:
description: The content of this event. The fields in this object will vary depending
on the type of event.
title: EventContent
type: object
origin_server_ts:
description: Timestamp in milliseconds on originating homeserver when this event
was sent.
format: int64
type: integer
sender:
description: The MXID of the user who sent this event.
type: string
state_key:
description: Optional. This key will only be present for state events. A unique
key which defines the overwriting semantics for this piece of room state.
type: string
type:
description: The type of event.
type: string
unsigned:
description: Information about this event which was not sent by the originating
homeserver
properties:
age:
description: Time in milliseconds since the event was sent.
format: int64
type: integer
prev_content:
description: Optional. The previous ``content`` for this state. This will
be present only for state events appearing in the ``timeline``. If this
is not a state event, or there is no previous content, this key will be
missing.
title: EventContent
type: object
transaction_id:
description: Optional. The transaction ID set when this message was sent.
This key will only be present for message events sent by the device calling
this API.
type: string
title: Unsigned
type: object
title: Event
type: object

13
api/client-server/definitions/event_batch.json
View file

@ -1,13 +0,0 @@
{
"type": "object",
"properties": {
"events": {
"type": "array",
"description": "List of events",
"items": {
"type": "object",
"allOf": [{"$ref": "event.json" }]
}
}
}
}

9
api/client-server/definitions/event_batch.yaml Normal file
View file

@ -0,0 +1,9 @@
properties:
events:
description: List of events
items:
allOf:
- $ref: event.yaml
type: object
type: array
type: object

42
api/client-server/definitions/event_filter.json
View file

@ -1,42 +0,0 @@
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description":
"The maximum number of events to return."
},
"types": {
"type": "array",
"description":
"A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
}
},
"not_types": {
"type": "array",
"description":
"A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
}
},
"senders": {
"type": "array",
"description":
"A list of senders IDs to include. If this list is absent then all senders are included. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
}
},
"not_senders": {
"type": "array",
"description":
"A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
}
}
}
}

34
api/client-server/definitions/event_filter.yaml Normal file
View file

@ -0,0 +1,34 @@
properties:
limit:
description: The maximum number of events to return.
type: integer
not_senders:
description: A list of sender IDs to exclude. If this list is absent then no senders
are excluded. A matching sender will be excluded even if it is listed in the
'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.
items:
type: string
type: array
not_types:
description: A list of event types to exclude. If this list is absent then no
event types are excluded. A matching type will be excluded even if it is listed
in the 'types' filter. A '*' can be used as a wildcard to match any sequence
of characters.
items:
type: string
type: array
senders:
description: A list of senders IDs to include. If this list is absent then all
senders are included. A '*' can be used as a wildcard to match any sequence
of characters.
items:
type: string
type: array
types:
description: A list of event types to include. If this list is absent then all
event types are included. A '*' can be used as a wildcard to match any sequence
of characters.
items:
type: string
type: array
type: object

9
api/client-server/definitions/push_condition.json
View file

@ -1,9 +0,0 @@
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": ["event_match", "profile_tag", "contains_display_name", "room_member_count"]
}
}
}

9
api/client-server/definitions/push_condition.yaml Normal file
View file

@ -0,0 +1,9 @@
properties:
kind:
enum:
- event_match
- profile_tag
- contains_display_name
- room_member_count
type: string
type: object

21
api/client-server/definitions/push_rule.json
View file

@ -1,21 +0,0 @@
{
"title": "PushRule",
"type": "object",
"properties": {
"default": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"rule_id": {
"type": "string"
},
"actions": {
"items": {
"type": ["object", "string"]
},
"type": "array"
}
}
}

15
api/client-server/definitions/push_rule.yaml Normal file
View file

@ -0,0 +1,15 @@
properties:
actions:
items:
type:
- object
- string
type: array
default:
type: boolean
enabled:
type: boolean
rule_id:
type: string
title: PushRule
type: object

65
api/client-server/definitions/push_ruleset.json
View file

@ -1,65 +0,0 @@
{
"type": "object",
"properties": {
"content": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"override": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"sender": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"underride": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
},
"room": {
"items": {
"type": "object",
"title": "PushRule",
"allOf": [
{
"$ref": "push_rule.json"
}
]
},
"type": "array"
}
}
}

37
api/client-server/definitions/push_ruleset.yaml Normal file
View file

@ -0,0 +1,37 @@
properties:
content:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
override:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
room:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
sender:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
underride:
items:
allOf:
- $ref: push_rule.yaml
title: PushRule
type: object
type: array
type: object

22
api/client-server/definitions/room_event_filter.json
View file

@ -1,22 +0,0 @@
{
"type": "object",
"allOf": [{"$ref": "event_filter.json"}],
"properties": {
"rooms": {
"type": "array",
"description":
"A list of room IDs to include. If this list is absent then all rooms are included. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
}
},
"not_rooms": {
"type": "array",
"description":
"A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
}
}
}
}

17
api/client-server/definitions/room_event_filter.yaml Normal file
View file

@ -0,0 +1,17 @@
allOf:
- $ref: event_filter.yaml
properties:
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the 'rooms'
filter. A '*' can be used as a wildcard to match any sequence of characters.
items:
type: string
type: array
rooms:
description: A list of room IDs to include. If this list is absent then all rooms
are included. A '*' can be used as a wildcard to match any sequence of characters.
items:
type: string
type: array
type: object

44
api/client-server/definitions/sync_filter.json
View file

@ -1,44 +0,0 @@
{
"type": "object",
"properties": {
"room": {
"type": "object",
"properties": {
"state": {
"description":
"The state events to include for rooms.",
"allOf": [{"$ref": "room_event_filter.json"}]
},
"timeline": {
"description":
"The message and state update events to include for rooms.",
"allOf": [{"$ref": "room_event_filter.json"}]
},
"ephemeral": {
"description":
"The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.",
"allOf": [{"$ref": "room_event_filter.json"}]
}
}
},
"presence": {
"description":
"The presence updates to include.",
"allOf": [{"$ref": "event_filter.json"}]
},
"event_format": {
"description":
"The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
"type": "string",
"enum": ["client", "federation"]
},
"event_fields": {
"type": "array",
"description":
"List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested.",
"items": {
"type": "string"
}
}
}
}

42
api/client-server/definitions/sync_filter.yaml Normal file
View file

@ -0,0 +1,42 @@
properties:
event_fields:
description: List of event fields to include. If this list is absent then all
fields are included. The entries may include '.' charaters to indicate sub-fields.
So ['content.body'] will include the 'body' field of the 'content' object. A
literal '.' character in a field name may be escaped using a '\'. A server may
include more fields than were requested.
items:
type: string
type: array
event_format:
description: The format to use for events. 'client' will return the events in
a format suitable for clients. 'federation' will return the raw event as receieved
over federation. The default is 'client'.
enum:
- client
- federation
type: string
presence:
allOf:
- $ref: event_filter.yaml
description: The presence updates to include.
room:
properties:
ephemeral:
allOf:
- $ref: room_event_filter.yaml
description: The events that aren't recorded in the room history, e.g. typing
and receipts, to include for rooms.
include_leave:
description: Include rooms that the user has left in the sync, default false
type: boolean
state:
allOf:
- $ref: room_event_filter.yaml
description: The state events to include for rooms.
timeline:
allOf:
- $ref: room_event_filter.yaml
description: The message and state update events to include for rooms.
type: object
type: object

14
api/client-server/definitions/timeline_batch.json
View file

@ -1,14 +0,0 @@
{
"type": "object",
"allOf": [{"$ref":"event_batch.json"}],
"properties": {
"limited": {
"type": "boolean",
"description": "True if the number of events returned was limited by the ``limit`` on the filter"
},
"prev_batch": {
"type": "string",
"description": "If the batch was limited then this is a token that can be supplied to the server to retrieve earlier events"
}
}
}

12
api/client-server/definitions/timeline_batch.yaml Normal file
View file

@ -0,0 +1,12 @@
allOf:
- $ref: event_batch.yaml
properties:
limited:
description: True if the number of events returned was limited by the ``limit``
on the filter
type: boolean
prev_batch:
description: If the batch was limited then this is a token that can be supplied
to the server to retrieve earlier events
type: string
type: object

10
api/client-server/directory.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Directory API"
title: "Matrix Client-Server Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1/directory
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
consumes:
- application/json
produces:
@ -52,6 +52,8 @@ paths:
{}
schema:
type: object
tags:
- Room directory
get:
summary: Get the room ID corresponding to this room alias.
parameters:
@ -102,6 +104,8 @@ paths:
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
tags:
- Room directory
delete:
summary: Remove a mapping of room alias to room ID.
description: |-
@ -125,3 +129,5 @@ paths:
{}
schema:
type: object
tags:
- Room directory

16
api/client-server/filter.yaml
View file

@ -1,11 +1,11 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 filter API"
title: "Matrix Client-Server filter API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -22,8 +22,8 @@ paths:
summary: Upload a new filter.
description: |-
Uploads a new filter definition to the homeserver.
Returns a filter ID that may be used in /sync requests to
retrict which events are returned to the client.
Returns a filter ID that may be used in future requests to
restrict which events are returned to the client.
security:
- accessToken: []
parameters:
@ -42,7 +42,7 @@ paths:
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.json"
- $ref: "definitions/sync_filter.yaml"
example: |-
{
"room": {
@ -84,6 +84,8 @@ paths:
type: string
description: |-
The ID of the filter that was created.
tags:
- Room participation
"/user/{userId}/filter/{filterId}":
get:
summary: Download a filter
@ -136,4 +138,6 @@ paths:
schema:
type: object
allOf:
- $ref: "definitions/sync_filter.json"
- $ref: "definitions/sync_filter.yaml"
tags:
- Room participation

9
api/client-server/guest_events.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Sync Guest API"
title: "Matrix Client-Server Sync Guest API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,7 +74,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
}
]
}
@ -98,6 +98,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
400:
description: "Bad pagination ``from`` parameter."
# No tags to exclude this from the swagger UI - use the non-guest version instead.

8
api/client-server/inviting.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Joining API"
title: "Matrix Client-Server Room Joining API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -38,7 +38,7 @@ paths:
Only users currently in a particular room can invite other users to
join that room.
If the user was invited to the room, the home server will append a
If the user was invited to the room, the homeserver will append a
``m.room.member`` event to the room.
.. _third party invites section: `invite-by-third-party-id-endpoint`_
@ -88,3 +88,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership

10
api/client-server/joining.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Inviting API"
title: "Matrix Client-Server Room Inviting API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -63,6 +63,8 @@ paths:
schema:
"$ref": "definitions/error.yaml"
x-alias:
canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join"
aliases:
- /_matrix/client/api/v1/join/{roomId}
- /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId}
tags:
- Room membership

8
api/client-server/leaving.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Leaving API"
title: "Matrix Client-Server Room Leaving API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -55,6 +55,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership
"/rooms/{roomId}/forget":
post:
summary: Stop the requesting user remembering about a particular room.
@ -90,3 +92,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership

6
api/client-server/list_public_rooms.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Creation API"
title: "Matrix Client-Server Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -95,3 +95,5 @@ paths:
400:
description: >
The request body is malformed or the room alias specified is already taken.
tags:
- Room discovery

10
api/client-server/login.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Registration and Login API"
title: "Matrix Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -81,7 +81,7 @@ paths:
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server:
type: string
description: The hostname of the Home Server on which the account has been registered.
description: The hostname of the homeserver on which the account has been registered.
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
@ -101,6 +101,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Session management
"/tokenrefresh":
post:
summary: Exchanges a refresh token for an access token.
@ -158,3 +160,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Session management

6
api/client-server/message_pagination.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Rooms API"
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -129,3 +129,5 @@ paths:
403:
description: >
You aren't a member of the room.
tags:
- Room participation

41
api/client-server/old_sync.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Sync API"
title: "Matrix Client-Server Sync API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -60,7 +60,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
}
]
}
@ -84,9 +84,11 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
400:
description: "Bad pagination ``from`` parameter."
tags:
- Room participation
"/initialSync":
get:
summary: Get the user's current state.
@ -154,7 +156,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 343511809,
@ -166,7 +168,7 @@ paths:
"origin_server_ts": 1432804487480,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
}
],
"end": "s3456_9_0",
@ -184,13 +186,12 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.join_rules",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:localhost",
@ -199,7 +200,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@alice:localhost",
"type": "m.room.member",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 7148267200,
@ -211,7 +212,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.create",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
},
{
"age": 1622568720,
@ -226,7 +227,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@bob:localhost",
"type": "m.room.member",
"user_id": "@bob:localhost"
"sender": "@bob:localhost"
},
{
"age": 7148267004,
@ -250,7 +251,7 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.power_levels",
"user_id": "@alice:localhost"
"sender": "@alice:localhost"
}
],
"visibility": "private",
@ -285,7 +286,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
rooms:
type: array
items:
@ -332,7 +333,7 @@ paths:
type: object
title: RoomEvent
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
required: ["start", "end", "chunk"]
state:
type: array
@ -345,7 +346,7 @@ paths:
title: StateEvent
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
visibility:
type: string
enum: ["private", "public"]
@ -361,11 +362,13 @@ paths:
title: Event
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
required: ["room_id", "membership"]
required: ["end", "rooms", "presence"]
404:
description: There is no avatar URL for this user or this user does not exist.
tags:
- Room participation
"/events/{eventId}":
get:
summary: Get a single event by event ID.
@ -392,12 +395,14 @@ paths:
"msgtype": "m.text"
},
"room_id:": "!wfgy43Sg4a:matrix.org",
"user_id": "@bob:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
schema:
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
404:
description: The event was not found or you do not have permission to read this event.
tags:
- Room participation

17
api/client-server/presence.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Presence API"
title: "Matrix Client-Server Presence API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -67,6 +67,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Presence
get:
summary: Get this user's presence state.
description: |-
@ -85,8 +87,7 @@ paths:
application/json: |-
{
"presence": "unavailable",
"last_active_ago": 420845,
"status_msg": null
"last_active_ago": 420845
}
schema:
type: object
@ -107,6 +108,8 @@ paths:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
tags:
- Presence
"/presence/list/{userId}":
post:
summary: Add or remove users from this presence list.
@ -161,6 +164,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Presence
get:
summary: Get presence events for this presence list.
description: |-
@ -205,4 +210,6 @@ paths:
type: object
title: PresenceEvent
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
tags:
- Presence

16
api/client-server/profile.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Profile API"
title: "Matrix Client-Server Profile API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -59,6 +59,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data
get:
summary: Get the user's display name.
description: |-
@ -88,6 +90,8 @@ paths:
description: The user's display name if they have set one.
404:
description: There is no display name for this user or this user does not exist.
tags:
- User data
"/profile/{userId}/avatar_url":
put:
summary: Set the user's avatar URL.
@ -129,6 +133,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data
get:
summary: Get the user's avatar URL.
description: |-
@ -158,6 +164,8 @@ paths:
description: The user's avatar URL if they have set one.
404:
description: There is no avatar URL for this user or this user does not exist.
tags:
- User data
"/profile/{userId}":
get:
summary: Get this user's profile information.
@ -192,4 +200,6 @@ paths:
type: string
description: The user's display name if they have set one.
404:
description: There is no profile information for this user or this user does not exist.
description: There is no profile information for this user or this user does not exist.
tags:
- User data

5
api/client-server/push_notifier.yaml
View file

@ -6,7 +6,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/push/v1
basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -189,4 +189,5 @@ paths:
items:
type: string
description: A pushkey
tags:
- Push notifications

10
api/client-server/pusher.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Push API"
title: "Matrix Client-Server Push API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -60,7 +60,6 @@ paths:
Max length, 512 bytes.
kind:
type: string
enum: ["http", null]
description: |-
The kind of pusher to configure. ``"http"`` makes a pusher that
sends HTTP pokes. ``null`` deletes the pusher.
@ -114,7 +113,7 @@ paths:
description: |-
If true, the homeserver should add another pusher with the
given pushkey and App ID in addition to any others with
different user IDs. Otherwise, the Home Server must remove any
different user IDs. Otherwise, the homeserver must remove any
other pushers with the same App ID and pushkey for different
users. The default is ``false``.
required: ['profile_tag', 'kind', 'app_id', 'app_display_name',
@ -141,4 +140,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Push notifications

37
api/client-server/pushrules.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Push Rules API"
title: "Matrix Client-Server Push Rules API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -45,14 +45,14 @@ paths:
description: The ruleset for this profile tag.
title: Ruleset
allOf: [
"$ref": "definitions/push_ruleset.json"
"$ref": "definitions/push_ruleset.yaml"
]
global:
type: object
description: The global ruleset.
title: Ruleset
allOf: [
"$ref": "definitions/push_ruleset.json"
"$ref": "definitions/push_ruleset.yaml"
]
examples:
application/json: |-
@ -245,6 +245,8 @@ paths:
]
}
}
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}":
get:
summary: Retrieve a push rule.
@ -295,8 +297,10 @@ paths:
description: The push rule.
title: PushRule
allOf: [
"$ref": "definitions/push_rule.json"
"$ref": "definitions/push_rule.yaml"
]
tags:
- Push notifications
delete:
summary: Delete a push rule.
description: |-
@ -335,6 +339,8 @@ paths:
{}
schema:
type: object # empty json object
tags:
- Push notifications
put:
summary: Add or change a push rule.
description: |-
@ -414,7 +420,7 @@ paths:
items:
type: object
title: conditions
allOf: [ "$ref": "definitions/push_condition.json" ]
allOf: [ "$ref": "definitions/push_condition.yaml" ]
required: ["actions"]
responses:
200:
@ -438,6 +444,8 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/enabled":
put:
summary: "Enable or disable a push rule."
@ -470,14 +478,21 @@ paths:
description: |
The identifier for the rule.
- in: body
name: <body>
name: body
description: |
Whether the push rule is enabled or not.
required: true
schema:
type: boolean
type: object
properties:
enabled:
type: boolean
description: Whether the push rule is enabled or not.
required: ["enabled"]
example: |-
true
{
"enabled": true
}
responses:
200:
description: The push rule was enabled or disabled.
@ -485,4 +500,6 @@ paths:
application/json: |-
{}
schema:
type: object # empty json object
type: object
tags:
- Push notifications

6
api/client-server/receipts.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 Receipts API"
title: "Matrix Client-Server Receipts API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -67,3 +67,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room participation

84
api/client-server/redaction.yaml Normal file
View file

@ -0,0 +1,84 @@
swagger: '2.0'
info:
title: "Matrix Client-Server message redaction API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION%
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}/redact/{eventId}/{txnId}":
put:
summary: Strips all non-integrity-critical information out of an event.
description: |-
Strips all information out of an event which isn't critical to the
integrity of the server-side representation of the room.
This cannot be undone.
Users may redact their own events, and any user with a power level
greater than or equal to the `redact` power level of the room may
redact events there.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room from which to redact the event.
required: true
x-example: "!637q39766251:example.com"
- in: path
type: string
name: eventId
description: The ID of the event to redact
required: true
x-example: "bai2b1i9:matrix.org"
- in: path
name: txnId
type: string
description: |-
The transaction ID for this event. Clients should generate a
unique ID; it will be used by the server to ensure idempotency of requests.
required: true
x-example: "37"
- in: body
name: body
schema:
type: object
example: |-
{
"reason": "Indecent material"
}
properties:
reason:
type: string
description: The reason for the event being redacted.
responses:
200:
description: "An ID for the redaction event."
examples:
application/json: |-
{
"event_id": "YUwQidLecu"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation

10
api/client-server/registration.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 Registration API"
title: "Matrix Client-Server Registration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -94,7 +94,7 @@ paths:
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
home_server:
type: string
description: The hostname of the Home Server on which the account has been registered.
description: The hostname of the homeserver on which the account has been registered.
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
@ -107,7 +107,7 @@ paths:
including after authentication if the requested user ID was registered
whilst the client was performing authentication.
Home Servers MUST perform the relevant checks and return these codes before
Homeservers MUST perform the relevant checks and return these codes before
performing `User-Interactive Authentication`_, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
@ -121,3 +121,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- User data

6
api/client-server/room_send.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 message event send API"
title: "Matrix Client-Server message event send API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -76,3 +76,5 @@ paths:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation

71
api/client-server/room_state.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 state event send API"
title: "Matrix Client-Server state event send API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -20,12 +20,12 @@ securityDefinitions:
paths:
"/rooms/{roomId}/state/{eventType}/{stateKey}":
put:
summary: Send a message event to the given room.
summary: Send a state event to the given room.
description: |
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
match. If the state event has an empty ``state_key``, it can be
omitted from the path.
State events can be sent using this endpoint. This endpoint is
equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
with an empty `stateKey`. Previous state events with matching
`<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
@ -78,3 +78,60 @@ paths:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
put:
summary: Send a state event to the given room.
description: |
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
match. This endpoint forces the state key to be the empty string.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
``state_key``. Furthermore, ``POST`` is unsupported on state paths.
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to set the state in
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.name"
- in: body
name: body
schema:
type: object
example: |-
{
"name": "New name for the room"
}
responses:
200:
description: "An ID for the sent event."
examples:
application/json: |-
{
"event_id": "YUwRidLecu"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
tags:
- Room participation

96
api/client-server/rooms.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Rooms API"
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -44,7 +44,7 @@ paths:
- in: path
type: string
name: stateKey
description: The key of the state to look up. Defaults to the empty string.
description: The key of the state to look up.
required: true
x-example: ""
responses:
@ -61,7 +61,49 @@ paths:
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.
@ -92,13 +134,12 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
@ -107,7 +148,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 7148267200,
@ -119,7 +160,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 1622568720,
@ -134,7 +175,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
},
{
"age": 7148267004,
@ -158,7 +199,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
}
]
schema:
@ -173,12 +214,13 @@ paths:
title: StateEvent
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
- "$ref": "../../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}/initialSync":
get:
summary: Snapshot the current state of a room and its most recent messages.
@ -212,7 +254,7 @@ paths:
"origin_server_ts": 1432804485886,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 343511809,
@ -224,7 +266,7 @@ paths:
"origin_server_ts": 1432804487480,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
}
],
"end": "s3456_9_0",
@ -242,13 +284,12 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
@ -257,7 +298,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 7148267200,
@ -269,7 +310,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 1622568720,
@ -284,7 +325,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
},
{
"age": 7148267004,
@ -308,7 +349,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
}
],
"visibility": "private",
@ -355,7 +396,7 @@ paths:
type: object
title: RoomEvent
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
required: ["start", "end", "chunk"]
state:
type: array
@ -368,7 +409,7 @@ paths:
title: StateEvent
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
visibility:
type: string
enum: ["private", "public"]
@ -383,13 +424,14 @@ paths:
title: Event
type: object
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
required: ["room_id"]
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.
@ -416,7 +458,6 @@ paths:
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"displayname": null,
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
@ -425,7 +466,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"user_id": "@alice:example.com"
"sender": "@alice:example.com"
},
{
"age": 1622568720,
@ -440,7 +481,7 @@ paths:
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"user_id": "@bob:example.com"
"sender": "@bob:example.com"
}
]
}
@ -458,4 +499,5 @@ paths:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation

17
api/client-server/search.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Search API"
title: "Matrix Client-Server Search API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,7 +74,6 @@ paths:
type: object
title: Filter
description: |-
The filter to apply to search results.
This has the same format as v2 filter API.
order_by:
title: "Ordering"
@ -178,7 +177,7 @@ paths:
title: Event
description: The event that matched.
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
context:
type: object
title: Event Context
@ -218,7 +217,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
events_after:
type: array
title: Events After
@ -227,7 +226,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: object
title: Current state
@ -238,7 +237,7 @@ paths:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
groups:
type: object
title: Groups
@ -309,7 +308,7 @@ paths:
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"type": "m.room.message",
"user_id": "@test:localhost"
"sender": "@test:localhost"
}
}
]
@ -322,3 +321,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Search

22
api/client-server/sync.yaml
View file

@ -1,11 +1,11 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v2 sync API"
title: "Matrix Client-Server sync API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -114,7 +114,7 @@ paths:
``timeline``, if ``since`` is not given, or
``full_state`` is true).
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
timeline:
title: Timeline
type: object
@ -122,7 +122,7 @@ paths:
The timeline of messages and state changes in the
room.
allOf:
- $ref: "definitions/timeline_batch.json"
- $ref: "definitions/timeline_batch.yaml"
ephemeral:
title: Ephemeral
type: object
@ -131,7 +131,7 @@ paths:
recorded in the timeline or state of the room.
e.g. typing.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
account_data:
title: Account Data
type: object
@ -139,7 +139,7 @@ paths:
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
invite:
title: Invited Rooms
type: object
@ -166,7 +166,7 @@ paths:
delta against the archived ``state`` not the
``invite_state``.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
leave:
title: Left rooms
type: object
@ -182,7 +182,7 @@ paths:
description: |-
The state updates for the room up to the start of the timeline.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
timeline:
title: Timeline
type: object
@ -190,14 +190,14 @@ paths:
The timeline of messages and state changes in the
room up to the point when the user left.
allOf:
- $ref: "definitions/timeline_batch.json"
- $ref: "definitions/timeline_batch.yaml"
presence:
title: Presence
type: object
description: |-
The updates to the presence status of other users.
allOf:
- $ref: "definitions/event_batch.json"
- $ref: "definitions/event_batch.yaml"
examples:
application/json: |-
{
@ -310,3 +310,5 @@ paths:
"leave": {}
}
}
tags:
- Room participation

8
api/client-server/tags.yaml
View file

@ -6,7 +6,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -59,6 +59,8 @@ paths:
"pinned": {}
}
}
tags:
- User data
"/user/{userId}/rooms/{roomId}/tags/{tag}":
put:
summary: Add a tag to a room.
@ -107,6 +109,8 @@ paths:
examples:
application/json: |-
{}
tags:
- User data
delete:
summary: Remove a tag from the room.
description: |-
@ -145,3 +149,5 @@ paths:
examples:
application/json: |-
{}
tags:
- User data

10
api/client-server/third_party_membership.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Room Membership API for third party identifiers"
title: "Matrix Client-Server Room Membership API for third party identifiers"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -39,7 +39,7 @@ paths:
join that room.
If the identity server did know the Matrix user identifier for the
third party identifier, the home server will append a ``m.room.member``
third party identifier, the homeserver will append a ``m.room.member``
event to the room.
If the identity server does not know a Matrix user identifier for the
@ -62,7 +62,7 @@ paths:
- The matrix user ID who invited them to the room
If a token is requested from the identity server, the home server will
If a token is requested from the identity server, the homeserver will
append a ``m.room.third_party_invite`` event to the room.
.. _joining rooms section: `invite-by-user-id-endpoint`_
@ -121,3 +121,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room membership

7
api/client-server/typing.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Typing API"
title: "Matrix Client-Server Typing API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -74,4 +74,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- Room participation

9
api/client-server/voip.yaml
View file

@ -1,12 +1,12 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Voice over IP API"
title: "Matrix Client-Server Voice over IP API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/api/v1
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -18,7 +18,7 @@ securityDefinitions:
name: access_token
in: query
paths:
"/turnServer":
"/voip/turnServer":
get:
summary: Obtain TURN server credentials.
description: |-
@ -65,4 +65,5 @@ paths:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
tags:
- VOIP