Control API (for developers)

The Control API lets your own code send commands to this device over your Wi-Fi. Turn on the Control API toggle in the Group Sync leader section to get the address and key. Commands act like taps and swipes, so followers see the same movement.

Overview

curl -H "Authorization: Bearer abcdef123456..." \
  http://192.168.1.100:8080/api/v1/status

Endpoints

All paths start with /api/v1. Commands that succeed return {"ok":true}.

Errors

Errors return { "error": { "code": "...", "message": "..." } }. Use code in your program and message for people.

400 bad_request

Invalid input, bad coordinates, unknown profile or kind, or malformed JSON.

401 unauthorized

Missing or incorrect key.

404 not_found

Unknown path, or the Control API is off.

404 route_not_found, favorite_not_found, speed_profile_not_found

No item with that ID.

405 method_not_allowed

Wrong method. The Allow header lists the right ones.

409 no_position

The device has no position to report. While spoofing is off, it has no saved position and no real location yet.

409 conflict

A route is playing, so you cannot start roaming or edit that route.

413 payload_too_large

Body is over 64 KiB.

431 (no body)

The request has too many header lines. The response has no body and no error code.

500 internal_error

Server error. Try again.

State and status

GET/status

Returns the API version, the device's role (always "leader"), the number of active followers, and one entry per follower in followerStates, sorted by id.

id
The follower's IP address.
spoofing
true while the follower is spoofing.
following
true while the follower follows the leader. It turns false when the follower moves on its own.
distanceM
Whole metres from the follower to the leader. It is approximate by a few metres, because followers add jitter. null when the leader is paused or the follower sent no position.
lastPollAgeMs
Milliseconds since the follower last polled.

A follower on an older app version sends no state. It still counts and appears with spoofing, following and distanceM set to null.

Returns {"apiVersion":1,"role":"leader","followers":N,"followerStates":[{"id","spoofing","following","distanceM","lastPollAgeMs"}]}.

GET/state

Full state snapshot. Fields without a value are null.

spoofState
One of IDLE, RUNNING, PAUSED, ERROR.
mode
One of JOYSTICK, ROUTE_REPLAY, ROAMING, WALK_TO, TELEPORT, FOLLOWER.
position
{"lat","lon"} or null.
bearing
Degrees, 0 = north, clockwise. null when unknown.
speedMs
Current speed in meters per second.
activeRouteId
ID of the playing route, or null.
walk
{"target":{"lat","lon"} or null,"paused":boolean}.
roaming
{"active":boolean,"paused":boolean}.
speedProfileId
ID of the active speed profile, such as walk.

GET/position

Current position only. While spoofing is off, it returns the last remembered position when the app remembers it, otherwise the phone's real location.

Returns {"lat":double,"lon":double,"source":"mock"|"real"}. source is mock for a spoofed or remembered position and real for the phone's real location. Returns 409 no_position if no position is known.

Search for a place by name. It returns the same results as the map search bar, in the same order. It moves nothing.

q
string required Query parameter, URL-encoded, such as /search?q=paris%20les%20tuileries.

Returns {"results":[{"name":string,"lat":double,"lon":double}]}. The list is empty when nothing matches. Returns 400 bad_request when q is missing or blank. Returns 502 geocoding_failed when the search service fails.

Movement commands

POST/teleport

Teleport to the given coordinates. Followers follow or walk there, depending on their Follow leader teleports setting. The cooldown is advisory: inside the suggested cooldown the teleport still runs, and the response adds a warning field (see the example). The Hide Teleport setting does not block this call.

lat
double required Latitude, -90 to 90.
lon
double required Longitude, -180 to 180.

POST/walk

Walk to the given coordinates. Followers walk toward the same target at their own speed.

lat
double required Latitude, -90 to 90.
lon
double required Longitude, -180 to 180.
viaRoads
boolean optional Default false (straight line). true follows roads.

POST/walk/pause

Pause the current walk without stopping it. The position is frozen.

POST/walk/resume

Resume a paused walk.

POST/walk/stop

Stop the walk and clear the target.

POST/route/start

Start playing a saved route. Only routeId is required. Every other option keeps its default unless you set it. Followers walk or snap to waypoints, depending on their teleport setting. The Hide Teleport setting does not block teleportBetweenWaypoints.

routeId
string required ID of a saved route.
loop
boolean optional Default false. Older shorthand for loopMode: true means RESTART. loopMode wins when you send both.
reverse
boolean optional Default false. Play the waypoints in reverse.
loopMode
string optional Default OFF. OFF plays the route once. RESTART starts over at the first stop. WALK_BACK turns around at each end. Walk back is ignored for planting and teleport routes. Any other value returns 400.
returnToLocation
boolean optional Default false. Walk back to the starting position at the end.
followRoadsToStart
boolean optional Default false. Follow roads on the way to the first waypoint.
planting
boolean optional Default false. Use the planting pattern.
teleportBetweenWaypoints
boolean optional Default false. Jump between waypoints instead of walking.
teleportBetweenDelaySeconds
integer optional Default 8. Seconds to wait between jumps. Clamped to 0 to 600.

Returns 404 route_not_found if the route does not exist.

POST/route/pause

Pause the current route replay.

POST/route/resume

Resume a paused route replay.

POST/route/stop

Stop route replay and clear the active route.

POST/roam/start

Start roaming. Every field is optional and defaults to the app's saved roaming settings. Send both lat and lon, or neither to start from the current position.

lat
double optional Latitude, -90 to 90.
lon
double optional Longitude, -180 to 180.
radiusMeters
double optional Meters, app default 500, clamped to 1 to 100000. Roaming stays within this distance of the start.
distanceMeters
double optional Meters, app default 1000, clamped to 50 to 50000. Total distance to cover.
speedProfileId
string optional App default walk. Speed profile ID.
followRoads
boolean optional App default true. Follow roads.
returnToInitialLocation
boolean optional App default true. End back at the start.
kind
string optional WALK_AROUND (random points, app default) or PLANTING (grid pattern).
plantingStartRadiusMeters
double optional Meters, app default 5. Inner radius of the planting grid.
plantingEndRadiusMeters
double optional Meters, app default 39. Outer radius of the planting grid.
plantingInfiniteLoops
boolean optional App default true. Repeat until stopped.
plantingSpacingMeters
integer optional Meters between spiral rings, app default 5. Minimum 1, no maximum.
plantingExpandOnly
boolean optional App default false. Walk the spiral out once and stop; ignores plantingInfiniteLoops and plantingLoopCount.
plantingLoopCount
integer optional App default 1. Number of loops when plantingInfiniteLoops is false.
plantingSpeedProfileId
string optional Profile ID, app default bike.

Returns 400 bad_request for a non-finite number or an unknown speed profile, and 409 conflict if a route is playing.

POST/roam/pause

Pause roaming.

POST/roam/resume

Resume roaming.

POST/roam/stop

Stop roaming.

POST/spoofing/start

Start the fake location. Does nothing if it is already running.

POST/spoofing/stop

Stop the fake location.

POST/speed-profile

Set the active speed profile (such as "slow_walk", "walk", "run", "bike", "drive").

id
string required

Returns 400 bad_request if the profile ID is unknown.

POST/joystick

Hold the joystick in one direction for a short time, like a finger held down. A new request replaces any running hold. Send force 0 or durationMs 0 to release at once.

bearingDegrees
double required Direction in degrees, 0 = north, clockwise.
force
double required 0 to 1. How far the stick is pushed.
durationMs
long required Milliseconds to hold, up to 10000.

Content API (Favorites, Routes, Speed Profiles)

GET/favorites

List all favorites.

Returns an array of objects with id, name, lat, lon, createdAt (milliseconds since epoch), and category (string or null).

POST/favorites

Create a new favorite.

name
string required Favorite name. Cannot be empty.
lat
double required Latitude, -90 to 90.
lon
double required Longitude, -180 to 180.
category
string optional

Returns 201 Created with the new favorite object (includes id and createdAt).

GET/favorites/{id}

Get a single favorite by ID.

Returns 404 favorite_not_found if not found.

PUT/favorites/{id}

Update a favorite. Preserves id and createdAt.

name
string required Favorite name. Cannot be empty.
lat
double required Latitude, -90 to 90.
lon
double required Longitude, -180 to 180.
category
string optional

Returns 404 favorite_not_found if not found.

DELETE/favorites/{id}

Delete a favorite.

Returns 404 favorite_not_found if not found.

GET/routes

List all routes (excludes the internal paste-temp scratch route).

Returns an array of route objects with id, name, routeType, isLooping, speedProfileId (string or null), randomizeTeleportOrder, plantingRadiusMeters (only when set), createdAt, updatedAt, and waypoints (array of {id,lat,lon,orderIndex,waitSeconds}).

POST/routes

Create a new route.

name
string required Route name.
routeType
string optional One of STRAIGHT, GUIDED, TELEPORT.
isLooping
boolean optional
speedProfileId
string optional Speed profile ID. Unset means none.
randomizeTeleportOrder
boolean optional
plantingRadiusMeters
number optional Circle radius, 5 to 200. Makes the route a Planting route. Left out on update keeps the current value. null clears it.
waypoints
array of objects required Each item is {lat,lon,waitSeconds?}. At least 2 waypoints required.

Returns 201 Created with the new route object.

GET/routes/{id}

Get a single route by ID.

Returns 404 route_not_found if not found or if it is the internal scratch route.

PUT/routes/{id}

Update a route (entire waypoint list). Body: same as POST /routes. Preserves id and createdAt, updates updatedAt.

name
string required Route name.
routeType
string optional One of STRAIGHT, GUIDED, TELEPORT.
isLooping
boolean optional
speedProfileId
string optional Speed profile ID. Unset means none.
randomizeTeleportOrder
boolean optional
plantingRadiusMeters
number optional Circle radius, 5 to 200. Makes the route a Planting route. Left out on update keeps the current value. null clears it.
waypoints
array of objects required Each item is {lat,lon,waitSeconds?}. At least 2 waypoints required.

Returns 404 route_not_found if not found, or 409 conflict if the route is playing.

DELETE/routes/{id}

Delete a route.

Returns 404 route_not_found if not found, or 409 conflict if the route is playing.

GET/speed-profiles

List the five built-in speed profiles.

Returns an array of objects with id, name, speedMetersPerSecond, builtIn (always true), active (boolean flag), and enabled (boolean flag).

GET/speed-profiles/{id}

Get a single profile by ID. Profile IDs: slow_walk, walk, run, bike, drive.

Returns 404 speed_profile_not_found if not found.

PUT/speed-profiles/{id}

Update a speed profile's speed. Profile ID, name, and builtIn flag cannot be changed.

speedMetersPerSecond
double required Must be between 0.01 and 15.0.

Returns the updated profile. Returns 400 bad_request if the speed is out of range, or 404 speed_profile_not_found if the profile does not exist.

Security limits

Example: teleport with curl

This request teleports the leader to Times Square in New York.

curl -X POST http://192.168.1.100:8080/api/v1/teleport \
  -H "Authorization: Bearer abcdef123456..." \
  -H "Content-Type: application/json" \
  -d '{"lat":40.758,"lon":-73.9855}'

On success the response is:

{"ok":true}

Inside the suggested cooldown the teleport still runs. The response adds a warning:

{"ok":true,"warning":{"code":"teleport_cooldown","message":"Suggested teleport cooldown has not elapsed","remainingSeconds":45,"totalSeconds":120,"distanceMeters":5280}}

You can build a link by hand for scripts or automation. The share icon in the app produces the https:// form below.

https://locationjoystick.shrtcts.fr/?lat=LAT&lon=LON

Type: decimal

Valid range: −90 to 90

Latitude

Type: decimal

Valid range: −180 to 180

Longitude

Example:

https://locationjoystick.shrtcts.fr/?lat=35.6762&lon=139.6503