Back to top

RunScribe API V2

This is the documentation for V2 of the RunScribe API.

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 in
POST/v2/authenticate

Log in to retrieve the authentication token which is used for account-related requests.

  • email (string, required)

  • password (string, required)

Example URI

POST /v2/authenticate
Request
HideShow
Body
{
  "email": "me@example.com",
  "password": "password"
}
Response  200
HideShow
Body
{
  "success": true,
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
  "id": "451"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid credentials."
}

Configuration

Configuration

Retrieve configuration
GET/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

GET /v2/configuration
Response  200
HideShow
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 account
POST/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

POST /v2/account
Request
HideShow
Body
{
  "email": "me@example.com",
  "password": "password",
  "first_name": "New",
  "last_name": "User",
  "accepted_license": "1.0"
}
Response  200
HideShow
Body
{
  "success": true,
  "email": "me@example.com",
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
  "id": "451"
}
Response  422
HideShow
Body
{
  "success": false,
  "errors": {
    "email": [
      "has already been taken"
    ]
  }
}

Retrieve account details
GET/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

GET /v2/account
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
Response  200
HideShow
Body
{
  "success": true,
  "email": "me@example.com",
  "id": "451"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Update account details
PUT/v2/account

Updates the current account details.

  • token (string, required) - authentication token

  • email (string)

  • password (string)

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

PUT /v2/account
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
  "email": "new@example.com",
  "password": "newpassword"
}
Response  200
HideShow
Body
{
  "success": true,
  "email": "new@example.com",
  "token": "da01cd4810dd53a799049cde6aed57b9182e08f47b3bf7050fecf174c2989f10",
  "id": "451"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}
Response  422
HideShow
Body
{
  "success": false,
  "errors": {
    "email": [
      "has already been taken"
    ]
  }
}

Profile

Retrieve profile
GET/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

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

GET /v2/profile
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
Response  200
HideShow
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"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Update profile
PUT/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

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

PUT /v2/profile
Request
HideShow
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"
}
Response  200
HideShow
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"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Firmware

Retrieve firmware info
GET/v2/firmware

Example URI

GET /v2/firmware

Uploads

New Upload

Upload run
POST/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

POST /v2/upload
URI Parameters
HideShow
timestamp
ISO8601 timestamp (optional) Example: 2015-08-13T19:35:12+09:30

run timestamp

delta
signed integer (optional) Example: 15

number of seconds difference between the scribe’s time and the client device

client_time
ISO8601 timestamp (optional) Example: 2015-08-13T19:35:12+09:30

local time of the client

client_type
string (required) Example: ios

client type identifier

client_version
string (required) Example: 1.2.0

client version identifier

runner_id
integer (optional) Example: 123

ID of runner that the run should be assigned to

Response  200
HideShow
Body
{
  "success": true,
  "id": 123,
  "location": "https://api.runscribe.com/v2/uploads/123",
  "crc": 123456
}

Uploads

List uploads
GET/v2/uploads{?ids}

Lists pending uploads or specific uploads by ID.

Example URI

GET /v2/uploads?ids=11,12,13
URI Parameters
HideShow
ids
comma-separated list (optional) Example: 11,12,13

list of upload IDs to query

Response  200
HideShow
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 details
GET/v2/uploads

Example URI

GET /v2/uploads
Response  200
HideShow
Body
{
  "success": true,
  "id": 11,
  "status": "imported",
  "location": "https://api.runscribe.com/runs/123"
}
Response  200
HideShow
Body
{
  "success": true,
  "id": 12,
  "status": "error",
  "error": "File is corrupted"
}
Response  200
HideShow
Body
{
  "success": true,
  "id": 13,
  "status": "pending"
}

Runs

Run

View run details
GET/v2/runs

Example URI

GET /v2/runs

Runs

List runs
GET/v2/runs{?limit,from}

Example URI

GET /v2/runs?limit=25&from=2015-05-10
URI Parameters
HideShow
limit
number (optional) Example: 25

Cap result set at this amount.

from
string (optional) Example: 2015-05-10

Starting date range of runs to fetch.

Request
HideShow
Headers
X-Auth-Token: abc123999
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true,
  "runs": [
    {
      "id": 21028,
      "location": "https://my.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://my.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://my.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://my.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://my.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://my.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"
    }
  ]
}

Scribes

Scribes

List Scribes
GET/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

GET /v2/scribes
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
Response  200
HideShow
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"
    }
  ]
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Create Scribe
POST/v2/scribes

Registers a new Scribe for the current account.

Example URI

POST /v2/scribes
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
  "serial": "8CC7FA44",
  "name": "My Red Scribe",
  "color": "red",
  "foot": "left",
  "placement": "heel",
  "bt_address": "EA:5A:33:73:61:AA"
}
Response  200
HideShow
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"
}
Response  422
HideShow
Body
{
  "success": false,
  "errors": {
    "serial": [
      "has already been taken"
    ]
  }
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Scribe

Update Scribe
PUT/v2/scribes

Updates the given Scribe for the current account.

Example URI

PUT /v2/scribes
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1",
  "serial": "8CC7FA44",
  "color": "black",
  "name": "My Black Scribe",
  "foot": "left",
  "placement": "heel",
  "bt_address": "EA:5A:33:73:61:AA"
}
Response  200
HideShow
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"
}
Response  404
HideShow
Body
{
  "success": false,
  "message": "Invalid Scribe ID"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Delete Scribe
DELETE/v2/scribes

Deletes the given Scribe from the current account.

Example URI

DELETE /v2/scribes
Request
HideShow
Body
{
  "token": "1837fe608f38ba968495e37472c7e29ba5b0e1d6865591fa785801569879e5c1"
}
Response  200
HideShow
Body
{
  "success": true
}
Response  404
HideShow
Body
{
  "success": false,
  "message": "Invalid Scribe ID"
}
Response  401
HideShow
Body
{
  "success": false,
  "message": "Invalid auth token"
}

Statistics

Account stats

Retrieve account stats
GET/v2/account/stats{?from,to}

Retrieves the statistics summary for this user, with an optional time range

Example URI

GET /v2/account/stats?from=2015-05-01&to=2015-05-31
URI Parameters
HideShow
from
string (optional) Example: 2015-05-01
to
string (optional) Example: 2015-05-31
Request
HideShow
Headers
X-Auth-Token: abc123999
Response  200
HideShow
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
  }
}

Generated by aglio on 22 Aug 2018