Health & Common Patterns

Health Check

Craft exposes a health check endpoint at two paths:

GET /health
GET /api/health

Response

{
  "status": "ok",
  "service": "craft-api"
}

The /health path is intended for internal health checks (Docker health probes, load balancers). The /api/health path is accessible through the Caddy reverse proxy alongside the rest of the API.

Common Patterns

The following conventions apply across all Craft API endpoints.

Base URL

All API endpoints are prefixed with /api/:

https://space.warehack.ing/api/satellites
https://space.warehack.ing/api/search?q=ISS
https://space.warehack.ing/api/passes?sat=25544

WebSocket endpoints use the /ws/ prefix:

wss://space.warehack.ing/ws/tracking/satellite/25544
wss://space.warehack.ing/ws/rotor/1

Response Format

All endpoints return JSON. List endpoints follow a consistent envelope pattern:

{
  "items": [...],
  "count": 42
}

The collection field name varies by resource (e.g. satellites, launches, predictions) but count is always present.

Pagination

Endpoints that return lists support limit and offset parameters:

Parameter	Type	Default	Description
`limit`	`int`	varies	Max results to return
`offset`	`int`	`0`	Number of results to skip

Error Responses

Errors follow standard HTTP status codes with a JSON detail message:

{
  "detail": "Satellite 99999 not found"
}

Status	Meaning
`400`	Invalid request (bad parameters, target below horizon)
`404`	Resource not found
`409`	Conflict (duplicate name, operation blocked by state)
`502`	Upstream service error (embedding service, rotctld)
`503`	Service unavailable (feature not configured)

Background Tasks

Several endpoints trigger background data refreshes. These always return immediately with a status message:

{
  "status": "refreshing",
  "message": "Description of what started"
}

Background refresh endpoints:

Endpoint	Refreshes
`POST /api/catalog/tle/update`	TLE data from CelesTrak
`POST /api/comets/refresh`	Comet data from MPC
`POST /api/launches/refresh`	Launch data from Launch Library 2
`POST /api/reentry/refresh`	Reentry predictions from Space-Track
`POST /api/weather/refresh`	Space weather from NOAA SWPC
`POST /api/atmosphere/refresh`	Local atmosphere from Open-Meteo
`POST /api/events/refresh`	Events (conjunctions, NEOs, crew)
`POST /api/sondes/refresh`	Radiosonde data from SondeHub
`POST /api/aircraft/refresh`	ADS-B data from OpenSky Network

CORS

The API allows all origins (*) for cross-origin requests. All HTTP methods and headers are permitted.

Timestamps

All timestamps are returned in ISO 8601 format with UTC timezone:

2026-02-14T22:30:00Z

Coordinate Systems

Azimuth: 0-360 degrees, measured clockwise from north
Elevation/Altitude: -90 to +90 degrees, measured from the horizon
Right Ascension: In hours (0-24) for position endpoints
Declination: In degrees (-90 to +90)
Latitude/Longitude: Decimal degrees (WGS84)