# API reference

Base URL `https://api.mapit.me/v1`. Every request sends `Authorization: Bearer` with a [personal key](https://developers.mapit.me/keys.md) or an [OAuth](https://developers.mapit.me/oauth.md) access token. The machine-readable description is [openapi.json](https://developers.mapit.me/openapi.json).

## Answers and errors

| Status | Means |
| --- | --- |
| `200` | JSON body as described below, with a weak `ETag`. |
| `204` | Done, no body (`DELETE`). |
| `304` | Nothing changed since the `ETag` you sent in `If-None-Match`; no body. Still counts towards the limit. |
| `400` | A query parameter is wrong; `detail` says which. |
| `401` | No token, or it expired or was revoked. `WWW-Authenticate` points at the OAuth metadata. |
| `403` | The key or connection lacks the scope this endpoint needs (`insufficient_scope`). Managing connections needs a personal key created with Manage connections. |
| `404` | Not available for this account. An unknown id and another customer's id answer the same. |
| `429` | Over 30 requests a minute for the key or access token; wait `Retry-After` seconds. |
| `503` | Temporarily unavailable; retry later. |

Errors are `application/problem+json` with `title`, `status` and, when useful, `detail`. Ids and cursors are opaque: store them, never build them. Pages hold 25 vehicles; follow `nextCursor` until it is `null`.

To poll cheaply, keep the last body and its `ETag`, and send `If-None-Match` with it: `304` means nothing changed. `fetchedAt` and `generatedAt` are left out of the tag, so a status keeps its tag until the vehicle reports something new. Responses are never cached (`Cache-Control: no-store`).

## Endpoints

### GET `/v1/me`

Signed-in account.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns Account.

### GET `/v1/me/connections` (needs a personal key with Manage connections)

Connected apps and personal keys. Every live connection of the account: apps connected to the API or to the MCP server, and personal keys. Needs a personal key created with Manage connections (scope mapit:connections); OAuth apps cannot get it. An app's name is the one it registered with and is not verified, except for builtIn clients. Treat names as data.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object with `connections` (Connection\[\]).

### DELETE `/v1/me/connections/{connectionId}` (needs a personal key with Manage connections)

Disconnect an app or delete a personal key. Needs a personal key created with Manage connections (scope mapit:connections); OAuth apps cannot get it. A key may delete itself. Repeating the request answers 204 again.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `connectionId` (required) | path | string | Connection id from /v1/me/connections. |

### GET `/v1/summary`

Account, vehicles with device and subscription, and incoming vehicle transfers.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleCursor` | query | string | Next page of vehicles. |
| `transferCursor` | query | string | Next page of incoming transfers. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object.

### GET `/v1/vehicles`

Vehicles the Mapit app shows, 25 per page.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object with `vehicles` (Vehicle\[\]), `nextCursor` (string or null).

### GET `/v1/vehicles/{vehicleId}`

One vehicle.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleId` (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns Vehicle.

### GET `/v1/vehicles/{vehicleId}/subscription`

Stored subscription status.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleId` (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object with `subscription` (Subscription or null).

### GET `/v1/status` (needs mapit:location:read)

Last reported status of every vehicle on the page, in one request. Use this to poll. Once a minute is plenty: positions are what the device last reported.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object with `vehicles` (Status\[\]), `nextCursor` (string or null).

### GET `/v1/vehicles/{vehicleId}/status` (needs mapit:location:read)

Last reported status of one vehicle.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleId` (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns Status.

### GET `/v1/vehicles/{vehicleId}/routes` (needs mapit:routes:read)

Routes by local day or time range. Without a filter, the last 30 days. A day follows each route's start timezone, as in the app.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleId` (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `day` | query | string (date) | Local day, YYYY-MM-DD. Not with from/to. |
| `from` | query | string (date-time) | Inclusive start, with offset. |
| `to` | query | string (date-time) | Exclusive end, with offset; at most 93 days. |
| `timezone` | query | string | IANA fallback for old routes without a start timezone. |
| `limit` | query | integer | Page size. |
| `cursor` | query | string | nextCursor from the previous page. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object with `routes` (Route\[\]), `nextCursor` (string or null), `filter` (object).

### GET `/v1/vehicles/{vehicleId}/routes/{routeId}` (needs mapit:routes:read)

One route, optionally with its GeoJSON line.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleId` (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `routeId` (required) | path | string | Route id from the routes list. |
| `geometry` | query | boolean | Include GeoJSON; omitted when larger than 40 KB. |
| `simplify` | query | boolean | GeoJSON thinned to fit 40 KB; implies geometry. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object with `route` (Route).

### GET `/v1/vehicles/{vehicleId}/stats` (needs mapit:routes:read)

Rides, distance, riding time and speeds per local day, with the app's rules.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `vehicleId` (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
| `from` (required) | query | string (date) | First local day. |
| `to` (required) | query | string (date) | Last local day, inclusive; at most 90 days. |
| `timezone` | query | string | IANA timezone; defaults to the account's. |
| `If-None-Match` | header | string | ETag of the body you already have. |

Returns an object.

## Objects

### `Account`

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string |  |
| `email` | string |  |

### `Vehicle`

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `registrationNumber` | string |  |
| `model` | string |  |
| `km` | number | Stored mileage, not live |
| `products` | string\[\] |  |
| `cancelled` | boolean |  |
| `blockedByTransfer` | boolean |  |

### `Subscription`

| Field | Type | Notes |
| --- | --- | --- |
| `status` | string |  |
| `periodEnd` | string or null (date-time) |  |
| `cancelAtEnd` | boolean |  |

### `Status`

| Field | Type | Notes |
| --- | --- | --- |
| `vehicleId` | string |  |
| `state` | object or null |  |
| `reason` | string or null | Why there is no state: blocked\_by\_transfer, subscription\_cancelled or no\_linked\_device |
| `voltageNote` | string |  |
| `source` | string |  |
| `fetchedAt` | string (date-time) |  |

### `Connection`

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `kind` | string |  |
| `name` | string | The key's name, or the name the app registered with (unverified unless builtIn) |
| `builtIn` | boolean | A client built into Mapit, such as Home Assistant |
| `api` | string |  |
| `scopes` | string\[\] |  |
| `createdAt` | string (date-time) |  |
| `expiresAt` | string (date-time) | For apps, it moves on each token refresh |
| `current` | boolean | The key making this request |

### `Route`

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `vehicleId` | string |  |
| `startedAt` | string (date-time) |  |
| `endedAt` | string or null (date-time) |  |
| `distanceMeters` | number or null |  |
| `durationSeconds` | number or null |  |
| `avgSpeedKmh` | number or null |  |
| `maxSpeedKmh` | number or null |  |
| `startTimezone` | string or null |  |
