Web API Live State

These endpoints read the running session: what state the server is in, the mission being played, and the ships in it. All of them are GET and need no token. Each answers with the world as it is at the moment the request is served, and a session with nothing loaded answers with empty results. For the basics — the port, paths, the token — see Web API.

The endpoints

status

GET /api/status
{"State":"Playing","Mode":"Mission","Mission":"Fighter Escort","Players":"Horizons"}

This is the cheapest call there is. Poll it to know when a game starts and stops, and ask for more only while State is Playing.

mission

Timer, ElapsedTime and TimeRemaining are sent as strings, so convert them before doing arithmetic.

vessels

The list holds every vessel, missile and astral object in the session, all maps included. Vessels carry the full set of fields below. Missiles and astral objects (planets, nebulae and the like) carry shorter sets of their own: every entry has ID, BaseType, Name and Position, and a missile's or a planet's Integrity is a fraction from 0 to 1 rather than hull points. Asking for one id returns only vessels.

Position is not in the engine's axis order. Position (and SeekPosition) put height last: X and Y are the horizontal plane and Z is up. A tool that reads Y as height is reading range. The coarse positions are not swapped.

Positions are in the units of the place the object is in: meters near a planet, so 1,000 to a kilometer, and larger units at the scale of a star system or the galaxy map.

vessel-contacts

GET /api/vessel-contacts/12

The contact list of vessel 12: everything its sensors currently show, nearest first, in the same form its crew's consoles receive. Each contact has ID, Name, Class, Faction, BaseType, Classification, Position, Orientation, Velocity, Integrity, Shields, Identified, Scanned, IFF, Tags and a few more. A contact the ship has not identified is masked the way the crew sees it, without its real name or faction.

The answer is [] while the ship is in FTL, and {} for an id that is not a vessel.

For a Game Master this is a quick way to answer "why can't they see it?": compare /api/vessels, which is everything, with the contacts of the ship that should see it.

player-vessels

One entry per player ship, with the crew-side state the consoles use:

metrics

What the last update of the simulation cost, in milliseconds: tick_ms for the whole of it, then players_ms, npcs_ms, projectiles_ms, events_ms and mission_ms. A collision block breaks the collision pass down, and the totals of vessels, astral objects, projectiles and missiles say how much there is in play.

Use it when a session feels slow. Sample it a few times rather than once: one update is noise. Within the collision block, faults counts every collision check that failed since the server started; anything but a steady number is worth a look in debug.log.

users

The registry of players the server remembers between sessions. /api/users answers { "Users": [...] }, newest seen first, with each account's AccountID, CallSign, name, rank, faction, Blocked and Trusted flags, when it was first and last seen, how many devices and missions it has, and whether it is online. /api/users/{account} adds the account's devices and its seat in each mission. An operator can correct or remove an entry; see Web API Writes.

A worked example

A small "who is winning" board for a competitive mission, polling once a second:

import json, time, urllib.request

def get(path):
    with urllib.request.urlopen("http://localhost:1864/api/" + path) as reply:
        body = reply.read().decode("utf-8")
        return json.loads(body) if body.strip() else None

while True:
    status = get("status")
    if status and status["State"] == "Playing":
        ships = [json.loads(p["VesselInfo"]) for p in get("player-vessels") or []]
        for ship in sorted(ships, key=lambda s: s.get("Score", 0), reverse=True):
            print(f'{ship.get("Name", "?"):20} {ship.get("Score", 0):8} {ship.get("Lives", "")}')
        print()
    time.sleep(1)