mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-28 03:48:36 +01:00
7f81501762
Rename "schema/v1/core" to "schema/v1/core-event-schema". Add self-referential symlinks to schema/v1/core-event-schema The python json schema libraries expect that relative references are relative to the file they are in. The node json schema libraries expect that relateive references are relative to the first file loaded. To support both kinds we reference the core event schema using "core-event-schema/event.json". We then symlink the core-event-schema directory to both the location of the file refering to "event.json" so that it will work in python and to the location of the top level file so that it will work in node.
356 lines
15 KiB
YAML
356 lines
15 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.
|
|
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``. Used
|
|
for pagination.
|
|
end:
|
|
type: string
|
|
description: |-
|
|
A token which correlates to the last value in ``chunk``. Used
|
|
for pagination.
|
|
chunk:
|
|
type: array
|
|
description: "An array of events."
|
|
items:
|
|
type: object
|
|
title: RoomEvent
|
|
allOf:
|
|
- "$ref": "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"
|
|
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"
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
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": "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"]
|
|
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": "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": "core-event-schema/state_event.json"
|
|
visibility:
|
|
type: string
|
|
enum: ["private", "public"]
|
|
description: |-
|
|
Whether this room is visible to the ``/publicRooms`` API
|
|
or not."
|
|
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": "core-event-schema/event.json"
|
|
404:
|
|
description: The event was not found or you do not have permission to read this event.
|