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
- Only the group leader runs the server.
- Base URL:
http://<host>:<port>/api/v1/. The app shows the host and port. - Send the key from the toggle in every request:
Authorization: Bearer <api-key>. - Request and response bodies are JSON, up to 64 KiB.
- A wrong or missing key returns
401withWWW-Authenticate: Bearer. - While the Control API is off, every path returns
404. - Requests from outside the local network get no response. The server closes the connection.
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.
spoofingtruewhile the follower is spoofing.followingtruewhile the follower follows the leader. It turnsfalsewhen 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.
nullwhen 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"}ornull.bearing- Degrees, 0 = north, clockwise.
nullwhen 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.
GET/search
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).truefollows 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 forloopMode:truemeansRESTART.loopModewins when you send both. reverse- boolean optional Default
false. Play the waypoints in reverse. loopMode- string optional Default
OFF.OFFplays the route once.RESTARTstarts over at the first stop.WALK_BACKturns 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) orPLANTING(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; ignoresplantingInfiniteLoopsandplantingLoopCount. plantingLoopCount- integer optional App default 1. Number of loops when
plantingInfiniteLoopsisfalse. 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.
nullclears 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.
nullclears 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
- The API works only on the same Wi-Fi network. It does not work over the internet or mobile data.
- The API uses plain HTTP, so requests travel unencrypted. Do not send the API key over an untrusted network.
- Send the key in the
Authorizationheader with each request. Treat it like a password. - The API is off when you create or join a group. Turn it on in the Control API section to let other apps connect.
- Leaving the group or restarting the app turns the API off. The key stays, so you can turn the API back on later.
- To create a new key, tap Regenerate key in the Control API section. The old key stops working at once.
- Teleports and routes sent through the API work even when Hide Teleport is on. See /teleport and /route/start.
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}}
Build a link by hand
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
lat
Type: decimal
Valid range: −90 to 90
Latitude
lon
Type: decimal
Valid range: −180 to 180
Longitude
Example:
https://locationjoystick.shrtcts.fr/?lat=35.6762&lon=139.6503
- Both
latandlonare required. The app ignores a link lacking either one. - The app ignores a link with coordinates outside the valid range.
- No key or sign-in is needed.
- A second format also works:
locationjoystick://open?lat=LAT&lon=LON. Use thehttps://link when sharing with other people.