Bearer token
Authorization: Bearer <token>
Accept: application/jsonUse from a trusted backend. Store the value as a secret environment variable such as NEXUS_TOKEN.
UNOFFICIAL · SOURCE-GROUNDED · PRACTICAL
The Nexus API,
mapped for builders.
A readable field manual for understanding Nexus Legacy data: authentication, endpoint families, payloads, response shapes, and the edge cases found while building real tools.
—documented routes
12endpoint families
2known universes
01 / ORIENTATION
Know what you are talking to
Nexus exposes a JSON HTTP API beneath each game universe. The tools inspected for this guide use the production universe at https://nf.nexuslegacy.space/api and the beta universe at https://beta.nexuslegacy.space/api.
This is a community-maintained description of routes observed in working local projects—not an official contract. Fields can differ between endpoint revisions, and some responses are either a direct object or wrapped in { "data": ... }. Defensive examples account for both.
Keep credentials server-side.Never commit a token, paste it into client-side JavaScript, include it in screenshots, or expose it through a public Coolify environment variable.
02 / FIRST CONTACT
Your first request
Ask Nexus who the current credential belongs to. This is the fastest authentication and universe check.
GET /api/auth/me
const origin = "https://nf.nexuslegacy.space";
const response = await fetch(`${origin}/api/auth/me`, {
headers: {
Accept: "application/json",
Authorization: `Bearer ${process.env.NEXUS_TOKEN}`
}
});
if (!response.ok) {
throw new Error(`Nexus returned ${response.status}`);
}
const payload = await response.json();
const me = payload.data ?? payload;
console.log(me.username, me.planets);1Choose a universe
A credential belongs to one universe. Production and beta sessions are not interchangeable.
2Add
/apiEvery game route in this manual is relative to the universe API root.
3Unwrap carefully
Use payload.data ?? payload when a client needs to tolerate both shapes.
03 / ACCESS
Authentication
Observed clients use bearer credentials, session cookies, or both. A backend bearer token is the cleanest tool boundary.
Session cookie
Cookie: <browser session cookie>
Accept: application/jsonSome same-origin browser tools rely on the signed-in session. Cookies are sensitive credentials and can be universe-specific.
04 / REQUEST MODEL
Conventions that repeat
{universe}/apiPaths shown below begin after /api.
application/jsonSend Content-Type for JSON bodies; ask for JSON with Accept.
{ shipDefId, quantity }Fleet actions use arrays of ship-definition IDs and counts.
ISO 8601Mission and report times are generally timestamp strings; parse them explicitly.
limit / offset / pageRankings and logs use limit plus offset; market orders use pages.
Idempotency-KeyObserved server tools add a unique key to commands where supported.
05 / ROUTE CATALOGUE
Endpoint index
Search by route, purpose, field, or family. Select a row to see parameters and observed response details.
06 / DATA MODEL
Common response shapes
Names below reflect the compatibility logic in existing tools. Prefer explicit normalizers at your application boundary.
System
- id / systemId
- numeric identifier
- name / systemName
- display label
- x, y / systemX, systemY
- galaxy coordinates
- visibility
- fog, partial, full, etc.
- securityZone
- open, sentinel, alliance, dead
Planet
- id / planetId
- numeric identifier
- systemId
- parent system
- resources
- amount and capacity by key
- isHomeworld
- homeworld marker
- buildings / queues
- development state
Mission
- id / missionId
- mission identifier
- missionType / type
- action kind
- status / state
- mission phase
- sourcePlanetId
- origin planet
- target*Id
- planet, system, field or debris
- ships / fleetComposition
- ship stacks
Ship stack
- shipDefId / id
- ship definition
- quantity / totalQuantity
- owned count
- readyQuantity
- currently available
- damagedQuantity
- repairable count
- cargoCapacity
- per-ship capacity
Field
- id / fieldId
- resource field ID
- fieldType
- gas or resource class
- remaining / capacity
- resource quantities
- richness
- yield factor
- systemId
- location
List envelope
- items / results
- generic collections
- missions / systems / reports
- named collections
- pagination.hasMore
- more ranking rows
- data
- optional outer wrapper
07 / FAILURE MODES
Errors & rate limits
Always read the status, then parse the body as JSON with a text fallback. Do not assume every failure has the same envelope.
400Invalid requestMissing fields, invalid quantities, or an impossible command.401Authentication failedExpired or missing credentials.403Not permittedThe account cannot view or perform the operation.404Not foundWrong route or an ID unavailable to the current player.409State conflictIncludes wrong-universe sessions and human-verification requirements observed by local clients.429Rate limitedInspect RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy when present.Defensive error parsing
const text = await response.text();
let body;
try { body = text ? JSON.parse(text) : null; }
catch { body = { raw: text.slice(0, 500) }; }
if (!response.ok) {
const detail = body?.error ?? body?.message ?? response.statusText;
throw new Error(`${response.status}: ${detail}`);
}08 / VOCABULARY
Identifiers are not interchangeable
Arm
→armIdSector
→sectorIdSystem
→systemIdPlanet
planetIdResource fields, debris, reports, stations, market hubs, wormholes, missions, buildings, and ship definitions each have their own ID spaces. Preserve IDs as returned instead of deriving them from names. Convert to numbers only where the API demonstrably expects numbers.
09 / SMALL TOOL
A one-shot galaxy scanner
This intentionally small example performs a single read when you run it. It lists systems whose visibility suggests they have not yet been fully scouted.
- Save the file as
scan.mjs. - Set
NEXUS_TOKENin your terminal environment. - Run it once with
node scan.mjs.
Why this is safe to learn fromIt is read-only, does not dispatch anything, does not persist credentials, and has no timer or repeated execution.
scan.mjs
const API = "https://nf.nexuslegacy.space/api";
async function nexusGet(path) {
const response = await fetch(API + path, {
headers: {
Accept: "application/json",
Authorization: `Bearer ${process.env.NEXUS_TOKEN}`
}
});
const text = await response.text();
const payload = text ? JSON.parse(text) : null;
if (!response.ok) throw new Error(`${response.status}: ${text}`);
return payload?.data ?? payload;
}
const map = await nexusGet("/galaxy/map");
const systems = Array.isArray(map) ? map : (map.systems ?? map.items ?? []);
const unknown = systems.filter(system => {
const visibility = String(
system.visibilityState ?? system.visibility ?? ""
).toLowerCase();
return ["fog", "outline", "partial", "unknown", "unscouted"]
.includes(visibility);
});
console.table(unknown.slice(0, 25).map(system => ({
id: system.id ?? system.systemId,
name: system.name ?? system.systemName,
x: system.x ?? system.systemX,
y: system.y ?? system.systemY,
visibility: system.visibilityState ?? system.visibility
})));10 / SHIPPING
Coolify deployment
This manual is a static Nginx container. It needs no Nexus credential and exposes no backend API.
01
Create a Coolify resource from this Git repository.
02
Select Docker Compose and use compose.yaml.
03
Attach your domain to container port 80, then deploy.
04
Verify /health returns healthy.
11 / PROVENANCE
How to read this reference
Routes and shapes were derived from the working projects in E:\Development\NEWnexus, including the central database collectors, panel clients, scouting utilities, mining reports, and browser-side tools. “Observed” means a route is called by local source. “Shape” notes describe fields consumed by those clients, not a guaranteed exhaustive schema.
Local application endpoints such as panel dashboards and the separate central-database /api/v1 interface are intentionally excluded from the Nexus game API catalogue.