# 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?    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.theseus.us/micro-vps/autopilot-integration/developer-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.