mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-31 04:58:37 +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.
209 lines
6.5 KiB
YAML
209 lines
6.5 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server v1 Presence 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:
|
|
"/presence/{userId}/status":
|
|
put:
|
|
summary: Update this user's presence state.
|
|
description: |-
|
|
This API sets the given user's presence state. When setting the status,
|
|
the activity time is updated to reflect that activity; the client does
|
|
not need to specify the ``last_active_ago`` field. You cannot set the
|
|
presence state of another user.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose presence state to update.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
- in: body
|
|
name: presenceState
|
|
description: The updated presence state.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: |-
|
|
{
|
|
"presence": "online",
|
|
"status_msg": "I am here."
|
|
}
|
|
properties:
|
|
presence:
|
|
type: string
|
|
enum: ["online", "offline", "unavailable", "free_for_chat"]
|
|
description: The new presence state.
|
|
status_msg:
|
|
type: string
|
|
description: "The status message to attach to this state."
|
|
required: ["presence"]
|
|
responses:
|
|
200:
|
|
description: The new presence state was set.
|
|
examples:
|
|
application/json: |-
|
|
{}
|
|
schema:
|
|
type: object # empty json object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
get:
|
|
summary: Get this user's presence state.
|
|
description: |-
|
|
Get the given user's presence state.
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose presence state to get.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: The presence state for this user.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"presence": "unavailable",
|
|
"last_active_ago": 420845,
|
|
"status_msg": null
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
presence:
|
|
type: string
|
|
enum: ["online", "offline", "unavailable", "free_for_chat"]
|
|
description: This user's presence.
|
|
last_active_ago:
|
|
type: integer
|
|
description: |-
|
|
The length of time in milliseconds since an action was performed
|
|
by this user.
|
|
status_msg:
|
|
type: string
|
|
description: The state message for this user if one was set.
|
|
404:
|
|
description: |-
|
|
There is no presence state for this user. This user may not exist or
|
|
isn't exposing presence information to you.
|
|
"/presence/list/{userId}":
|
|
post:
|
|
summary: Add or remove users from this presence list.
|
|
description: |-
|
|
Adds or removes users from this presence list.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose presence list is being modified.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
- in: body
|
|
name: presence_diff
|
|
description: The modifications to make to this presence list.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: |-
|
|
{
|
|
"invite": [
|
|
"@bob:matrix.org"
|
|
],
|
|
"drop": [
|
|
"@alice:matrix.org"
|
|
]
|
|
}
|
|
properties:
|
|
invite:
|
|
type: array
|
|
description: A list of user IDs to add to the list.
|
|
items:
|
|
type: string
|
|
description: A list of user IDs.
|
|
drop:
|
|
type: array
|
|
description: A list of user IDs to remove from the list.
|
|
items:
|
|
type: string
|
|
description: A list of user IDs.
|
|
responses:
|
|
200:
|
|
description: The list was updated.
|
|
examples:
|
|
application/json: |-
|
|
{}
|
|
schema:
|
|
type: object # empty json object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
get:
|
|
summary: Get presence events for this presence list.
|
|
description: |-
|
|
Retrieve a list of presence events for every user on this list.
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose presence list should be retrieved.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: A list of presence events for this list.
|
|
examples:
|
|
application/json: |-
|
|
[
|
|
{
|
|
"content": {
|
|
"avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP",
|
|
"displayname": "Alice Margatroid",
|
|
"last_active_ago": 395,
|
|
"presence": "offline",
|
|
"user_id": "@alice:matrix.org"
|
|
}
|
|
"type": "m.presence"
|
|
},
|
|
{
|
|
"content": {
|
|
"avatar_url": "mxc://matrix.org/FWEhuiwegfWEfhuiwf",
|
|
"displayname": "Marisa Kirisame",
|
|
"last_active_ago": 16874,
|
|
"presence": "online",
|
|
"user_id": "@marisa:matrix.org"
|
|
}
|
|
"type": "m.presence"
|
|
}
|
|
]
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
title: PresenceEvent
|
|
allOf:
|
|
- "$ref": "core-event-schema/event.json"
|