Developer API

The Micro VPS exposes a REST API over HTTP for direct integration with your GCS software.

Default Base URL: http://192.168.218.100:5000

All responses are JSON. Endpoints return {"code": "SUCCESS", ...} on success and {"code": "ERROR", "message": "..."} on failure.

---

Integration Flow

1. GET /api/ping — verify the module is reachable

2. POST /api/upload/maps — upload a map archive

3. GET /api/extraction/status — poll until extraction completes

4. POST /api/maps/set — activate the uploaded map

5. POST /api/home-position — set the takeoff / starting location

---

Connectivity

Ping

GET /api/ping

Response 200:

{
  "status": "ok"
}

---

Map Management

Upload a Map

POST /api/upload/maps

Uploads a .tar.gz map archive. The file is received synchronously; extraction happens in the background.

Headers:

Header	Required	Description
filename	Yes	URL-encoded filename, must end in .tar.gz
checksum	No	SHA256 checksum for integrity verification

Body: Raw binary stream of the .tar.gz file.

Response 200:

{
  "code": "SUCCESS",
  "message": "Upload received, extraction started for my-map.tar.gz",
  "size": 104857600,
  "chunks_processed": 12800,
  "checksum": "abc123...",
  "extraction_queued": true,
  "map_name": "my-map"
}

After a successful upload, poll /api/extraction/status until extraction is complete.

---

Get Extraction Status

GET /api/extraction/status

Poll this endpoint after uploading a map to monitor background extraction progress.

Response 200:

{
  "code": "SUCCESS",
  "data": { ... }
}

---

List Available Maps

GET /api/maps

Response 200:

{
  "code": "SUCCESS",
  "data": [
    {
      "name": "my-map",
      "size": 209715200,
      "size_human": "200.0 MB",
      "modified": 1710000000.0,
      "completed": true,
      "checksum": "abc123...",
      "format_version": "1.0.0",
      "min_firmware_version": "1.16.0"
    }
  ]
}

completed is false while extraction is still in progress. A map cannot be activated until completed is true.

---

Get Active Map

GET /api/maps/current

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "active_map": "my-map"
  }
}

Returns "active_map": null if no map is selected.

---

Set Active Map

POST /api/maps/set
Content-Type: application/json

Request body:

{
  "map_name": "my-map"
}

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "active_map": "my-map",
    "message": "Active map set to my-map"
  }
}

Error Code	Reason
400	Missing map_name
400	Map extraction not yet complete
404	Map not found

---

Delete a Map

POST /api/maps/delete
Content-Type: application/json

Request body:

{
  "map_name": "my-map"
}

Field	Required	Description
map_name	Yes	Name of the map to delete
new_active_map	No	If deleting the active map, switch to this map first
new_home_position	No	Home position for the new active map (lat, lon, alt)

---

Home Position

Get Home Position

GET /api/home-position

Response 200:

{
  "home_position": {
    "lat": 54.0887,
    "lon": 12.1407,
    "alt": 42.5
  }
}

---

Set Home Position

POST /api/home-position
Content-Type: application/json

Sets the starting point for navigation. A map must be active before setting the home position.

Request body:

{
  "lat": 54.0887,
  "lon": 12.1407,
  "alt": 0
}

Field	Required	Description
lat	Yes	Latitude in degrees (-90 to 90)
lon	Yes	Longitude in degrees (-180 to 180)
alt	Yes	Altitude in meters — automatically replaced by an elevation lookup from the active map data

Response 200:

{
  "code": "SUCCESS",
  "message": "Home position updated successfully",
  "home_position": {
    "lat": 54.0887,
    "lon": 12.1407,
    "alt": 42.5
  }
}

Error Code	Reason
400	Missing lat or lon
400	Coordinates not numeric or out of valid range
500	Elevation lookup failed — is a map loaded?