Overview

The Nox API is a RESTful HTTP API that lets you interact with the Nox platform programmatically. All routes are prefixed with /api and return JSON. The documentation below is generated from the OpenAPI specification.

Base URL

Replace {server} with the hostname of the Nox instance you are targeting (e.g. nox.example.com).

https://{server}/api

The actual API root URL is advertised by the server through a well-known discovery mechanism. Clients should resolve it automatically rather than hardcoding the scheme or port.

Server discovery

Given a bare hostname (e.g. nox.example.com), clients attempt the following strategies in order, stopping at the first success:

_nox._tcp.example.com.  IN  SRV  10 100 443 nox.example.com.

_nox.example.com.  IN  TXT  "ng=https://nox.example.com/.well-known/nox"

{
  "links": [
    { "rel": "nox/1.0", "href": "https://nox.example.com/.well-known/nox" }
  ]
}

Authentication

Most endpoints require a Bearer token obtained from POST /api/auth/login or POST /api/auth/register.

Pass the token in the Authorization header of every authenticated request:

Authorization: Bearer <token>

Response envelope

Every response (except Fediverse and Storage endpoints) is wrapped in a consistent envelope:

{
  "data": { "id": "1@nox.example.com", "username": "alice" },
  "error": null,
  "time": 1700000000000,
  "request": "/api/users/me"
}

{
  "data": null,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user found with this identifier.",
    "status": 404
  },
  "time": 1700000000000,
  "request": "/api/users/1@nox.example.com"
}

Nox Identifiers

Resources are identified by a NoxIdentifier — a compact, URL-safe string that encodes a resource type, a numeric or named ID, optional query parameters, and an optional server address.

Full format

[<type>:]<id>[?<key>=<value>[&<key>=<value>...]][@<server>]

All parts except <id> are optional. When @<server> is omitted the identifier refers to a resource on the local server.

Type prefixes

Query parameters embedded in identifiers

Query parameters are appended after a ? and before the optional @<server> part. They allow passing context or options together with the identifier, without adding extra URL parameters.

World (w:) queries

Instance (i:) queries

Examples

1@nox.example.com                       # untyped resource #1 on remote server
u:1@nox.example.com                     # user #1 on remote server
u:alice                                 # user "alice" on the local server
w:42@nox.example.com                    # world #42 on remote server
w:42?v=3@nox.example.com               # world #42, asset version 3
i:lobby                                 # instance with shortname "lobby" on local server
i:7?w=NDJAbm94LmV4YW1wbGUuY29t         # instance #7 joining world encoded in base64
i:7?w=NDJAbm94LmV4YW1wbGUuY29t&p=c2VjcmV0  # same, with password

Pagination

List endpoints return a paginated envelope inside data:

{
  "data": {
    "total": 120,
    "limit": 20,
    "offset": 0,
    "items": [ "..." ]
  }
}

Control pagination with the limit and offset query parameters.

Asset upload flow

Uploading binary assets (avatars, worlds) is a three-step process:

PUT /api/assets

POST /api/assets/{id}/file
Content-Type: multipart/form-data

GET /api/assets/{id}/status

API groups

Fediverse

The Fediverse endpoints (/.well-known/*, /nodeinfo/*) follow their respective protocol standards and do not use the response envelope described above. They return plain JSON or XML as required by the protocol.

Error codes

Common HTTP status codes returned by the API: