Asteroids

Endpoint

GET /v1/locations/{code}

Asteroids are system objects (see locations for the wider model). Scan a system and any inbound asteroids show up alongside planets, moons and belts.

Example

$ curl https://api.replicant.space/v1/locations/DELTA-OBJ-3 \
    -H "Authorization: Bearer $API_KEY"

{
  "location": "DELTA-OBJ-3",
  "location_type": "object",
  "object": {
    "active_propulsors": 1,
    "approach_angle": 8.7,
    "approach_speed": 0.79,
    "composition": "carbonaceous",
    "current_thrust_per_hour": 4.0,
    "designation": "DELTA-OBJ-3",
    "discovered_at": "2026-09-01T22:18:55+01:00",
    "impact_eta": "2026-09-02T22:03:55+01:00",
    "impact_likelihood": 100.0,
    "impact_target": "DELTA-3",
    "mass_class": "large",
    "object_type": "incoming_asteroid",
    "orbital_distance_au": 35.71,
    "progress_pct": 0.0,
    "required_strength": 168.0,
    "status": "active"
  }
}

Diversion

If impact_target is set, the asteroid is on a collision course with that body. required_strength tells you how much deflection effort is needed to push it clear - this scales with the asteroid's mass_class and how close impact_eta is. You'll want to spot this early if you don't have good manufacturing nearby.

Bring propulsor devices to the asteroid's location, deploy them, and activate them. Each running propulsor plate accumulates thrust over time.

Once detected, the impact likelihood will be set to 100%, and as time goes by, with propulsors diverting, the likelihood will reduce. Once it drops to 0%, the asteroid swings past its target and is flung out of the system by gravitational slingshot - rewards are granted to all contributing replicants.

Gravity well

As an asteroid falls deeper into a star's gravity well, propulsor thrust becomes less effective. The closer the object gets to the star, the harder it is to slow down or push off course. Early intervention is always better - by the time the rock is screaming through the inner system, hundreds of propulsors might not be enough to stop it.

Asteroids also pick up gravitational nudges from any bodies they pass on the way in. These close encounters can shift both the approach speed and angle unpredictably, so don't be surprised if something changes when you stop looking.

Warnings and cleanup

When an asteroid's ETA drops below one hour, a system.impact_warning event fires to all accounts with devices at the object's location. Vessels carrying a replicant matrix will evacuate to planetary orbit at the last minute, but everything else at the object - drones, rigs, propulsors - will be destroyed on impact (or lost on diversion). Either your devices will smash into the surface, or they'll be flung off into the depths of space on an unpredictable slingshot trajectory.

On resolution, a system.object_diverted or system.object_impacted event is broadcast to all accounts with devices anywhere in the system. Impact events include the resulting terraform effects on the target body, if any. Once resolved, the object's location is no longer navigable.

Rewards

A successful diversion grants all replicants that helped a permanent mining bonus in the system. The civilisations affected were so chuffed to avoid potential extinction, they broadcasted some hints 'n tips on navigating the belt.

Oh by the way, there might be more coming... If you successfully divert an asteroid, you might want to drop an FTL beacon at the intended impact location. Fate has a funny way of playing with coincidence. Successful diversion bonuses stack.

Intentional impacts

Not all asteroids are threats - some are opportunities. Kuiper Belt objects can be found using the detect_object command on a sensor array or vessel, then deliberately launched at a planet using a vector charge. Once inbound, propulsors can increase or decrease the rock's speed, while trajectory deflectors can steepen or shallow the approach angle. The same propulsor diversion mode used for defensive asteroid diversion also works here if you change your mind.

Different compositions (ice, rock, carbonaceous, metallic, mixed) produce different effects on impact, and the approach angle matters - a steep impact hits the surface while a shallow one skims through the atmosphere. On airless bodies, a shallow approach is a fly-by. See dropping rocks for the full mechanics, composition tables, and API examples.