---
openapi: 3.0.1
info:
title: mod_rest API
version: 0.3.2
description: |
API for sending and receiving stanzas, in a REST-ish fashion or by
responding to webhooks. Multiple formats supported, including native XML
and a simplified JSON mapping.
license:
name: MIT
paths:
/rest:
post:
summary: Send stanzas and receive responses. Webhooks work the same way.
tags:
- generic
security:
- basic: []
- token: []
- oauth2: []
requestBody:
$ref: '#/components/requestBodies/common'
responses:
"200":
$ref: '#/components/responses/success'
"202":
$ref: '#/components/responses/sent'
/rest/{kind}/{type}/{to}:
post:
summary: Even more RESTful mapping with certain components in the path.
tags:
- generic
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/kind'
- $ref: '#/components/parameters/type'
- $ref: '#/components/parameters/to'
requestBody:
$ref: '#/components/requestBodies/common'
responses:
"200":
$ref: '#/components/responses/success'
/rest/echo:
post:
summary: Build as stanza and return it for inspection.
tags:
- debug
security:
- basic: []
- token: []
- oauth2: []
requestBody:
$ref: '#/components/requestBodies/common'
responses:
"200":
$ref: '#/components/responses/success'
/rest/ping/{to}:
get:
tags:
- query
summary: Ping a local or remote server or other entity
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
description: Test reachability of some address
content:
application/json:
schema:
$ref: '#/components/schemas/iq_pong'
application/xmpp+xml:
schema:
$ref: '#/components/schemas/iq_pong'
/rest/version/{to}:
get:
tags:
- query
summary: Ask what software version is used.
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
description: Version query response
content:
application/json:
schema:
$ref: '#/components/schemas/iq_result_version'
application/xmpp+xml:
schema:
$ref: '#/components/schemas/iq_result_version'
/rest/disco/{to}:
get:
tags:
- query
summary: Query a remote entity for supported features
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
$ref: '#/components/responses/success'
/rest/items/{to}:
get:
tags:
- query
summary: Query an entity for related services, chat rooms or other items
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
$ref: '#/components/responses/success'
/rest/extdisco/{to}:
get:
tags:
- query
summary: Query for external services (usually STUN and TURN)
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
- name: type
in: query
schema:
type: string
example: stun
responses:
"200":
$ref: '#/components/responses/success'
/rest/archive/{to}:
get:
tags:
- query
summary: Query a message archive
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
- name: with
in: query
schema:
type: string
- name: start
in: query
schema:
type: string
- name: end
in: query
schema:
type: string
- name: before-id
in: query
schema:
type: string
- name: after-id
in: query
schema:
type: string
- name: ids
in: query
schema:
type: string
description: comma-separated list of archive ids
- name: after
in: query
schema:
type: string
- name: before
in: query
schema:
type: string
- name: max
in: query
schema:
type: integer
responses:
"200":
$ref: '#/components/responses/success'
/rest/lastactivity/{to}:
get:
tags:
- query
summary: Query last activity of an entity. Sometimes used as "uptime" for servers.
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
$ref: '#/components/responses/success'
/rest/stats/{to}:
get:
tags:
- query
summary: Query an entity for statistics
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
$ref: '#/components/responses/success'
/rest/upload_request/{to}:
get:
tags:
- query
summary: Lorem ipsum
security:
- basic: []
- token: []
- oauth2: []
parameters:
- $ref: '#/components/parameters/to'
responses:
"200":
$ref: '#/components/responses/success'
components:
schemas:
stanza:
type: object
example:
body: Hello
type: chat
kind: message
to: alice@example.com
state: active
oneOf:
- $ref: '#/components/schemas/message'
- $ref: '#/components/schemas/presence'
- $ref: '#/components/schemas/iq'
message:
type: object
xml:
name: message
properties:
kind:
description: Which kind of stanza
type: string
enum:
- message
type:
type: string
enum:
- chat
- error
- groupchat
- headline
- normal
xml:
attribute: true
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
id:
$ref: '#/components/schemas/id'
lang:
$ref: '#/components/schemas/lang'
body:
$ref: '#/components/schemas/body'
subject:
$ref: '#/components/schemas/subject'
thread:
$ref: '#/components/schemas/thread'
invite:
$ref: '#/components/schemas/invite'
state:
$ref: '#/components/schemas/state'
nick:
$ref: '#/components/schemas/nick'
delay:
$ref: '#/components/schemas/delay'
replace:
$ref: '#/components/schemas/replace'
html:
$ref: '#/components/schemas/html'
oob:
$ref: '#/components/schemas/oob'
reactions:
$ref: '#/components/schemas/reactions'
occupant_id:
$ref: '#/components/schemas/occupant_id'
attach_to:
$ref: '#/components/schemas/attach_to'
fallback:
$ref: '#/components/schemas/fallback'
stanza_ids:
$ref: '#/components/schemas/stanza_ids'
reference:
$ref: '#/components/schemas/reference'
reply:
$ref: '#/components/schemas/reply'
markable:
$ref: '#/components/schemas/markable'
displayed:
$ref: '#/components/schemas/displayed'
encryption:
$ref: '#/components/schemas/encryption'
archive:
$ref: '#/components/schemas/archive_result'
dataform:
$ref: '#/components/schemas/dataform'
forwarded:
$ref: '#/components/schemas/forwarded'
error:
$ref: '#/components/schemas/error'
presence:
type: object
properties:
kind:
description: Which kind of stanza
type: string
enum:
- presence
type:
type: string
enum:
- available
- unavailable
- subscribe
- subscribed
- unsubscribe
- unsubscribed
- error
xml:
attribute: true
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
id:
$ref: '#/components/schemas/id'
lang:
$ref: '#/components/schemas/lang'
show:
$ref: '#/components/schemas/show'
status:
$ref: '#/components/schemas/status'
priority:
$ref: '#/components/schemas/priority'
caps:
$ref: '#/components/schemas/caps'
nick:
$ref: '#/components/schemas/nick'
delay:
$ref: '#/components/schemas/delay'
vcard_update:
$ref: '#/components/schemas/vcard_update'
idle_since:
$ref: '#/components/schemas/idle_since'
muc:
$ref: '#/components/schemas/muc'
error:
$ref: '#/components/schemas/error'
iq:
type: object
properties:
kind:
description: Which kind of stanza
type: string
enum:
- iq
type:
type: string
enum:
- get
- set
- result
- error
xml:
attribute: true
to:
$ref: '#/components/schemas/to'
from:
$ref: '#/components/schemas/from'
id:
$ref: '#/components/schemas/id'
lang:
$ref: '#/components/schemas/lang'
ping:
$ref: '#/components/schemas/ping'
version:
$ref: '#/components/schemas/version'
lastactivity:
$ref: '#/components/schemas/lastactivity'
disco:
$ref: '#/components/schemas/disco'
items:
$ref: '#/components/schemas/items'
command:
$ref: '#/components/schemas/command'
stats:
$ref: '#/components/schemas/stats'
payload:
$ref: '#/components/schemas/payload'
gateway:
$ref: '#/components/schemas/gateway'
register:
$ref: '#/components/schemas/register'
extdisco:
$ref: '#/components/schemas/extdisco'
upload_request:
$ref: '#/components/schemas/upload_request'
upload_slot:
$ref: '#/components/schemas/upload_slot'
error:
$ref: '#/components/schemas/error'
iq_pong:
description: Test reachability of some XMPP address
type: object
xml:
name: iq
properties:
type:
type: string
enum:
- result
xml:
attribute: true
iq_result_version:
description: Version query response
type: object
xml:
name: iq
properties:
type:
type: string
enum:
- result
xml:
attribute: true
version:
$ref: '#/components/schemas/version'
kind:
description: Which kind of stanza
type: string
enum:
- message
- presence
- iq
type:
description: Stanza type
type: string
enum:
- chat
- normal
- headline
- groupchat
- get
- set
- result
- available
- unavailable
- subscribe
- subscribed
- unsubscribe
- unsubscribed
xml:
attribute: true
to:
description: the intended recipient for the stanza
example: alice@example.com
format: xmpp-jid
type: string
xml:
attribute: true
from:
description: the sender of the stanza
example: bob@example.net
format: xmpp-jid
type: string
xml:
attribute: true
id:
description: Reasonably unique id. mod_rest generates one if left out.
type: string
xml:
attribute: true
lang:
description: Language code
example: en
xml:
prefix: xml
attribute: true
type: string
body:
description: Human-readable chat message
example: Hello, World!
type: string
subject:
description: Subject of message or group chat
example: Talking about stuff
type: string
thread:
description: Message thread identifier
properties:
parent:
type: string
xml:
attribute: true
id:
type: string
xml:
text: true
show:
description: indicator of availability, ie away or not
type: string
enum:
- away
- chat
- dnd
- xa
status:
description: Textual status message.
type: string
priority:
description: Presence priority
type: integer
maximum: 127
minimum: -128
state:
description: Chat state notifications, e.g. "is typing..."
type: string
xml:
namespace: http://jabber.org/protocol/chatstates
x_name_is_value: true
enum:
- active
- inactive
- gone
- composing
- paused
example: composing
nick:
type: string
description: Nickname of the sender
xml:
name: nick
namespace: http://jabber.org/protocol/nick
delay:
type: string
format: date-time
description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 format.
title: 'XEP-0203: Delayed Delivery'
xml:
name: delay
namespace: urn:xmpp:delay
x_single_attribute: stamp
replace:
type: string
description: ID of message being replaced (e.g. for corrections)
xml:
name: replace
namespace: urn:xmpp:message-correct:0
x_single_attribute: id
muc:
description: Multi-User-Chat related
type: object
xml:
name: x
namespace: http://jabber.org/protocol/muc
properties:
history:
type: object
properties:
maxchars:
type: integer
minimum: 0
xml:
attribute: true
maxstanzas:
type: integer
minimum: 0
xml:
attribute: true
seconds:
type: integer
minimum: 0
xml:
attribute: true
since:
type: string
format: date-time
xml:
attribute: true
invite:
description: Invite to a group chat
title: 'XEP-0249: Direct MUC Invitations'
type: object
required:
- jid
xml:
name: x
namespace: jabber:x:conference
properties:
jid:
type: string
description: Address of the group chat
format: xmpp-jid
xml:
attribute: true
reason:
type: string
description: Optional message by the inviter
xml:
attribute: true
password:
type: string
description: Password for the group chat, if required
xml:
attribute: true
thread:
type: string
xml:
attribute: true
continue:
type: boolean
description: Whether the group chat continues a one-to-one chat
xml:
attribute: true
html:
description: HTML version of 'body'
example: <body><p>Hello!</p></body>
type: string
ping:
description: A ping.
type: boolean
enum:
- true
xml:
name: ping
namespace: urn:xmpp:ping
version:
type: object
description: Software version query
properties:
name:
type: string
example: My Software
version:
type: string
example: 1.0.0
os:
type: string
example: Linux
required:
- name
- version
xml:
name: query
namespace: jabber:iq:version
disco:
description: Discover supported features
oneOf:
- description: A full response
type: object
properties:
features:
description: List of URIs indicating supported features
type: array
items:
type: string
identities:
description: List of abstract identities or types that describe the entity
type: array
example:
- name: Prosody
type: im
category: server
items:
type: object
properties:
name:
type: string
type:
type: string
category:
type: string
node:
type: string
extensions:
type: object
- description: A query with a node, or an empty response with a node
type: string
- description: Either a query, or an empty response
type: boolean
items:
description: List of references to other entities
oneOf:
- description: List of items referenced
type: array
items:
properties:
jid:
type: string
description: Address of item
node:
type: string
name:
type: string
description: Descriptive name
required:
- jid
type: object
- type: string
description: A query with a node, or an empty reply list with a node
- description: An items query or empty list
type: boolean
enum:
- true
command:
description: Ad-hoc commands.
oneOf:
- type: object
properties:
data:
$ref: '#/components/schemas/formdata'
action:
type: string
note:
type: object
properties:
text:
type: string
type:
type: string
enum:
- info
- warn
- error
form:
$ref: '#/components/schemas/dataform'
sessionid:
type: string
status:
type: string
node:
type: string
actions:
type: object
properties:
complete:
type: boolean
prev:
type: boolean
next:
type: boolean
execute:
type: string
- type: string
description: Call a command by 'node' id, without arguments
oob:
type: object
description: Reference a media file
xml:
name: x
namespace: jabber:x:oob
properties:
url:
type: string
description: URL of the attached media file
example: https://media.example.net/thisfile.jpg
format: uri
desc:
description: Optional description
type: string
payload:
title: 'XEP-0335: JSON Containers'
description: A piece of arbitrary JSON with a type field attached
type: object
xml:
name: payload
namespace: urn:xmpp:json-msg:0
required:
- datatype
- data
properties:
data:
example: '{"some":"json"}'
type: object
datatype:
example: urn:example:my-json#payload
type: string
rsm:
title: 'XEP-0059: Result Set Management'
xml:
name: set
namespace: http://jabber.org/protocol/rsm
type: object
properties:
last:
type: string
max:
type: integer
index:
type: integer
count:
type: integer
before:
type: string
after:
type: string
first:
type: string
archive_query:
title: 'XEP-0313: Message Archive Management'
type: object
properties:
queryid:
xml:
attribute: true
type: string
page:
$ref: '#/components/schemas/rsm'
form:
$ref: '#/components/schemas/dataform'
xml:
name: query
namespace: urn:xmpp:mam:2
archive_result:
title: 'XEP-0313: Message Archive Management'
xml:
namespace: urn:xmpp:mam:2
name: result
type: object
properties:
queryid:
type: string
xml:
attribute: true
forward:
$ref: '#/components/schemas/forwarded'
forwarded:
title: 'XEP-0297: Stanza Forwarding'
xml:
name: forwarded
namespace: urn:xmpp:forward:0
type: object
properties:
message:
$ref: '#/components/schemas/message'
delay:
$ref: '#/components/schemas/delay'
dataform:
description: Data form
type: object
properties:
title:
description: Title of the form
example: TPS Report
type: string
fields:
type: array
items:
description: Form field
type: object
properties:
value:
description: Field value
oneOf:
- type: string
- type: array
items:
type: string
type:
description: Type of form field
type: string
label:
description: Descriptive label for the field
type: string
desc:
description: Longer description, i.e. that would go in a tooltip
type: string
required:
description: Whether the field must be included in the form
type: boolean
var:
description: Internal name of the field
type: string
type:
type: string
enum:
- form
- submit
- cancel
- result
instructions:
type: string
formdata:
description: Simplified data form carrying only values
type: object
additionalProperties:
oneOf:
- type: string
- type: array
items:
type: string
stats:
description: Statistics
type: array
xml:
name: query
namespace: http://jabber.org/protocol/stats
wrapped: true
items:
type: object
properties:
name:
type: string
xml:
attribute: true
unit:
type: string
xml:
attribute: true
value:
type: string
xml:
attribute: true
lastactivity:
type: object
xml:
name: query
namespace: jabber:iq:last
properties:
seconds:
type: integer
minimum: 0
xml:
attribute: true
status:
type: string
xml:
text: true
caps:
type: object
xml:
name: c
namespace: http://jabber.org/protocol/caps
properties:
ver:
type: string
xml:
attribute: true
hash:
type: string
xml:
attribute: true
node:
type: string
xml:
attribute: true
ext:
type: string
xml:
attribute: true
vcard_update:
type: object
xml:
name: x
namespace: vcard-temp:x:update
properties:
photo:
type: string
example: adc83b19e793491b1c6ea0fd8b46cd9f32e592fc
reactions:
type: object
xml:
namespace: urn:xmpp:reactions:0
properties:
id:
type: string
xml:
attribute: true
reactions:
type: array
items:
xml:
name: reaction
type: string
xml:
wrapped: false
name: reactions
occupant_id:
type: string
xml:
namespace: urn:xmpp:occupant-id:0
x_single_attribute: id
name: occupant-id
attach_to:
type: string
xml:
namespace: urn:xmpp:message-attaching:1
x_single_attribute: id
name: attach-to
fallback:
type: boolean
xml:
namespace: urn:xmpp:fallback:0
x_name_is_value: true
name: fallback
stanza_ids:
type: array
items:
type: object
required:
- id
- by
xml:
namespace: urn:xmpp:sid:0
name: stanza-id
properties:
id:
xml:
attribute: true
type: string
by:
xml:
attribute: true
format: xmpp-jid
type: string
reference:
type: object
xml:
namespace: urn:xmpp:reference:0
properties:
end:
minimum: 0
xml:
attribute: true
type: integer
uri:
xml:
attribute: true
format: uri
type: string
begin:
minimum: 0
xml:
attribute: true
type: integer
type:
xml:
attribute: true
type: string
required:
- type
- uri
reply:
title: 'XEP-0461: Message Replies'
description: Reference a message being replied to
type: object
xml:
name: reply
namespace: urn:xmpp:reply:0
properties:
to:
type: string
xml:
attribute: true
id:
type: string
xml:
attribute: true
markable:
type: boolean
xml:
namespace: urn:xmpp:chat-markers:0
x_name_is_value: true
displayed:
type: string
description: Message ID of a message that has been displayed
xml:
namespace: urn:xmpp:chat-markers:0
x_single_attribute: id
idle_since:
type: string
xml:
namespace: urn:xmpp:idle:1
x_single_attribute: since
name: idle
format: date-time
gateway:
type: object
xml:
namespace: jabber:iq:gateway
name: query
properties:
desc:
type: string
prompt:
type: string
jid:
type: string
extdisco:
type: object
xml:
namespace: urn:xmpp:extdisco:2
name: services
properties:
type:
xml:
attribute: true
type: string
services:
items:
type: object
xml:
name: service
required:
- type
- host
properties:
transport:
xml:
attribute: true
type: string
type:
xml:
attribute: true
type: string
port:
xml:
attribute: true
type: integer
host:
xml:
attribute: true
type: string
expires:
xml:
attribute: true
format: datetime
type: string
username:
xml:
attribute: true
type: string
password:
xml:
attribute: true
type: string
restricted:
xml:
attribute: true
type: boolean
name:
xml:
attribute: true
type: string
type: array
register:
type: object
description: Register with a service
xml:
namespace: jabber:iq:register
name: query
properties:
nick:
type: string
misc:
type: string
password:
type: string
date:
type: string
address:
type: string
key:
type: string
text:
type: string
url:
type: string
zip:
type: string
phone:
type: string
last:
type: string
email:
type: string
remove:
xml:
x_name_is_value: true
type: boolean
city:
type: string
registered:
xml:
x_name_is_value: true
type: boolean
first:
type: string
state:
type: string
instructions:
type: string
username:
type: string
name:
type: string
required:
- username
- password
upload_slot:
type: object
xml:
name: slot
namespace: urn:xmpp:http:upload:0
properties:
put:
type: object
properties:
url:
type: string
format: uri
xml:
attribute: true
headers:
type: array
items:
type: object
required:
- name
- value
xml:
name: header
properties:
name:
type: string
enum:
- Authorization
- Cookie
- Expires
xml:
attribute: true
value:
type: string
xml:
text: true
get:
type: object
properties:
url:
type: string
format: uri
xml:
attribute: true
upload_request:
type: object
required:
- filename
- size
xml:
name: request
namespace: urn:xmpp:http:upload:0
properties:
filename:
type: string
xml:
attribute: true
content-type:
xml:
attribute: true
name: content-type
size:
type: integer
xml:
attribute: true
encryption:
title: 'XEP-0380: Explicit Message Encryption'
type: string
xml:
x_single_attribute: namespace
name: encryption
namespace: urn:xmpp:eme:0
error:
description: Description of something gone wrong. See the Stanza Errors section in RFC 6120.
type: object
properties:
type:
description: General category of error
type: string
enum:
- auth
- cancel
- continue
- modify
- wait
condition:
description: Specific error condition.
type: string
enum:
- bad-request
- conflict
- feature-not-implemented
- forbidden
- gone
- internal-server-error
- item-not-found
- jid-malformed
- not-acceptable
- not-allowed
- not-authorized
- policy-violation
- recipient-unavailable
- redirect
- registration-required
- remote-server-not-found
- remote-server-timeout
- resource-constraint
- service-unavailable
- subscription-required
- undefined-condition
- unexpected-request
code:
description: Legacy numeric error code. Similar to HTTP status codes.
type: integer
text:
description: Description of error intended for human eyes.
type: string
by:
description: Originator of the error, when different from the stanza @from attribute
type: string
xml:
attribute: true
securitySchemes:
token:
description: Tokens from mod_http_oauth2.
scheme: Bearer
type: http
basic:
description: Use JID as username.
scheme: Basic
type: http
oauth2:
description: Needs mod_http_oauth2
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth2/authorize
tokenUrl: https://example.com/oauth2/token
scopes:
prosody:restricted: Restricted account
prosody:user: Regular user privileges
prosody:admin: Administrator privileges
prosody:operator: Server operator privileges
requestBodies:
common:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/stanza'
application/xmpp+xml:
schema:
description: Single XMPP stanza in XML format.
application/x-www-form-urlencoded:
schema:
description: A subset of the JSON schema, only top level string fields.
responses:
success:
description: The stanza was sent and returned a response.
content:
application/json:
schema:
$ref: '#/components/schemas/stanza'
application/xmpp+xml:
schema:
description: Single XMPP stanza in XML format.
example: <message><body>Hello</body></message>
application/x-www-form-urlencoded:
schema:
description: A subset of the JSON schema, only top level string fields.
example: body=Hello
text/plain:
schema:
description: Plain text response used as message body.
example: Hello
type: string
sent:
description: The stanza was sent without problem, and without response, so an empty reply.
parameters:
to:
name: to
in: path
required: true
schema:
$ref: '#/components/schemas/to'
kind:
name: kind
in: path
required: true
schema:
$ref: '#/components/schemas/kind'
type:
name: type
in: path
required: true
schema:
$ref: '#/components/schemas/type'