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.
403 lines
17 KiB
YAML
403 lines
17 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server v1 Sync 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:
|
|
"/events":
|
|
get:
|
|
summary: Listen on the event stream.
|
|
description: |-
|
|
This will listen for new events and return them to the caller. This will
|
|
block until an event is received, or until the ``timeout`` is reached.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: query
|
|
type: string
|
|
name: from
|
|
description: |-
|
|
The token to stream from. This token is either from a previous
|
|
request to this API or from the initial sync API.
|
|
required: false
|
|
x-example: "s3456_9_0"
|
|
- in: query
|
|
type: integer
|
|
name: timeout
|
|
description: The maximum time in milliseconds to wait for an event.
|
|
required: false
|
|
x-example: "35000"
|
|
responses:
|
|
200:
|
|
description: "The events received, which may be none."
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"start": "s3456_9_0",
|
|
"end": "s3457_9_0",
|
|
"chunk": [
|
|
{
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
start:
|
|
type: string
|
|
description: |-
|
|
A token which correlates to the first value in ``chunk``. This
|
|
is usually the same token supplied to ``from=``.
|
|
end:
|
|
type: string
|
|
description: |-
|
|
A token which correlates to the last value in ``chunk``. This
|
|
token should be used in the next request to ``/events``.
|
|
chunk:
|
|
type: array
|
|
description: "An array of events."
|
|
items:
|
|
type: object
|
|
title: Event
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
|
|
400:
|
|
description: "Bad pagination ``from`` parameter."
|
|
"/initialSync":
|
|
get:
|
|
summary: Get the user's current state.
|
|
description: |-
|
|
This returns the full state for this user, with an optional limit on the
|
|
number of messages per room to return.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: query
|
|
type: integer
|
|
name: limit
|
|
description: The maximum number of messages to return for each room.
|
|
required: false
|
|
x-example: "2"
|
|
- in: query
|
|
type: boolean
|
|
name: archived
|
|
description: |-
|
|
Whether to include rooms that the user has left. If ``false`` then
|
|
only rooms that the user has been invited to or has joined are
|
|
included. If set to ``true`` then rooms that the user has left are
|
|
included as well. By default this is ``false``.
|
|
required: false
|
|
x-example: "true"
|
|
responses:
|
|
200:
|
|
description: The user's current state.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"end": "s3456_9_0",
|
|
"presence": [
|
|
{
|
|
"content": {
|
|
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
|
|
"displayname": "Bob",
|
|
"last_active_ago": 31053,
|
|
"presence": "online",
|
|
"user_id": "@bob:localhost"
|
|
},
|
|
"type": "m.presence"
|
|
}
|
|
],
|
|
"account_data": [
|
|
{
|
|
"type": "org.example.custom.config",
|
|
"content": {
|
|
"custom_config_key": "custom_config_value"
|
|
}
|
|
}
|
|
],
|
|
"rooms": [
|
|
{
|
|
"membership": "join",
|
|
"messages": {
|
|
"chunk": [
|
|
{
|
|
"age": 343513403,
|
|
"content": {
|
|
"body": "foo",
|
|
"msgtype": "m.text"
|
|
},
|
|
"event_id": "$14328044851tzTJS:localhost",
|
|
"origin_server_ts": 1432804485886,
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"type": "m.room.message",
|
|
"user_id": "@alice:localhost"
|
|
},
|
|
{
|
|
"age": 343511809,
|
|
"content": {
|
|
"body": "bar",
|
|
"msgtype": "m.text"
|
|
},
|
|
"event_id": "$14328044872spjFg:localhost",
|
|
"origin_server_ts": 1432804487480,
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"type": "m.room.message",
|
|
"user_id": "@bob:localhost"
|
|
}
|
|
],
|
|
"end": "s3456_9_0",
|
|
"start": "t44-3453_9_0"
|
|
},
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"state": [
|
|
{
|
|
"age": 7148266897,
|
|
"content": {
|
|
"join_rule": "public"
|
|
},
|
|
"event_id": "$14259997323TLwtb:localhost",
|
|
"origin_server_ts": 1425999732392,
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"state_key": "",
|
|
"type": "m.room.join_rules",
|
|
"user_id": "@alice:localhost"
|
|
},
|
|
{
|
|
"age": 6547561012,
|
|
"content": {
|
|
"avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
|
|
"displayname": null,
|
|
"membership": "join"
|
|
},
|
|
"event_id": "$1426600438280zExKY:localhost",
|
|
"membership": "join",
|
|
"origin_server_ts": 1426600438277,
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"state_key": "@alice:localhost",
|
|
"type": "m.room.member",
|
|
"user_id": "@alice:localhost"
|
|
},
|
|
{
|
|
"age": 7148267200,
|
|
"content": {
|
|
"creator": "@alice:localhost"
|
|
},
|
|
"event_id": "$14259997320KhbwJ:localhost",
|
|
"origin_server_ts": 1425999732089,
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"state_key": "",
|
|
"type": "m.room.create",
|
|
"user_id": "@alice:localhost"
|
|
},
|
|
{
|
|
"age": 1622568720,
|
|
"content": {
|
|
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
|
|
"displayname": "Bob",
|
|
"membership": "join"
|
|
},
|
|
"event_id": "$1431525430134MxlLX:localhost",
|
|
"origin_server_ts": 1431525430569,
|
|
"replaces_state": "$142652023736BSXcM:localhost",
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"state_key": "@bob:localhost",
|
|
"type": "m.room.member",
|
|
"user_id": "@bob:localhost"
|
|
},
|
|
{
|
|
"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:localhost": 100
|
|
},
|
|
"users_default": 0
|
|
},
|
|
"event_id": "$14259997322mqfaq:localhost",
|
|
"origin_server_ts": 1425999732285,
|
|
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
|
|
"state_key": "",
|
|
"type": "m.room.power_levels",
|
|
"user_id": "@alice:localhost"
|
|
}
|
|
],
|
|
"visibility": "private",
|
|
"account_data": [
|
|
{
|
|
"type": "m.tag",
|
|
"content": {"tags": {"work": {"order": 1}}}
|
|
},
|
|
{
|
|
"type": "org.example.custom.room.config",
|
|
"content": {
|
|
"custom_config_key": "custom_config_value"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
end:
|
|
type: string
|
|
description: |-
|
|
A token which correlates to the last value in ``chunk``. This
|
|
token should be used with the ``/events`` API to listen for new
|
|
events.
|
|
presence:
|
|
type: array
|
|
description: A list of presence events.
|
|
items:
|
|
type: object
|
|
title: Event
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
|
|
rooms:
|
|
type: array
|
|
items:
|
|
type: object
|
|
title: RoomInfo
|
|
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"]
|
|
invite:
|
|
type: object
|
|
title: "InviteEvent"
|
|
description: "The invite event if ``membership`` is ``invite``"
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/m.room.member"
|
|
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", "membership"]
|
|
required: ["end", "rooms", "presence"]
|
|
404:
|
|
description: There is no avatar URL for this user or this user does not exist.
|
|
"/events/{eventId}":
|
|
get:
|
|
summary: Get a single event by event ID.
|
|
description: |-
|
|
Get a single event based on ``event_id``. You must have permission to
|
|
retrieve this event e.g. by being a member in the room for this event.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: eventId
|
|
description: The event ID to get.
|
|
required: true
|
|
x-example: "$asfDuShaf7Gafaw:matrix.org"
|
|
responses:
|
|
200:
|
|
description: The full event.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"content": {
|
|
"body": "Hello world!",
|
|
"msgtype": "m.text"
|
|
},
|
|
"room_id:": "!wfgy43Sg4a:matrix.org",
|
|
"user_id": "@bob:matrix.org",
|
|
"event_id": "$asfDuShaf7Gafaw:matrix.org",
|
|
"type": "m.room.message"
|
|
}
|
|
schema:
|
|
allOf:
|
|
- "$ref": "../../event-schemas/schema/core-event-schema/event.json"
|
|
404:
|
|
description: The event was not found or you do not have permission to read this event.
|