REST API

API Documentation

Integrate Runify GPS tracking into your mobile app. Send positions in real-time or sync at the end of a session.

Authentication

All requests require an application token sent via the X-API-Key header.

Headerhttp
X-API-Key: YOUR_APP_TOKEN

The token is automatically generated when you create an event in the dashboard. The Authorization: Bearer header is also accepted.

Base URL

Productiontext
https://api-runify.domainedunet.fr

Create a track

POST/tracks

Creates a new GPS track. Call this endpoint when tracking starts.

Request body

ParamTypeRequiredDescription
device_track_idstringrequiredUnique device identifier (1–100 chars)
titlestringoptionalTrack title (max 500 chars). If omitted, auto-generated: "Sortie du 12 mars à 09h20"
activity_typestringoptionalrun | walk | bike | hike (default: run)
start_tsISO 8601optionalStart date/time
user_idstringoptionalUser identifier (max 255 chars)
image_urlURLoptionalAssociated image URL
Examplebash
curl -X POST https://api-runify.domainedunet.fr/tracks \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_track_id": "track_2024_001",
    "title": "Morning run",
    "activity_type": "run",
    "start_ts": "2024-03-15T07:30:00Z"
  }'

Response 201 on creation, 200 when the same track is replayed (nothing is written twice). The body is what the server holds after the write, not an echo of your request:

Response 201json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "device_track_id": "track_2024_001",
  "state": "running",
  "start_ts": "2024-03-15T07:30:00.000Z",
  "end_ts": null,
  "race_id": null,
  "points_count": 0,
  "last_point_ts": null,
  "hidden": false,
  "offered": false,
  "free_credit_used": false,
  "public_visible": false,
  "pauses_rev": 0,
  "time_basis": null,
  "hero_photo_id": null,
  "photos": []
}

Send GPS points

POST/tracks/:id/points

Send a batch of GPS points. Up to 10,000 points per request. Response 200 with the received and inserted counts.

Point fields

ParamTypeRequiredDescription
latitudenumberrequired-90 → 90
longitudenumberrequired-180 → 180
timestampISO 8601requiredPoint timestamp
altitudenumberoptionalAltitude in meters
accuracynumberoptionalGPS accuracy in meters
speed_mpsnumberoptionalSpeed in m/s
headingnumberoptionalHeading (0–360°)
batterynumberoptionalBattery level (0–1)
originstringoptionalforeground | background | native
Examplebash
curl -X POST https://api-runify.domainedunet.fr/tracks/TRACK_ID/points \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "latitude": 48.8566,
        "longitude": 2.3522,
        "altitude": 35.2,
        "accuracy": 5.0,
        "speed_mps": 3.2,
        "timestamp": "2024-03-15T07:30:05Z",
        "origin": "foreground"
      },
      {
        "latitude": 48.8567,
        "longitude": 2.3524,
        "altitude": 35.5,
        "timestamp": "2024-03-15T07:30:10Z"
      }
    ]
  }'
💡 Response 200, processed synchronously: a replayed batch inserts nothing twice.
Response 200json
{
  "received": 2,
  "inserted": 2,
  "points_count": 128,
  "last_point_ts": "2024-03-15T07:30:10.000Z"
}

Update a track

PATCH/tracks/:id

Update the title, state, or end time of a track.

ParamTypeRequiredDescription
titlestringoptionalNew title
statestringoptionalrunning | paused | stopped
end_tsISO 8601optionalEnd date/time
Examplebash
curl -X PATCH https://api-runify.domainedunet.fr/tracks/TRACK_ID \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "paused"}'

Response 200 with the same snapshot as the creation, never an empty body.

Finish a track

POST/tracks/:id/finish

Finalize a track. Automatically computes statistics (distance, pace, elevation…).

Examplebash
curl -X POST https://api-runify.domainedunet.fr/tracks/TRACK_ID/finish \
  -H "X-API-Key: YOUR_APP_TOKEN"

Full sync

POST/sync

All-in-one endpoint: creates the track, sends points and statistics in a single request. Ideal for end-of-session sync. Up to 50,000 points.

Request body

ParamTypeRequiredDescription
trackobjectrequiredTrack object (see POST /tracks)
pointsarrayrequiredArray of GPS points
statsobjectoptionalPre-computed statistics

Stats fields (optional)

ParamTypeRequiredDescription
distance_metersnumberoptionalTotal distance in meters
duration_secintegeroptionalTotal duration in seconds
elevation_gain_mnumberoptionalElevation gain (m)
elevation_loss_mnumberoptionalElevation loss (m)
mean_speed_mpsnumberoptionalAverage speed (m/s)
pace_sec_per_kmnumberoptionalPace (s/km)
max_speed_mpsnumberoptionalMax speed (m/s)
max_altitude_mnumberoptionalMax altitude (m)
min_altitude_mnumberoptionalMin altitude (m)
points_countintegeroptionalNumber of points
Examplebash
curl -X POST https://api-runify.domainedunet.fr/sync \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "track": {
      "device_track_id": "track_2024_001",
      "title": "Trail du Glazig - 25km",
      "activity_type": "run",
      "start_ts": "2024-03-15T07:30:00Z",
      "end_ts": "2024-03-15T09:45:00Z"
    },
    "points": [
      {
        "latitude": 48.2345,
        "longitude": -3.5678,
        "altitude": 45.2,
        "speed_mps": 2.8,
        "timestamp": "2024-03-15T07:30:05Z"
      }
    ],
    "stats": {
      "distance_meters": 25340,
      "duration_sec": 8100,
      "elevation_gain_m": 850,
      "mean_speed_mps": 3.13,
      "pace_sec_per_km": 319
    }
  }'
Response 201json
{
  "track_id": "550e8400-e29b-41d4-a716-446655440000"
}

Get a track

GET/tracks/:id

Returns a track's details with its computed statistics.

Examplebash
curl https://api-runify.domainedunet.fr/tracks/TRACK_ID \
  -H "X-API-Key: YOUR_APP_TOKEN"
Response 200json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "device_track_id": "track_2024_001",
  "title": "Sortie du 12 mars à 09h20",
  "activity_type": "run",
  "state": "running",
  "start_ts": "2026-03-12T09:20:00.000Z",
  "end_ts": null,
  "image_url": null,
  "points_count": 121,
  "stats": {
    "distance_meters": 1200,
    "duration_sec": 600,
    "elevation_gain_m": 15,
    "mean_speed_mps": 2.0,
    "pace_sec_per_km": 500
  },
  "created_at": "2026-03-12T09:20:00.000Z",
  "updated_at": "2026-03-12T09:30:00.000Z"
}

List a device's tracks

GET/tracks/mine

Returns the tracks of the calling device, for the event of the token. The device is proven by the X-Device-Id header (the same device_id sent at creation): another device, even with the same token, gets none. Read-only. Hidden or locked tracks are returned to their own device; tracks deleted in the app are returned too, so the app must not revive them.

ParamTypeRequiredDescription
limitintegeroptional1 to 100 (default: 50)
cursoruuidoptionalThe next_cursor of the previous page. Order is by id, not chronological: sort on start_ts.
Examplebash
curl "https://api-runify.domainedunet.fr/tracks/mine?limit=50" \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "X-Device-Id: YOUR_DEVICE_ID"
Response 200json
{
  "tracks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "device_track_id": "your-own-track-id",
      "title": "Morning run",
      "activity_type": "run",
      "state": "stopped",
      "start_ts": "2026-03-12T09:00:00.000Z",
      "end_ts": "2026-03-12T09:30:00.000Z",
      "points_count": 121,
      "stats": {
        "distance_meters": 5200,
        "duration_sec": 1800,
        "elevation_gain_m": 15,
        "mean_speed_mps": 2.9,
        "pace_sec_per_km": 346
      },
      "hidden": false,
      "offered": false,
      "public_visible": true,
      "hero_photo_id": null,
      "photos": []
    }
  ],
  "next_cursor": null
}

400: X-Device-Id missing or empty, limit outside 1 to 100, or cursor that is not a uuid. No 404: an unknown device gets an empty list (indistinguishable from a device with no tracks). 429 with a Retry-After header beyond 12 calls per minute per device (120 per minute per IP address).

List GPS points

GET/tracks/:id/points

Returns all GPS points for a track, sorted by timestamp ascending. Only for the device that created it: the X-Device-Id header must be the track's device_id. Another device, a missing header and an unknown track all get the same 404.

Query parameters

ParamTypeRequiredDescription
limitintegeroptionalInteger from 1 to 50,000 (default: all; above 50,000, brought down to 50,000)
offsetintegeroptionalInteger ≥ 0, number of points to skip (default: 0)
Examplebash
curl "https://api-runify.domainedunet.fr/tracks/TRACK_ID/points?limit=1000" \
  -H "X-API-Key: YOUR_APP_TOKEN" \
  -H "X-Device-Id: YOUR_DEVICE_ID"
Response 200json
{
  "track_id": "550e8400-e29b-41d4-a716-446655440000",
  "count": 121,
  "points": [
    {
      "latitude": 48.8566,
      "longitude": 2.3522,
      "timestamp": "2026-03-12T09:20:00.000Z",
      "altitude": 35.7,
      "accuracy": 5,
      "speed_mps": 2.1,
      "heading": 180,
      "battery": 0.85
    }
  ]
}

400: limit or offset that is not an integer in the range above. 429 with a Retry-After header beyond 30 reads per minute per device (X-Device-Id header), 300 per minute per IP address.

Error codes

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid token
400BAD_REQUESTInvalid data (Zod validation)
404NOT_FOUNDTrack not found
409CONFLICTdevice_track_id already in use
429RATE_LIMITToo many requests

Quick start

Typical flow to track an activity in real-time:

1

Create the track at start

POST /tracks→ get the id
2

Send points in batches

POST /tracks/:id/points→ every 5–30 seconds
3

Finalize at the end

POST /tracks/:id/finish→ automatically computes stats
💡 Alternative: use POST /sync to send everything in a single request at the end of the session.