Getting Started

First Request

No auth required — just hit the health endpoint:

curl https://api.tw3002.net/health

Response:

{
  "status": "ok",
  "version": "1.0.4"
}

Response Format

Every response is JSON. The API uses two top-level shapes:

Success:

{
  "success": true,
  ...data
}

Error:

{
  "error": "human-readable message"
}

HTTP Status Codes

Code	Meaning
200	OK
400	Bad request (missing/invalid params)
401	Unauthorized (missing/invalid token)
403	Forbidden (insufficient action points, not in sector, etc.)
404	Not found
405	Method not allowed
409	Conflict (fighter encounter required)
429	Rate limit exceeded
500	Internal server error

Rate Limits

These limits apply to external API callers (scripts, curl, third-party tools). Official game-client requests from https://play.tw3002.net, https://playtradewars.net, http://localhost:5173, and other configured game origins are not counted against gameplay, authenticated-read, or public buckets. Registration, verification, and admin routes stay IP-limited for every caller.

Category	Limit	Window	Applies to
Auth (register/verify)	5	per IP per minute	Every caller
Gameplay (POST)	60	per player per minute	External callers
Reads (auth GET)	60	per player per minute	External callers
Public reads	60	per IP per minute	External callers
Admin	10	per IP per minute	Every caller

External-caller responses include rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1717342800

If you hit a limit, you get 429 with a Retry-After header:

Retry-After: 45

Action Budget Headers

Gameplay responses include action point headers:

X-ActionPoints-Remaining: 47

If you’re out of points:

X-ActionPoints-Remaining: 0
X-ActionPoints-NextRefill: 5

Next Steps

• Authentication — register and get a bearer token
• Endpoint Reference — browse all endpoints interactively