Owl DeveloperOverview
The public, read-only API for the server catalog and its media.
Not published yet
The URLs on this page are the planned production addresses. The public catalog is published after the storage bucket, the custom domain and the caching rules are configured. Until then these URLs do not resolve.
The API is a set of static files. There is no server to call, no key to request and no rate limit to negotiate: the catalog is a JSON document, and each media file is an image. Any CDN can serve them.
Endpoints
| Path | Returns | Cache |
|---|---|---|
https://media.owlclient.dev/v1/servers.json | The catalog for API version 1: every published server, the address index and the wildcard list. | 5 minutes, with stale-while-revalidate for an hour |
https://media.owlclient.dev/servers/<id>/<kind>.<hash>.<ext> | One image. The hash is part of the name. | one year, immutable |
The catalog is documented in Servers. Media is documented in Media. Compatibility rules are in Versioning. Cache behavior is in Caching.
Read the catalog
curl -sS -H "User-Agent: my-tool/1.0 (+https://example.net)" \
https://media.owlclient.dev/v1/servers.jsonSend a descriptive User-Agent. Requests with the default user agent of some runtimes, such as the JVM's Java/*, can be blocked by the CDN's bot protection.
Formats
- Responses are UTF-8 JSON, with
application/json; charset=utf-8. - Images are PNG or WebP, as listed in each media entry.
- Every JSON field that is not documented may be added in a later release. Ignore unknown fields.
What the API does not do
- It does not accept writes. Changes go through pull requests.
- It does not resolve SRV records, check that a server is online, or report player counts.
- It does not expose the metadata files themselves; the catalog is the published projection.