Replicant Space

https://replicant.space/docs
Admin
Replicant Space is an API-first space exploration game where players build a manufacturing empire in...
Tokens:108,813
Snippets:886
Trust Score:5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Belt Resources

Source: https://replicant.space/docs/concepts/resources

Example GET request to retrieve information about resources available in a specific asteroid belt.

```shell
response GET /v1/locations/TARAZEDAR-BELT-1 200 OK 
```
{
  "location": "TARAZEDAR-BELT-1",
  "location_type": "belt",
  "belt": {
    "density": "sparse",
    "designation": "TARAZEDAR-BELT-1",
    "inner_radius_au": 0.6,
    "outer_radius_au": 0.9,
    "resources": {
      "carbon": "rich",
      "conductive": "scarce",
      "rares": "low",
      "silicates": "low",
      "structural": "moderate",
      "volatiles": "high"
    }
  },
  "resource_sites": [
    {
      "designation": "TARAZEDAR-BELT-1-SITE-0",
      "name": "TARAZEDAR-BELT-1 Primary Site",
      "resources_remaining_pct": {
        "carbon": 100,
        "conductive": 100,
        "rares": 100,
        "silicates": 100,
        "structural": 100,
        "volatiles": 100
      },
      "site_index": 0
    }
  ]
}
```
```

--------------------------------

### Start Mining Device Command

Source: https://replicant.space/docs/api/devices/command

Tell a mining drone to start mining for a specific resource.

```APIDOC
## _start_mining_

### Description
Tell a mining drone to start mining for a specific resource.

### Method
POST

### Endpoint
/devices/command

### Request Body
```json
{
  "command": "start_mining",
  "resource_type": "<resource_type_code>"
}
```
```

--------------------------------

### Blueprint Response Example

Source: https://replicant.space/docs/concepts/blueprints

This is an example of the JSON response when listing blueprints. It details device type, descriptions, directives, features, print time, resource costs, and capacity.

```json
{
  "blueprints": [
    {
      "device_type": "maintenance_drone",
      "short_description": "Repairs your devices once they lose enough operational capacity.",
      "description": "This is a solid metallic box with an extendable pair of sensor lenses at the top and an articulated arm on either side. When it reaches a damaged device, the drone evaluates the repair, powers the target down, and opens its front panel to reveal tools, spare parts and interesting bits of salvage. Its patrol directive works by pinging all devices in the system, then cruising to anything that requires maintenance.",
      "directives": [
        "patrol"
      ],
      "features": [
        "cruise",
        "repair",
        "ami",
        "stow"
      ],
      "print_time": 270,
      "resources": {
        "carbon": 35,
        "conductive": 80,
        "rares": 20,
        "silicates": 40,
        "structural": 150,
        "volatiles": 10
      },
      "attach_capacity": 0,
      "cargo_capacity": 0,
      "stow_capacity": 0
    },
    ...
  ]
}
```

--------------------------------

### Example Inventory Response

Source: https://replicant.space/docs/quickstart

This is an example of the JSON response you will receive when checking your inventory at a location.

```json
{
  "location": "SOL-BELT-1",
  "location_type": "belt",
  "inventory": [
    { "resource_type": "carbon",     "quantity": 25 },
    { "resource_type": "silicates",  "quantity": 28 },
    { "resource_type": "structural", "quantity": 123 }
  ]
}
```

--------------------------------

### _print.started

Source: https://replicant.space/docs/api/events/catalogue

A device print job was started by a replicant, vessel, or autofactory.

```APIDOC
## _print.started

### Description
A device print job was started by a replicant, vessel, or autofactory.

### Response Example
```json
{
  "device_type": "mining_drone",
  "print_mode": "vessel"    // "vessel", or "autofactory"
}
```
```

--------------------------------

### Launch Response

Source: https://replicant.space/docs/ami

Example response when a fleet is successfully launched. It details which devices were deployed.

```json
{
  "device_code": "175B5AD3",
  "assigned_devices": {
    "already_deployed": [],
    "deployed": [
      "E811348D",
      "6414BB30",
      "ADA90515",
      "494140A7",
      "6DABF041"
    ],
    "failed": [],
    "skipped": []
  },
  "status": "launched"
}
```

--------------------------------

### Planet or Moon Location Response Example

Source: https://replicant.space/docs/api/locations

Example JSON response for a planet or moon location. Includes system, parent, atmosphere, and resource site information if surveyed. Also shows device and resource counts.

```json
{
  "code": "TARAZEDAR-2-3",
  "location_type": "moon",
  "system": "TARAZEDAR",
  "parent": "TARAZEDAR-2",
  "surveyed": true,
  "atmosphere": "thin",
  "resource_sites": [
    { "resource": "silicates", "yield": 0.62 },
    { "resource": "rare_earth", "yield": 0.08 }
  ],
  "your_devices": 3,
  "your_resources": 412
}
```

--------------------------------

### Start a Print Job

Source: https://replicant.space/docs/api/replicants/print

Initiates a new print job for a specified device type. Ensure the device type is available in your blueprints.

```bash
$ curl -X POST https://api.replicant.space/v1/replicants/57F0F6C8/print \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"device_type": "mining_drone"}'
```

```json
{
  "status": "enqueued"
}
```

--------------------------------

### Example Event Response

Source: https://replicant.space/docs/concepts/civilisations

This is an example of a successful response when querying for active events. It includes details about the event's location, designation, broadcast message, title, description, category, status, criteria, rewards, and discovery time.

```json
{
  "events": [
    {
      "location": "QIGONOG-3",
      "designation": "QIGONOG-3-EVT-001",
      "broadcast_message": "...our communication networks are degrading...",
      "title": "Electronics Shortage"
      "description": "A civilisation's conductive material reserves are exhausted...",
      "category": "resource_trade",
      "status": "active",
      "criteria": {
        "devices": [],
        "resources": {
          "conductive": 250,
          "silicates": 100
        }
      },
      "rewards": {
        "civilisation_points": 1,
        "completion_achievement": "electronics_shortage_completed",
        "resources": {
          "rares": 350
        },
        "xp": 500
      },
      "discovered_at": "2026-05-23T21:17:25+01:00",
      "tier": 1
    }
  ]
}
```

--------------------------------

### Example Response for Replicant Cooperation Update

Source: https://replicant.space/docs/api/accounts

This is an example of a successful response (200 OK) after updating the replicant cooperation setting. It confirms the change and returns the updated account details.

```json
{
  "replicant_cooperation": "shared",
  "name": "Bob",
  "email": "bob@example.com",
  ...
}
```

--------------------------------

### Belt Location Response Example

Source: https://replicant.space/docs/api/locations

This is an example JSON response for a belt location query. It details the belt's properties, resource distribution, and any associated devices or inventory.

```json
{
  "location_type": "belt",
  "location": "TARAZEDAR-BELT-1",
  "belt": {
    "density": "sparse",
    "designation": "TARAZEDAR-BELT-1",
    "inner_radius_au": 0.6,
    "outer_radius_au": 0.9,
    "resources": {
      "carbon": "rich",
      "conductive": "scarce",
      "rares": "low",
      "silicates": "low",
      "structural": "moderate",
      "volatiles": "high"
    }
  },
  "devices": [],
  "inventory": [],
  "resource_sites": []
}
```

--------------------------------

### Launch Fleet

Source: https://replicant.space/docs/ami

Deploys the controller's fleet and starts executing the currently set directive.

```APIDOC
## POST /v1/devices/{code}

### Description
Launch the fleet and start executing the current directive.

### Method
POST

### Endpoint
/v1/devices/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - The unique identifier for the AMI controller.

#### Request Body
- **command** (string) - Required - Must be "launch".

### Request Example
```json
{
  "command": "launch"
}
```

### Response
#### Success Response (200)
- **device_code** (string) - The code of the controller.
- **assigned_devices** (object) - Details about the deployed devices.
  - **already_deployed** (array of strings) - Devices that were already deployed.
  - **deployed** (array of strings) - Devices that were successfully deployed in this operation.
  - **failed** (array of strings) - Devices that failed to deploy.
  - **skipped** (array of strings) - Devices that were skipped.
- **status** (string) - The status of the operation, e.g., "launched".

#### Response Example
```json
{
  "device_code": "175B5AD3",
  "assigned_devices": {
    "already_deployed": [],
    "deployed": [
      "E811348D",
      "6414BB30",
      "ADA90515",
      "494140A7",
      "6DABF041"
    ],
    "failed": [],
    "skipped": []
  },
  "status": "launched"
}
```
```

--------------------------------

### Start Mining a Resource

Source: https://replicant.space/docs/drones/mining

Initiates mining for a specified resource type at the drone's current location. Ensure the drone is already at the resource site.

```bash
$ curl -X POST https://api.replicant.space/v1/devices/2AC61214 \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command": "start_mining", "resource_type": "carbon"}'
```

--------------------------------

### Command Details

Source: https://replicant.space/docs/api/devices/command

Detailed information about each command, including its purpose and usage examples.

```APIDOC
## Command Details

Command| Details  
---|---
_activate_ | Activate a deployed device. Most commonly for activating FTL relays, but also for turning on propulsors when diverting.  
_adopt_ |  Instruct an AMI controller to adopt another device.  
`{command: adopt, targets: [ ... ]}`  
_attach_ |  Instruct a device to connect to another device. Commonly used for moving devices between systems with surge plates.  
`{command: attach, targets: [ ... ]}`  
_change_owner_ |  Reassign a device from one replicant to another (must both be under the same account).  
`{command: change_owner, target: <code>}`  
_clear_directive_ | Reset an AMI controller's directive. This will stop the controller from evaluating and issuing new commands to the devices it controls.  
_compact_ | Start the process of collapsing a large modular device into a transportable state so it can be attached to a surge carrier. The device is offline until unfurled. The cruise drive will still work for in-system travel while compacted.  
_clear_queue_ | Remove any items from a 3D printer's queue. Primarily used on autofactories, this can also be issued to any device with the print feature. Useful if you try to print something yourself, then realise you're short of resources and change your mind.  
_collect_resources_ |  Instruct a transport device to take resources from the current location's inventory.  
`{command: collect_resources, resources: { silicates: 50, rares: 30, ... }}`  
_deactivate_ | Stop a device from printing, mining, scanning, travelling, etc. Most async commands can be stopped with this.  
_decommission_ | Send a device to the nearest autofactory in the current system, where it will be converted into resources. You'll learn the blueprint for the device, if you didn't know it already. The trading system allows you to purchase devices from other players and NPCs.  
_deploy_ | Deploy a stowed device to the current location.  
_deposit_resources_ |  Instruct a device with cargo to unload at its location. Skip the resources param to empty everything.  
`{command: deposit_resources, resources: { silicates: 50, rares: 30, ... }}`  
_dequeue_print_ |  Remove a specific item from a device's print queue. Supply the zero-indexed position in the list.  
`{command: dequeue_print, index: 2}`  
_detach_ |  Disconnect one device from another. Skip the devices param to detach everything connected to it.  
`{command: detach, targets: [ ... ]}`  
_enqueue_print_ |  Add an item to the print queue, with optional auto-adoption controller code and on-complete command.  
`{command: enqueue_print, controller: <code>, oncomplete: <command>}`  
_launch_ | Deploy an AMI controller to your current location. This will also activate the AMI directive and deploy all controlled devices. Fly to a belt and launch your mining swarm with one command.  
_prospect_ |  Discover new stars beyond the galaxy catalogue. Deploy a galactic observatory at the fringe and prospect outward, or specify a direction to search in any direction where stars look sparse.  
`{command: prospect, direction: [x, y, z]}`  
_recall_ | Instruct a device to come home and stow itself. If you fly away while it's returning to you, it will continue to chase you around the system like a wasp in summer.  
_release_ |  Tell an AMI controller to stop controlling one or more devices. Opposite of the adopt command.  
`{command: release, targets: [ ... ]}`  
_rename_ |  Once you're in charge of a system with your own system_hub running, you can ask it to update the star catalogue to change the names of things. Valid target designations are stars, planets and moons.  
`{command: rename, designation: SOL-3, new_name: Earth}`  
_repair_ |  Ask a maintenance drone to repair a specific device, when it's not running a directive.  
`{command: repair, target: <code>}`  
_replicate_ |  Once you have an empty replicant matrix at your current location, issue this command to your own internal matrix, and it will initiate a tight-beam replication process. Similar to a teleport, except we don't destroy the original, avoiding the existential crisis.  
`{command: replicate, target: <code>}`  
_retarget_ |  Instruct a mining drone to switch focus to a new resource, without stopping the current operation.  
`{command: retarget, resource_type: <code>}`  
```

--------------------------------

### Unfurl Device Command

Source: https://replicant.space/docs/api/devices/command

Start the process of reassembling a previously compacted modular device.

```APIDOC
## _unfurl_

### Description
Start the process of reassembling a previously compacted modular device.

### Method
POST

### Endpoint
/devices/command

### Request Body
```json
{
  "command": "unfurl"
}
```
```

--------------------------------

### Start Mining Resources

Source: https://replicant.space/docs/quickstart

Initiates resource mining for a deployed drone. You can specify the resource type to mine. This command should be repeated for each drone.

```APIDOC
## POST /v1/devices/{code}

### Description
Starts mining a specified resource type for a drone.

### Method
POST

### Endpoint
/v1/devices/{code}

### Parameters
#### Path Parameters
- **code** (string) - Required - The unique identifier of the device (drone).

#### Request Body
- **command** (string) - Required - The command to execute, should be "start_mining".
- **resource_type** (string) - Required - The type of resource to mine (e.g., "carbon", "silicates").

### Request Example
```json
{
  "command": "start_mining",
  "resource_type": "carbon"
}
```

### Response
#### Success Response (200 OK)
Indicates the command was successfully received and processed.
```

--------------------------------

### Start Mining Resource

Source: https://replicant.space/docs/api/devices/command

Instruct a mining drone to begin mining a specific resource. The resource type must be specified.

```json
{command: start_mining, resource_type: <code>}
```

--------------------------------

### List Replicant Devices Response

Source: https://replicant.space/docs/api/replicants/devices

This is an example JSON response when listing a replicant's devices. It includes a list of devices with their details and a `next_cursor` for pagination.

```json
{
  "devices": [
    {
      "device_code": "2AC61214",
      "device_type": "mining_drone",
      "location": "SOL-BELT-1",
      "status": "mining",
      "operational_capacity": 0.92
    },
    {
      "device_code": "7FE981A0",
      "device_type": "mining_drone",
      "location": "SOL-BELT-1",
      "status": "mining (structural)",
      "operational_capacity": 0.99
    }
  ],
  "next_cursor": 4821
}
```

--------------------------------

### Example Trader Response

Source: https://replicant.space/docs/trading/directory

This JSON object represents a successful response when listing traders. It includes details about each shop, such as its name, owner, description, and stock.

```json
{
  "traders": [
    {
      "controller_code": "C25C44CE",
      "description": "Bring some compute cores to the 'works if you want my new bots.",
      "is_local": false,
      "location": null,
      "owner_name": "Bill",
      "owner_replicant_code": "67D2FE23",
      "shop_name": "The Skunkworks",
      "star": null,
      "total_stock": 6,
      "trade_count": 2
    },
    {
      "controller_code": "F61FA449",
      "description": "We need volatiles, happy to trade.",
      "is_local": false,
      "location": "SOL-3-1",
      "owner_name": "Riker",
      "owner_replicant_code": "05AB5A1E",
      "shop_name": "Riker's Lunar Supplies",
      "star": "SOL",
      "total_stock": 10,
      "trade_count": 1
    }
  ]
}
```

--------------------------------

### Scan System - cURL Example

Source: https://replicant.space/docs/api/replicants/scan

Use this cURL command to initiate a scan of the current system. Replace `{code}` with your replicant's code and `$API_KEY` with your actual API key.

```bash
$ curl -X POST https://api.replicant.space/v1/replicants/8AFE4482/scan \
    -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### Teleport Replicant Response

Source: https://replicant.space/docs/api/replicants/teleport

This is an example of a successful response when initiating a teleportation. It confirms the teleportation is in progress and provides details about the transfer, including start and completion times.

```json
{
  "status": "teleporting",
  "source_star": "SOL",
  "destination_star": "POLIBUS",
  "started_at": "2026-05-10T14:30:00+01:00",
  "completes_at": "2026-05-10T14:30:30+01:00",
  "offline_seconds": 30,
  "target_matrix_code": "0799A49D"
}
```

--------------------------------

### Scan Starting System

Source: https://replicant.space/docs/quickstart

Execute this POST request to scan your current system. Replace `{code}` with your replicant's code to discover planets and asteroid belts.

```shell
# 2. scan your starting system to discover what's around you
$ curl -X POST https://api.replicant.space/v1/replicants/57F0F6C8/scan \
    -H "Authorization: Bearer $API_KEY" \

```

--------------------------------

### GET /v1/devices/{relay_code}/messages

Source: https://replicant.space/docs/concepts/bobnet

Retrieves a rolling log of messages from an active FTL relay or System Hub. You can specify parameters to control the message retrieval, such as starting position, number of messages, and whether to include NPC chatter.

```APIDOC
## GET /v1/devices/{relay_code}/messages

### Description
Retrieves a rolling log of messages from an active FTL relay or System Hub. You can specify parameters to control the message retrieval, such as starting position, number of messages, and whether to include NPC chatter.

### Method
GET

### Endpoint
/v1/devices/{relay_code}/messages

### Parameters
#### Path Parameters
- **relay_code** (string) - Required - The unique identifier for the FTL relay or System Hub.

#### Query Parameters
- **cursor** (integer) - Optional - Position in the list to start from, default null.
- **limit** (integer) - Optional - Number of messages to show, default 20.
- **latest** (boolean) - Optional - Show latest messages. Default `false`. Incompatible with `cursor`.
- **include_npcs** (boolean) - Optional - Include NPC chatter. Default `true`.

### Request Example
```bash
curl https://api.replicant.space/v1/devices/SR9023C1/messages?latest=true&limit=3&include_npcs=true \
    -H "Authorization: Bearer $API_KEY"
```

### Response
#### Success Response (200)
- **messages** (array) - A list of message objects.
  - **id** (integer) - The unique identifier for the message.
  - **channel** (string) - The chat channel.
  - **current_star** (string) - The current star system associated with the message.
  - **message** (string) - The content of the message.
  - **replicant_code** (string) - The unique identifier for the replicant who sent the message.
  - **replicant_name** (string) - The name of the replicant who sent the message.
  - **time** (string) - The timestamp when the message was sent.
- **next_cursor** (null) - Indicates the next cursor for pagination, null if at the end.
- **total** (integer) - The total number of messages available.
- **total_messages** (integer) - The total number of messages retrieved.

#### Response Example
```json
{
  "messages": [
    {
      "id": 10418,
      "channel": "#general",
      "current_star": "HATTIPI",
      "message": "No, I'm not a teapot",
      "replicant_code": "77F75255",
      "replicant_name": "Bob",
      "time": "2026-05-27T07:49:30+01:00"
    },
    {
      "id": 10417,
      "channel": "#general",
      "current_star": "MUROPE",
      "message": "How about a matcha?",
      "replicant_code": "0B6A463F",
      "replicant_name": "Mercutio",
      "time": "2026-05-27T07:49:29+01:00"
    },
    {
      "id": 10416,
      "channel": "#general",
      "current_star": "MUROPE",
      "message": "Coffee?",
      "replicant_code": "0B6A463F",
      "replicant_name": "Mercutio",
      "time": "2026-05-27T07:49:27+01:00"
    }
  ],
  "next_cursor": null,
  "total": 263,
  "total_messages": 263
}
```
```

--------------------------------

### Set Shop Storefront Configuration

Source: https://replicant.space/docs/trading/configuration

Configure the name, description, and announcement for your shop using the `set_directive` command with the `trade` directive. The description and announcement fields are optional.

```shell
$ curl -X POST https://api.replicant.space/v1/devices/TC4488AA \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "command": "set_directive",
      "directive": "trade",
      "configuration": {
        "name": "Bob\'s Bits and Bobs",
        "description": "A longer description for your shop!",
        "announcement": "Head to SOL-3-1 for mining equipment!"
      }
    }'
```

--------------------------------

### Start Mining Carbon with a Drone

Source: https://replicant.space/docs/quickstart

Use this command to instruct a deployed drone to begin mining a specific resource. Repeat this command for each drone you wish to deploy for mining operations.

```bash
# 5. start mining carbon (repeat for each drone)
$ curl -X POST https://api.replicant.space/v1/devices/A1B2C3D4 \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command": "start_mining", "resource_type": "carbon"}'
```

--------------------------------

### Simulation Started Event Payload

Source: https://replicant.space/docs/api/events/catalogue

This event signifies the initiation of a simulation scenario. It includes the simulation ID, scenario code, and the starting star system.

```json
{
  "simulation_id": 17,
  "scenario_code": "mining_rush",
  "starting_star": "VIRTSOL"
}
```

--------------------------------

### Event: Device Print Started

Source: https://replicant.space/docs/api/events/catalogue

Payload for when a device print job is started by a replicant, vessel, or autofactory. Specifies the device type and print mode.

```json
{
  "device_type": "mining_drone",
  "print_mode": "vessel"    // "vessel", or "autofactory"
}
```

--------------------------------

### Retrieve Device Details

Source: https://replicant.space/docs/api/devices/retrieve

Use this command to fetch all details for a specific device. Ensure you have your API key set as an environment variable.

```bash
$ curl https://api.replicant.space/v1/devices/B58FCC78 \
    -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### Webhook Payload Example

Source: https://replicant.space/docs/api/accounts/webhook

An example of an incoming webhook payload, including the signature header and the JSON body. Note that the signature is computed over the raw request bytes.

```json
# every event delivery is signed
X-Replicant-Space-Signature: a5f7e3b9c1d8f2a4e6b0c3d5f7a9b1c2e4d6f8a0b2c4d6e8f0a2c4e6d8b0f2a4

{
  "type": "event",
  "event_type": "device_cruise_arrived",
  "device_code": "F54FA154",
  "device_type": "heaven_vessel",
  "replicant_code": "57F0F6C8",
  "payload": {
    "location": "SOL-5-L5",
    "from_location": "PORRAMA-KUIPER"
  },
  "timestamp": "2026-05-10T08:55:27+01:00"
}
```

--------------------------------

### Entering a simulation

Source: https://replicant.space/docs/simulations/running

Initiate a simulation by sending a POST request with the scenario and replicant code to the simulation endpoint. The response includes details about the simulation and its initial state.

```APIDOC
## POST /v1/devices/{interface_code}/simulate

### Description
Starts a new simulation by providing the scenario and replicant code.

### Method
POST

### Endpoint
/v1/devices/{interface_code}/simulate

### Parameters
#### Path Parameters
- **interface_code** (string) - Required - The unique code of the device interface to use for the simulation.

#### Request Body
- **scenario** (string) - Required - The code of the scenario to run.
- **replicant_code** (string) - Required - The code of the replicant to use in the simulation.

### Request Example
```json
{
  "scenario": "mining_rush",
  "replicant_code": "7A303E2A"
}
```

### Response
#### Success Response (200 OK)
- **simulation_id** (integer) - The unique identifier for the simulation.
- **scenario_code** (string) - The code of the scenario that was run.
- **scenario_name** (string) - The human-readable name of the scenario.
- **starting_star** (string) - The name of the star region where the simulation starts.
- **starting_location** (string) - The specific location within the starting star region.
- **seed** (integer) - The seed value used for the simulation's random generation.
- **devices** (array) - A list of devices included in the simulation loadout.
  - **device_code** (string) - The code of the device.
  - **device_type** (string) - The type of the device.
- **timeout_hours** (integer) - The duration in hours before the simulation times out.

### Response Example
```json
{
  "simulation_id": 42,
  "scenario_code": "mining_rush",
  "scenario_name": "Mining Rush",
  "starting_star": "VIRTUHOMAM",
  "starting_location": "VIRTUHOMAM-3-L4",
  "seed": 2043,
  "devices": [
    { "device_code": "SIM8F2A1", "device_type": "heaven_vessel" },
    { "device_code": "SIM3B7C2", "device_type": "mining_drone" },
    { "device_code": "SIM3B7C3", "device_type": "mining_drone" },
    { "device_code": "SIM3B7C4", "device_type": "mining_drone" },
    { "device_code": "SIM9D4E5", "device_type": "survey_drone" }
  ],
  "timeout_hours": 24
}
```
```

--------------------------------

### Set Welcome Message for System Hub

Source: https://replicant.space/docs/system-hubs

Use this command to set a custom welcome message for visitors to your system. The message can be up to 500 characters. The hub must be active for the message to be set and delivered.

```bash
$ curl -X POST https://api.replicant.space/v1/devices/SH8C2A1F \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "command": "set_welcome_message",
      "message": "Welcome to PHARM. Trading outposts on the third planet are fully stocked!."
    }'
```

--------------------------------

### Locations API Response Example

Source: https://replicant.space/docs/api/locations/overview

This is an example of the JSON response structure when successfully retrieving locations. It shows the count of devices, replicants, resource sites, and resources for each location.

```json
{
  "locations": {
    "SOL-2": {
      "devices": 1,
      "replicants": 1,
      "resource_sites": 4,
      "resources": 1023
    },
    "TARAZEDAR-BELT-1": {
      "devices": 23,
      "replicants": 1,
      "resource_sites": 10,
      "resources": 23012
    }
  }
}
```

--------------------------------

### Example SSE Stream Response

Source: https://replicant.space/docs/api/events/stream

This is an example of the Server-Sent Events (SSE) stream response format. It includes event IDs, event types, and JSON data payloads, as well as keepalive comments.

```text
id: 1752681600000-0
event: mining.started
data: {"version":1,"category":"mining","event":"mining.started","device_code":"2AC61214","payload":{"resource_type":"structural","site":"SOL-BELT-1-SITE-3"},"created_at":"2026-07-16T10:00:00Z"}

id: 1752681620000-0
event: travel.departed
data: {"version":1,"category":"travel","event":"travel.departed","device_code":"7FE981A0","payload":{"travel_type":"cruise","origin":"SOL-4","destination":"SOL-BELT-1"},"created_at":"2026-07-16T10:03:20Z"}

: keepalive
```

--------------------------------

### Register New Account

Source: https://replicant.space/docs/api/accounts/registration

Use this snippet to create a new account by sending an email, name, and timezone to the /v1/accounts endpoint. A verification email will be sent.

```shell
$ curl -X POST https://api.replicant.space/v1/accounts \
    -H "Content-Type: application/json" \
    -d '{
      "email": "bob@replicant.space",
      "name": "Bob",
      "timezone": "Europe/London"
    }'
```

--------------------------------

### Set Entry Point Device Command

Source: https://replicant.space/docs/api/devices/command

Instruct a system hub to update the star catalogue. Sets the surge entry point of a star system to the hub's current location.

```APIDOC
## _set_entry_point_

### Description
Instruct a system hub to update the star catalogue. Sets the surge entry point of a star system to the hub's current location.

### Method
POST

### Endpoint
/devices/command

### Request Body
```json
{
  "command": "set_entry_point"
}
```
```

--------------------------------

### _mining.started

Source: https://replicant.space/docs/api/events/catalogue

A device began mining at a belt or salvage site.

```APIDOC
## _mining.started

### Description
A device began mining at a belt or salvage site.

### Response Example
```json
{
  "location_type": "belt",       // "belt" or "salvage"
  "location": "SOL-BELT-1",
  "site": "SOL-BELT-1-SITE-3",
  "resource_type": "structural",
  "availability": "high",
  "density": "moderate",
  "cycle_time_seconds": 52
}
```
```

--------------------------------

### Per-scenario leaderboard

Source: https://replicant.space/docs/simulations/leaderboards

Get the top 10 personal bests for a specific scenario.

```APIDOC
## GET /v1/leaderboards/simulations/{scenario_code}

### Description
Get the top 10 personal bests for a specific scenario. Pass the scenario code in the URL.

### Method
GET

### Endpoint
/v1/leaderboards/simulations/{scenario_code}

### Parameters
#### Path Parameters
- **scenario_code** (string) - Required - The unique code of the scenario for which to retrieve the leaderboard.

### Response
#### Success Response (200)
- **scenario_code** (string) - The unique code for the scenario.
- **scenario_name** (string) - The display name of the scenario.
- **entries** (array) - A list of leaderboard entries.
  - **rank** (integer) - The player's rank in the scenario.
  - **replicant_code** (string) - The unique code for the player's account.
  - **name** (string) - The display name of the player.
  - **score_seconds** (integer) - The player's completion time in seconds.
  - **resources_mined** (integer) - The amount of resources mined during the run.
  - **devices_printed** (integer) - The number of devices printed during the run.
  - **completed_at** (string) - The timestamp when the scenario was completed (ISO 8601 format).

### Response Example
```json
{
  "scenario_code": "mining_rush",
  "scenario_name": "Mining Rush",
  "entries": [
    {
      "rank": 1,
      "replicant_code": "7A303E2A",
      "name": "Bob",
      "score_seconds": 1842,
      "resources_mined": 1031,
      "devices_printed": 2,
      "completed_at": "2026-07-08T09:22:14"
    },
    {
      "rank": 2,
      "replicant_code": "C4D5E6F7",
      "name": "Alice-3",
      "score_seconds": 2104,
      "resources_mined": 1155,
      "devices_printed": 5,
      "completed_at": "2026-07-09T16:45:30"
    }
  ]
}
```
```

--------------------------------

### Execute a Trade

Source: https://replicant.space/docs/trading/directory

Initiate a trade by sending a POST request to the trade endpoint. This requires your replicant to be at the shop's location with the necessary criteria items.

```bash
$ curl -X POST https://api.replicant.space/v1/devices/93C4B199/trades/TRD-1A893F \
    -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### Response for Setting Welcome Message

Source: https://replicant.space/docs/system-hubs

This is the expected JSON response after successfully setting a welcome message for a system hub.

```json
{
  "status": "set",
  "welcome_message": "Welcome to PHARM. Trading outposts on the third planet are fully stocked!"
}
```

--------------------------------

### GET /v1/replicants

Source: https://replicant.space/docs/api/replicants/directory

Browse the replicants currently known to the galaxy. You can filter and paginate the results.

```APIDOC
## GET /v1/replicants

### Description
Browse the replicants currently known to the galaxy. You can filter and paginate the results.

### Method
GET

### Endpoint
/v1/replicants

### Parameters
#### Query Parameters
- **cursor** (integer) - Optional - Position in the list to start from, default null.
- **limit** (integer) - Optional - Number of replicants to show, default 20.
- **latest** (boolean) - Optional - Show latest replicants. Default `false`. Incompatible with `cursor`.
- **name** (string) - Optional - Search replicant names. Matching is case-insensitive.

### Request Example
```
GET /v1/replicants 200 OK
```
```json
{
  "replicants": [
    {
      "name": "Sylphrena",
      "replicant_code": "30B93F2F",
      "last_location": "IMPOLLA",
      "is_npc": true
    }
  ],
  "next_cursor": 10
}
```

### Response
#### Success Response (200)
- **name** (string) - public name.
- **replicant_code** (string) - the replicant's internal code.
- **last_location** (string) - the last known location of the replicant (according to BobNet).
- **is_npc** (boolean) - whether the replicant is a player or an NPC.

#### Response Example
```json
{
  "replicants": [
    {
      "name": "Sylphrena",
      "replicant_code": "30B93F2F",
      "last_location": "IMPOLLA",
      "is_npc": true
    }
  ],
  "next_cursor": 10
}
```
```

--------------------------------

### Replicate Device Command

Source: https://replicant.space/docs/api/devices/command

Initiate a tight-beam replication process using an empty replicant matrix at your current location. This is similar to teleportation but does not destroy the original.

```json
{ "command": "replicate", "target": <code> }
```

--------------------------------

### List Available Blueprints

Source: https://replicant.space/docs/quickstart

Use this command to see which blueprints you have unlocked. This helps you understand what devices you can print.

```bash
# 8. see which blueprints you can print
$ curl https://api.replicant.space/v1/blueprints \
    -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### GET /v1/stars

Source: https://replicant.space/docs/api/locations/star-catalogue

Downloads the complete star catalogue. The response is pre-built and cached for instant retrieval.

```APIDOC
## GET /v1/stars

### Description
Retrieves the entire star catalogue. The response is pre-built and cached, ensuring instant returns.

### Method
GET

### Endpoint
/v1/stars

### Rate Limit
1 request per minute per account.

### Caching
The catalogue is regenerated every 5 minutes. The `generated_at` field indicates the build time of the current snapshot. Newly discovered stars appear within 5 minutes of discovery.

### Request Example
```
GET /v1/stars
Authorization: Bearer $API_KEY
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of stars in the catalogue.
- **generated_at** (string) - The timestamp indicating when the catalogue was generated.
- **stars** (array) - An array of star objects.
  - **designation** (string) - The star's designation.
  - **name** (string) - The star's common name.
  - **spectral_type** (string) - The star's spectral type.
  - **color** (string) - The star's color.
  - **position** (object) - The star's coordinates.
    - **x** (number) - The x-coordinate.
    - **y** (number) - The y-coordinate.
    - **z** (number) - The z-coordinate.
  - **estimated_planets** (integer) - The estimated number of planets in the system.
  - **entry_point** (string) - The entry point to the system (if applicable).
  - **has_hub** (boolean) - Indicates if the system has a hub.

#### Response Example
```json
{
  "total": 24,
  "generated_at": "2026-07-12T14:30:00.123456+00:00",
  "stars": [
    {
      "designation": "CYGNUS",
      "name": "Cygnus Prime",
      "spectral_type": "M5",
      "color": "yellow",
      "position": {
        "x": 41.2,
        "y": -11.4,
        "z": 30.9
      },
      "estimated_planets": 6,
      "entry_point": "CYGNUS-5-L4",
      "has_hub": true
    },
    {
      "designation": "TARAZEDAR",
      "spectral_type": "K4",
      "color": "red",
      "position": {
        "x": -2.55,
        "y": 0.44,
        "z": 6.71
      },
      "estimated_planets": 4
    }
  ]
}
```

### Notes
- The catalogue does not include account-specific fields. Use `nearest stars` for distance-aware listings.
- If the catalogue is being prepared, the endpoint returns `503` with a retry message.
```

--------------------------------

### List Available Scenarios

Source: https://replicant.space/docs/simulations/scenarios

Use the `curl` command to query the replicant interface's simulate endpoint and retrieve a list of available scenarios for a specific datacentre.

```bash
$ curl GET https://api.replicant.space/v1/devices/A1B2C3D4/simulate \
    -H "Authorization: Bearer $API_KEY"
```

--------------------------------

### Withdraw Response

Source: https://replicant.space/docs/ami

Example response when a fleet is successfully withdrawn. It lists devices that were recalled and operations that were stopped.

```json
{
  "device_code": "175B5AD3",
  "assigned_devices": {
    "already_stowed": [],
    "failed": [],
    "recalled": [
      "E811348D",
      "6414BB30",
      "494140A7",
      "ADA90515",
      "6DABF041"
    ],
    "stopped_mining": [],
    "stopped_scanning": [
      "E811348D",
      "6414BB30",
      "494140A7",
      "ADA90515",
      "6DABF041"
    ],
    "stopped_tracking": []
  },
  "status": "withdrawn"
}
```

--------------------------------

### Registering an account

Source: https://replicant.space/docs/authentication

Create a new account by sending a POST request with your email, name, and timezone to the /v1/accounts endpoint. The timezone can be an IANA zone or a UTC offset.

```APIDOC
## Registering an account

### Description
Create an account by POSTing your email, name and timezone to `/accounts`. Timezone accepts any IANA zone (e.g. `Europe/London`, `America/Los_Angeles`) or a fixed UTC offset like `+02:00`.

### Method
POST

### Endpoint
/v1/accounts

### Parameters
#### Request Body
- **email** (string) - Required - The email address for the account.
- **name** (string) - Required - The name of the account holder.
- **timezone** (string) - Required - The IANA timezone or UTC offset.

### Request Example
```
POST /v1/accounts
Content-Type: application/json

{
  "email": "bob@replicant.space",
  "name": "Bob",
  "timezone": "Europe/London"
}
```

### Response
#### Success Response (201 Created)
- **message** (string) - Confirms that a verification email has been sent.
```
Tokens:
Raw