RunScribe API V2
This is the documentation for V2 of the RunScribe API.
-
Production: https://api.runscribe.com/
-
Staging: http://newapi.dev.runscribe.com/
POST parameters can be passed either as a JSON object string (application/json)
or as HTML encoded form parameters (application/x-www-form-urlencoded)
. The examples below will use JSON.
For authenticated requests, the authentication token can be passed either as a JSON or form parameter token
, or alternatively using the X-Auth-Token
header.
Authentication ¶
Authenticate ¶
Log inPOST/v2/authenticate
Log in to retrieve the authentication token which is used for account-related requests.
-
email (string, required)
-
password (string, required)
Example URI
Body
{
"email": "me@example.com",
"password": "password"
}
200
Body
{
"success": true,
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
"id": "451"
}
401
Body
{
"success": false,
"message": "Invalid credentials."
}
Configuration ¶
Configuration ¶
Retrieve configurationGET/v2/configuration
Fetch the configuration parameters defined within the RunScribe admin. If an authentication token is provided, then parameters marked as ‘authenticated’ will be returned. However this is not required.
All keys and values are returned as strings. It is up to the administrator and API client to ensure that values are valid and cast to the appropriate type.
Example URI
200
Body
{
"success": true,
"device_recording_timeout": "250",
"low_voltage_threshold_cr2032": "2600",
"low_voltage_threshold_rechargeable": "3600",
"min_voltage_erase_rechargeable": "3500",
"show_warning_on_upload_error": "yes",
"min_voltage_erase_cr2032": "2500"
}
Account and Profile ¶
Account ¶
Create accountPOST/v2/account
New user registration.
-
email (string, required)
-
password (string, required)
-
first_name (string, required)
-
last_name (string, required)
-
accepted_license (string, optional)
-
clinic_name (string, optional) - will set the account type to “clinician” if provided
-
name (string, DEPRECATED)
Example URI
Body
{
"email": "me@example.com",
"password": "password",
"first_name": "New",
"last_name": "User",
"accepted_license": "1.0"
}
200
Body
{
"success": true,
"email": "me@example.com",
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
"id": "451"
}
422
Body
{
"success": false,
"errors": {
"email": [
"has already been taken"
]
}
}
Retrieve account detailsGET/v2/account
Retrieves the email address for the current account. In future, this may also return additional account-level information (e.g. plan type).
- token (string, required) - authentication token
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
200
Body
{
"success": true,
"email": "me@example.com",
"id": "451",
"type": "clinician",
"permissions": [
"shock_metrics",
"motion_metrics",
"plus_metrics",
"clients"
],
"metrics": [
"stride_pace",
"step_rate",
"stride_length",
"contact_time",
"flight_ratio",
"power",
"shock",
"impact_gs",
"braking_gs",
"footstrike_type",
"pronation_excursion_fs_mp",
"max_pronation_velocity"
],
"run_queue": {
"enabled": true,
"size": 3
}
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Update account detailsPUT/v2/account
Updates the current account details.
-
token (string, required) - authentication token
-
email (string)
-
password (string)
-
run_queue (boolean) - enables or disables the run queue
If the password is updated, then the authentication token may change in which case the new authentication token should be saved for future requests.
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
"email": "new@example.com",
"password": "newpassword"
}
200
Body
{
"success": true,
"email": "new@example.com",
"token": "da01cd4810dd53a799049cde6aed57b9182e08f47b3bf7050fecf174c2989f10",
"id": "451"
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
422
Body
{
"success": false,
"errors": {
"email": [
"has already been taken"
]
}
}
Profile ¶
Retrieve profileGET/v2/profile
Retrieves the profile details for the current account.
- token (string, required) - authentication token
Profile fields:
-
name (string) - user’s full name (combination of first and last names)
-
first_name (string) - user’s first name
-
last_name (string) - user’s last name
-
birthdate (string) - date in YYYY-MM-DD format, null if unset
-
units (string) - “metric” or “imperial”
-
gender (string) - “male” or “female”
-
weight_in_kg (float) - user’s weight in kilograms, null if unset
-
height_in_cm (float) - user’s height in centimetres, null if unset
-
years_running (integer) - number of years user has been running, null if unset
-
stride_rate_threshold (integer) - stride rate startup threshold
-
accepted_license (string) - latest accepted license version
-
client_data_agreement (string) - latest accept client data agreement version
-
scaling_factors (array) - current scaling factor settings for each foot/placement
-
distance_method (integer) - selected firmware distance method for user
-
fit_debug (integer) - current FIT debug level (0: disabled, 1: enabled)
Clinic fields:
-
clinic_name (string) - name of the user’s clinic
-
street (string) - street name and number
-
city (string) - user’s city/locality
-
state (string) - user’s state
-
postal_code (string) - user’s zip/postal code
-
country (string) - 2-letter country code (ISO 3166-1 alpha-2)
-
phone (string) - user’s phone number
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
200
Body
{
"success": true,
"name": "User Name",
"first_name": "User",
"last_name": "Name",
"birthdate": "1985-12-02",
"units": "metric",
"gender": "male",
"weight_in_kg": 88,
"height_in_cm": 182.9,
"years_running": 0,
"stride_rate_threshold": 65,
"accepted_license": "1.0",
"client_data_agreement": "1.0",
"scaling_factors": [
{
"foot": "left",
"placement": "laces",
"value": 0.98605,
"manual": false
},
{
"foot": "right",
"placement": "laces",
"value": 1.345,
"manual": true
},
{
"foot": "left",
"placement": "heel",
"value": 1.468,
"manual": true
},
{
"foot": "right",
"placement": "heel",
"value": 1.234,
"manual": true
}
],
"distance_method": 1,
"fit_debug": 1
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Update profilePUT/v2/profile
Updates the profile for the current account.
- token (string, required) - authentication token
Profile fields:
-
first_name (string) - user’s first name
-
last_name (string) - user’s last name
-
birthdate (string) - date in YYYY-MM-DD format
-
units (string) - “metric” or “imperial”
-
gender (string) - “male” or “female”
-
weight (object) - use key “kg” for metric and “lbs” for imperial
-
height (object) - use key “cm” for metric and keys “feet” and “inches” for imperial
-
weight_in_kg (float) - user’s weight in kilograms
-
height_in_cm (float) - user’s height in centimetres
-
years_running (integer) - number of years user has been running
-
stride_rate_threshold (integer) - stride rate startup threshold
-
accepted_license (string) - latest accepted license version
-
client_data_agreement (string) - latest accept client data agreement version
-
scaling_factors (array) - array of scaling factors to set
-
fit_debug (integer) - current FIT debug level (0: disabled, 1: enabled)
Clinic fields:
-
clinic_name (string) - name of the user’s clinic
-
street (string) - street name and number
-
city (string) - user’s city/locality
-
state (string) - user’s state
-
postal_code (string) - user’s zip/postal code
-
country (string) - 2-letter country code (ISO 3166-1 alpha-2)
-
phone - user’s phone number
Deprecated fields:
- name (string, DEPRECATED) - user name
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
"first_name": "New",
"last_name: "Name",
"gender": "female",
"units": "imperial",
"weight": { "lbs": 201.5 },
"height": { "feet": 6, "inches": 2 },
"accepted_license": "1.1",
"client_data_agreement": "1.0",
"scaling_factors": [
{
"foot": "right",
"placement": "laces",
"value": 1.345
},
{
"foot": "left",
"placement": "heel",
"value": 1.468
},
{
"foot": "right",
"placement": "heel",
"value": null
}
]
}
200
Body
{
"success": true,
"name": "New Name",
"first_name": "New",
"last_name: "Name",
"birthdate": "1985-12-02",
"units": "imperial",
"gender": "female",
"weight_in_kg": 91.398862555,
"height_in_cm": 187.96,
"years_running": 0,
"stride_rate_threshold": 70,
"accepted_license": "1.1",
"client_data_agreement": "1.0",
"scaling_factors": [
{
"foot": "left",
"placement": "laces",
"value": 0.98605,
"manual": false
},
{
"foot": "right",
"placement": "laces",
"value": 1.345,
"manual": true
},
{
"foot": "left",
"placement": "heel",
"value": 1.468,
"manual": true
},
{
"foot": "right",
"placement": "heel",
"value": 1.00011,
"manual": false
}
],
"distance_method": 1,
"fit_debug": 1
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Uploads ¶
New Upload ¶
Upload runPOST/v2/upload
Submits a new FIT file for importing. The FIT file can be passed either as the POST body or as the file
parameter if using a multipart HTTP form request.
The timestamp parameter should be passed as a query string parameter to set the fallback time for the run (in case it has not been set in firmware before running), as well as to pass the timezone offset.
The client_time and delta parameters are used to correct for differences between the scribe and client times, as well as for incorrect times on the client device. The delta (in seconds) will always be added to the timestamp. The difference between the client_time and the server’s current time is added to the timestamp when the difference is greater than 1 minute (any less is considered network latency).
Example URI
- timestamp
ISO8601 timestamp
(optional) Example: 2015-08-13T19:35:12+09:30run timestamp
- delta
signed integer
(optional) Example: 15number of seconds difference between the scribe’s time and the client device
- client_time
ISO8601 timestamp
(optional) Example: 2015-08-13T19:35:12+09:30local time of the client
- client_type
string
(required) Example: iosclient type identifier
- client_version
string
(required) Example: 1.2.0client version identifier
- runner_id
integer
(optional) Example: 123ID of runner that the run should be assigned to
200
Body
{
"success": true,
"id": 123,
"location": "https://api.runscribe.com/v2/uploads/123",
"crc": 123456
}
Uploads ¶
List uploadsGET/v2/uploads{?ids}
Lists pending uploads or specific uploads by ID.
Example URI
- ids
comma-separated list
(optional) Example: 11,12,13list of upload IDs to query
200
Body
{
"success": true,
"uploads": [
{
"id": 11,
"status": "imported",
"location": "https://api.runscribe.com/runs/123"
},
{
"id": 12,
"status": "error",
"error": "File is corrupted"
},
{
"id": 13,
"status": "pending"
}
]
}
Upload ¶
Retrieves the status of a given upload.
View upload detailsGET/v2/uploads/
Example URI
200
Body
{
"success": true,
"id": 11,
"status": "imported",
"location": "https://api.runscribe.com/runs/123"
}
200
Body
{
"success": true,
"id": 12,
"status": "error",
"error": "File is corrupted"
}
200
Body
{
"success": true,
"id": 13,
"status": "pending"
}
Runs ¶
Run ¶
View run detailsGET/v2/runs/{run_id}
Example URI
- run_id
number
(required)Numeric ID of the requested run.
Headers
X-Auth-Token: abc123999
200
Headers
Content-Type: application/json
Body
{
"success": true,
"run": {
"id": 370108,
"location": "https://dashboard.runscribe.com/runs/370108",
"label": "19km",
"timestamp": "2021-08-15T10:26:27.000+09:30",
"distance": 19050,
"steps": 16587,
"time": 5913.554,
"status": "imported",
"calibration": "calibrated",
"terrain_types": [
"Smooth trail",
"Road"
],
"workout_types": [
"Long run"
],
"pain_points": [],
"pain_level": 0,
"exertion_level": 0,
"run_files": [
{
"id": 733999,
"serial": "3D4C4BE0",
"fit": "https://api.runscribe.com/v2/files/733999.fit"
},
{
"id": 733998,
"serial": "A7F1C164",
"fit": "https://api.runscribe.com/v2/files/733998.fit"
},
{
"id": 733997,
"serial": "C2E0EAD7",
"fit": "https://api.runscribe.com/v2/files/733997.fit"
}
],
"mountings": [
{
"position": "left",
"placement": "laces",
"serial": "3D4C4BE0",
"steps": "https://api.runscribe.com/v2/runs/370108/mountings/3D4C4BE0.csv",
"ride": "https://api.runscribe.com/v2/runs/370108/mountings/3D4C4BE0/ride.csv"
},
{
"position": "right",
"placement": "laces",
"serial": "A7F1C164",
"steps": "https://api.runscribe.com/v2/runs/370108/mountings/A7F1C164.csv",
"ride": "https://api.runscribe.com/v2/runs/370108/mountings/A7F1C164/ride.csv"
},
{
"position": null,
"placement": "sacrum",
"serial": "C2E0EAD7",
"steps": "https://api.runscribe.com/v2/runs/370108/mountings/C2E0EAD7.csv",
"ride": "https://api.runscribe.com/v2/runs/370108/mountings/C2E0EAD7/ride.csv"
}
],
"shock_total": 263154.716,
"shock_avg": 15.865,
"power_avg": 0.582,
"grf_vert_peak_avg": 2.706,
"kleg_avg": 8.312,
"kvert_avg": 21.979,
"vo2_avg": 38.098
}
}
Runs ¶
List runsGET/v2/runs{?limit,from}
Example URI
- limit
number
(optional) Example: 25Cap result set at this amount.
- from
string
(optional) Example: 2015-05-10Starting date range of runs to fetch.
Headers
X-Auth-Token: abc123999
200
Headers
Content-Type: application/json
Body
{
"success": true,
"runs": [
{
"id": 21028,
"location": "https://dashboard.runscribe.com/runs/21028",
"label": "Helipad / Hauke Lft",
"timestamp": "2015-08-07T13:29:44.438+00:00",
"distance": 7402.997205994388,
"steps": 6252,
"time": 2379.553,
"status": "imported"
},
{
"id": 20883,
"location": "https://dashboard.runscribe.com/runs/20883",
"label": "Helipad // Haike ++",
"timestamp": "2015-08-05T07:10:02.000-07:00",
"distance": 7402.99720599441,
"steps": 6192,
"time": 2443.364,
"status": "imported"
},
{
"id": 20453,
"location": "https://dashboard.runscribe.com/runs/20453",
"label": "Helipad / Hauke +",
"timestamp": "2015-07-31T07:24:00.000-07:00",
"distance": 7242.062484124934,
"steps": 6430,
"time": 2497.541,
"status": "imported"
},
{
"id": 20454,
"location": "https://dashboard.runscribe.com/runs/20454",
"label": "Helipad / Hauke +",
"timestamp": "2015-07-29T06:12:18.000-07:00",
"distance": 7242.062484124953,
"steps": 6232,
"time": 2458.873,
"status": "imported"
},
{
"id": 19568,
"location": "https://dashboard.runscribe.com/runs/19568",
"label": "Run 23 Jul 2015",
"timestamp": "2015-07-23T06:08:53.000-04:00",
"distance": 6866.800083582151,
"steps": 6514,
"time": 2445.062,
"status": "imported"
},
{
"id": 19570,
"location": "https://dashboard.runscribe.com/runs/19570",
"label": "Run 21 Jul 2015",
"timestamp": "2015-07-21T07:26:37.000-04:00",
"distance": 1289.1324154774459,
"steps": 1224,
"time": 463.764,
"status": "imported"
}
]
}
Metric data ¶
Metric dataGET/v2/runs/{run_id}/metric/{metric}{?units}
Example URI
- run_id
number
(required) Example: 123Numeric ID of the requested run.
- metric
string
(required) Example: stride_pacename of metric. Refer to GET /v2/account for list of accessible metrics.
- units
string
(optional) Example: metricunit system (metric or imperial)
Headers
X-Auth-Token: abc123999
200
Headers
Content-Type: application/json
Body
{
"success": true,
"metric": {
"name": "stride_pace",
"label": "Pace",
"units": "min/km",
"unified": true,
"mountings": [
{
"foot": "left",
"placement": "laces",
"serial": "E84E13E7",
"timestamps": [
0,
771,
...
],
"values": [
1.401,
1.492,
...
]
"average": 2.767,
"units": "m/s"
}
]
}
}
Shoe print data ¶
Shoe print dataGET/v2/runs/{run_id}/shoe_print/{metric}
Returns the point data used to render shoe prints.
Data points are returned as an array of [x, y, v] values where v is the metric value, and are split by running vs walking.
-
Footstrike metrics: shock, max_pronation_velocity, kleg, kvert, grf_vert
-
Toe off metrics: flight_ratio, power, flight_time, grf_horiz, total_force_rate, vo2
Example URI
- run_id
number
(required) Example: 123Numeric ID of the requested run.
- metric
string
(required) Example: shockShoe print metric to render. See footstrike/toe off metrics listed above.
Headers
X-Auth-Token: abc123999
200
Headers
Content-Type: application/json
Body
{
"success": true,
"print": {
"metric": "shock",
"left": {
"running": [
[
-4.21875,
-5.366666666666666,
11.612020486349076
],
[
-8.75,
-80.5,
9.864849040002145
],
...
],
"walking": [
[
1.0625,
16.099999999999998,
0.8096875150762253
],
[
-3.453125,
26.833333333333332,
2.9800617145061987
],
...
]
}
}
}
Shoe ride data ¶
Shoe ride dataGET/v2/runs/{run_id}/shoe_ride
Returns the point data used to render shoe ride prints.
Example URI
- run_id
number
(required) Example: 123Numeric ID of the requested run.
Headers
X-Auth-Token: abc123999
200
Headers
Content-Type: application/json
Body
{
"success": true,
"print": {
"left": {
"running": [
{
"timestamp": 2267.0,
"ride": [
[
null,
null,
0.0
],
[
null,
null,
0.0
],
[
-5.75,
-5.75,
552.0
],
[
-5.5,
-5.5,
618.0
],
...
],
"stride_rate": 79.26023778071334
},
...
],
"walking": [
...
]
}
}
}
Scribes ¶
Scribes ¶
List ScribesGET/v2/scribes
Lists the registered Scribes for the current account.
- token (string, required) - authentication token
Scribe fields:
-
serial (string, required) - serial number in hexadecimal format (must be unique within an account)
-
name (string) - friendly user name for the Scribe
-
color (string) - Scribe color (black, red, blue) - defaults to black
-
foot (string) - left or right
-
placement (string) - heel or laces
-
bt_address (string) - Bluetooth address - e.g. EA:5A:33:73:61:AA
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
200
Body
{
"success": true,
"scribes": [
{
"id": 1,
"serial": "8CC7FA44",
"name": "My Red Scribe",
"color": "red",
"foot": "left",
"placement": "heel",
"bt_address": "EA:5A:33:73:61:AA"
}
]
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Create ScribePOST/v2/scribes
Registers a new Scribe for the current account.
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
"serial": "8CC7FA44",
"name": "My Red Scribe",
"color": "red",
"foot": "left",
"placement": "heel",
"bt_address": "EA:5A:33:73:61:AA"
}
200
Body
{
"success": true,
"id": 1,
"serial": "8CC7FA44",
"name": "My Red Scribe",
"color": "red",
"foot": "left",
"placement": "heel",
"bt_address": "EA:5A:33:73:61:AA"
}
422
Body
{
"success": false,
"errors": {
"serial": [
"has already been taken"
]
}
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Scribe ¶
Update ScribePUT/v2/scribes/
Updates the given Scribe for the current account.
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
"serial": "8CC7FA44",
"color": "black",
"name": "My Black Scribe",
"foot": "left",
"placement": "heel",
"bt_address": "EA:5A:33:73:61:AA"
}
200
Body
{
"success": true,
"id": 1,
"serial": "8CC7FA44",
"name": "My Black Scribe",
"color": "black",
"foot": "left",
"placement": "heel",
"bt_address": "EA:5A:33:73:61:AA"
}
404
Body
{
"success": false,
"message": "Invalid Scribe ID"
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Delete ScribeDELETE/v2/scribes/
Deletes the given Scribe from the current account.
Example URI
Body
{
"token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
200
Body
{
"success": true
}
404
Body
{
"success": false,
"message": "Invalid Scribe ID"
}
401
Body
{
"success": false,
"message": "Invalid auth token"
}
Statistics ¶
Account stats ¶
Retrieve account statsGET/v2/account/stats{?from,to}
Retrieves the statistics summary for this user, with an optional time range
Example URI
- from
string
(optional) Example: 2015-05-01- to
string
(optional) Example: 2015-05-31
Headers
X-Auth-Token: abc123999
200
Headers
Content-Type: application/json
Body
{
"success": true,
"runs": 26,
"distance": 188624.6,
"steps": 182564,
"avgPace": 3.25,
"avgContactTime": 123,
"avgStrideRate": 456,
"mileage": {
"2015-05-18": 225.67,
"2015-05-19": 10473.74,
"2015-05-20": 232.89,
"2015-05-21": 2940.48,
"2015-05-27": 10919.22,
"2015-06-04": 15965.87,
"2015-06-05": 8217.76,
"2015-06-06": 5399.26,
"2015-06-08": 14655.38,
"2015-06-12": 4223.47,
"2015-06-15": 204.55,
"2015-06-18": 5000,
"2015-06-19": 6403.3,
"2015-06-21": 21987.65,
"2015-06-23": 6310,
"2015-06-27": 11212.65,
"2015-06-28": 21957.35,
"2015-06-29": 3231.37,
"2015-07-09": 12824.52,
"2015-07-11": 14395.92,
"2015-07-13": 7932.87,
"2015-07-20": 3910.69
}
}