> For the complete documentation index, see [llms.txt](https://docs.theseus.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.theseus.us/micro-vps/autopilot-integration/developer-api.md).

# 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`:**

```json
{
  "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`:**

```json
{
  "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`:**

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

***

#### List Available Maps

```
GET /api/maps
```

**Response `200`:**

```json
{
  "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`:**

```json
{
  "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:**

```json
{
  "map_name": "my-map"
}
```

**Response `200`:**

```json
{
  "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:**

```json
{
  "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`:**

```json
{
  "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:**

```json
{
  "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`:**

```json
{
  "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?    |