API documentation

This document describes how to use the API.

Output formats

You can specify an output format by using the format request parameter. If you do not specify a format, json will be used:

    /api/?format=json

The following formats are currently supported:

Format	Explanation
json	JSON
services.xml	XML, based on the Service Discovery Protocol format.
services-full.xml	A more descriptive XML format, compatible with the one from xmpp.org.

Filter by country

You can filter servers by countries by giving the country request parameter:

    /api/?country=at

There is no really reliable way of determining the server a country is in. The country is determined by the coordinates the server-admin gives when registering the server (and they in turn are not in any way verified).

Require features

You can limit the output to servers that have a certain feature. To do that, simply give the features request parameter:

    /api/?features=tls,ipv6

The following features are currently recognized:

Feature	Explanation
plain	Servers that allow plain, unencrypted connections.
ssl	Servers that allow connections via SSL.
tls	Servers that allow connections via TLS.
ipv6	Servers that have IPv6 connectivity.

Note: Currently only IPv6 is actually verified, all other features will always return an empty list.

Output additional fields

By default, The API outputs only a list of JIDs. You can request more fields via the fields request parameter:

    /api/?fields=website,ca

Currently the following fields are supported:

Field	Explanation
launched	When the server was launched.
location	Where the server is located.
website	The website of the server.
ca	The Certificate Autority of the server.
software	The software this server uses.
software_version	The version of the software the server uses.
contact	The contact address of this server.

Note: The output of this feature is still subject to change.
Note: The fields parameter is ignored when using format=services.xml or format=services-full.xml.