SugarWOD API - BETA

The SugarWOD API is currently in the beta test stage. That means you may find bugs. Based on feedback, we may also change the API routes and data formats.

Though the API is in beta, it is deployed to our production infrastructure. You should expect a reliable and performant experience.

Please email any bugs, ideas or questions to SugarWOD Support.

Get Started

By using the SugarWOD API, you agree to SugarWOD's API Terms of Service.

To use this API, you must first generate an API KEY. API KEYs can be created in the SugarWOD portal: https://app.sugarwod.com/affiliate/settings/developer-keys

If you have any questions, please email SugarWOD Support.

Versions

This is version 2 of the SugarWOD API. Once we leave the beta period, there will be no breaking changes to this API. We may enhance or expand the routes or attributes, but we will maintain backwards compatibility. As new versions of the API are released, we may choose to deprecate or retire this version.

All API routes should include the API version you are using, prefixed like this:

https://api.sugarwod.com/v2

Security

API responses are scoped to the Affiliate for which the Authentication token was created.

API requests should only be made server-to-server, and always via HTTPS, to protect Affiliate tokens. You are responsible for all use of your API Key, it should never be embedded in client-side code.

Tokens may be included in a request as either a GET parameter apiKey, or via the Authorization: HTTP header.

For example, include the apiKey as a query parameter:

https://api.sugarwod.com/v2/box?apiKey=YOUR-API-KEY-HERE

Or, include the apiKey in the header:

$ curl -XPUT https://api.sugarwod.com/v2/box \
  -H "Authorization: YOUR-API-KEY-HERE" \
  -H "Content-Type: application/json"

The parameter option may be preferable for quick experimentation with endpoints, but the header method is preferable for production, to avoid apiKeys appearing in any log files.

JSON Format

Except where noted, the data returned from and consumed by the API conforms to the JSONAPI format.

Routes

All API routes in this documentation should be prefixed with:

https://api.sugarwod.com/v2

The best route to get started with is:

/box

Which returns data of type "affiliates" with the basic info about the Affiliate connected by the provided API key. This is a good way to verify the key is properly enabled in SugarWOD, and is for the proper affiliate.

{
    "data": {
        "type": "affiliates",
        "id": "[internal sugarwod affiliate ID]",
        "attributes": {
            "name": "CrossFit Roots",
            "nickname": "Roots",
            "street": "2406 30th St.",
            "city": "Boulder",
            "state": "CO",
            "logo_url": "https://files-sugarwod-com.s3.amazonaws.com/db45b099-c9c2-4152-88cc-71a978cb6b7b-4vMS6B7sWb_icon.png"
        },
        "links": null
    },
    "links": {
        ...
    }
}

Updating

The API allows updating of certain entities in the SugarWOD database, via the HTTP PATCH verb.

Patch data should conform to the JSONAPI spec (i.e. an object with data property containing a type, id and an attributes object). Only certain attributes of each patchable are permitted. See the full documentation for a list of permitted attributes. See the full documentation for a list of permitted patch types and allowed attributes. Patch actions attempting to update any disallowed attributes will fail with an error message, and will not update any records.

PATCH https://api.sugarwod.com/v2/box
Authorization: [YOUR-API-KEY]
Content-Type: application/json
{
    "data": {
        "type": "affiliates",
        "id": "[MUST MATCH ID OF AFFILIATE ATTACHED TO TOKEN]",
        "attributes": {
            "name": "CrossFit Roots",
            "nickname": "Roots",
            "street": "2406 30th Street",
            "city": "Boulder",
            "state": "CO"
        }
    }
}

Patch actions will return the updated object as the response body.

Dates

All dates are returned as UTC timestamps.

Dates that are used to represent an event on a certain date (e.g. the date on which a workout is scheduled) are returned in two ways in attributes. By convention, date attributes that are timestamps have a suffix of "_at", date attributes that are integers have a suffix of "_date_int".

EXAMPLE: A Workout has a "scheduled" date, represented two ways:

scheduled_date_int: As integers in a YYYYMMDD format. For example, a Workout that is scheduled for May 12, 2017 will have a scheduled_date_int of 20170512.

scheduled_at: As timestamp in UTC with time "00:00:00". For example, a Workout that is scheduled for May 12, 2017 will have a scheduled_at of 2017-05-12T00:00:00+00:00.

SugarWOD internally stores "dates without times" as integers in YYYYMMDD format. Both date formats are returned in API responses for convenience.

Rate Limits

Access to this API is rate limited per API Key. When the requests exceed the allowed limit, a 429 "Too Many Requests" response will be returned.

Identifiers

Identifiers for all objects are alphanumeric, case-sensitive strings.

IDs are unique within a model class (e.g. Affiliate, Workout, etc.), but are not guaranteed unique across all classes. For example, it is possible that a Workout and an Athlete could have the same ID. If you need to guarantee uniqueness across the entire system, we recommend that you concatenate the type attribute and the id attribute. For example, "workouts+t2Thdn3Dhr".

Currently, all IDs are 10 characters in length, but this may change in the future.

Affiliates

A box or gym. An authenticated API access token gives the requestor access to a single Affiliate.

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
name string The affiliate's name
nickname string The affiliate's nickname
street string The affiliate's street address
city string The affiliate's city
state_or_province string The affiliate's state or province
postal_code string The affiliate's postal code (zip code in the US)
logo_url string A URL for this affiliate's logo image

Actions

GET /box Returns the Affiliate scoped by the API token.
GET /box/account-owner Returns the Athlete that is the registered owner of this Affiliate's account.
PATCH /box Update the affiliate's basic attributes.

Athletes

A member of an Affiliate. An Athlete has access to the Affiliate's whiteboard, shared workouts, viewing other athletes, announcements, etc. An Athlete can log scores to shared workouts and to their personal logbook.

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
first_name string The athlete's first name
last_name string The athlete's last name
profile_image_url string A URL for this athlete's profile image
email string The email address this athlete used to register
gender string The gender classification used to represent this athlete on the scoreboard. May have the values "male" or "female".
is_coach boolean Will be true if this athlete is designated as a coach in their Affiliate.
is_owner boolean Will be true if this athlete is designated as an owner of their Affiliate. Note that an Affiliate may have many owners, but only one owner will be the account owner.
last_login timestamp The date/time that this athlete last opened the SugarWOD app.

Actions

GET /athletes?role={athlete-role} Returns a list of Athletess in this Affiliate. The role parameter may be used to filter the athletes returned. Valid values are "athletes", "coaches", "owners", "all". This parameter is optional, default is "all".
GET /athletes/{athlete_id} Returns a single Athlete from this Affiliate.
GET /athletes/{athlete_id}/summary/performance Returns a summary of this Athlete's parformance metrics, suitable for embedding in a dashboard. Will include current PRs for 8-12 benchmark workouts and barbell lifts. Not Yet Available
GET /athletes/{athlete_id}/summary/participation Returns a summary of this Athlete's participation metrics, suitable for embedding in a dashboard. Will include current workout, fistbump and comment counts. Not Yet Available
GET /athletes/find?email={athlete@example.com} Finds an Athlete in the Affiliate specified by API KEY with the given email address. Email address must be urlencoded, i.e. athlete+elite@example.com may be searched with parameter email=athlete%2belite@example.com
PATCH /athletes/{athlete_id} Update the athlete's basic attributes.
PATCH /athletes/{athlete_id}/remove Removes this Athlete from this Affiliate, making them an independent athlete. Used when a member leaves a gym. Any data sent will be ignored.
POST /athletes Given an athlete first_name, last_name, gender, email, and optionally a password, will create an Athlete in this Affiliate. If an Athlete with the given email address already exists in SugarWOD, a HTTP 409 response with an error message will be issued. A randomly-assigned password will be set in the response attributes if none is provided. The password will be irretrievable after being displayed this one time.

An optional object attribute notify may specify alerts to be delivered. The only current option is as follows: "notify": {"welcome_athlete": true} to send the new Athlete a welcome email.

Barbell Lifts

A Barbell Lift is a workout template which may be scheduled on an Affiliate's workout calendar, or logged directly by an Athlete in their Personal Logbook.

SugarWOD's library of Barbell Lifts includes dozens of common lifts shared by all affiliates, including Back Squat, Deadlift, Hang Power Clean, etc.

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
name string The barbell lift's name.
category string "clean", "deadlift", ...
movements array An array of Movements contained in this lift.

Actions

GET /barbelllifts/{category} Returns a list of Barbell Lifts in the specified category.
GET /barbell-lifts/{barbelllift_id} Returns a single of Barbell Lift.

Benchmarks

A Benchmark is a workout template which may be scheduled on an Affiliate's workout calendar, or logged directly by an Athlete in their Personal Logbook.

SugarWOD's library of Benchmarks includes 1000s of workouts shared by all affiliates, including the CrossFit Girls, Heroes, Games, etc. Affiliates may also define their own "Gym Benchmarks" via the SugarWOD coach's website.

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
title string The workout's title
description string The workout's description (visible to athletes)
score_type string Valid score_types are "rounds", "reps", "load", "time", and "other".
category string Valid benchmark categories are "girls", "heroes", "games", "gymnastics", "notable", and "custom".
movement_ids array An array of Movements IDs contained in this Benchmark.

Actions

GET /benchmarks/{benchmark_id} Returns a single Benchmark.
GET /benchmarks/category/{category} Returns a list of Benchmarks in the specified category.

Movements

A Movement is an element of a Workout or Benchmark such as "Box Jump", "Back Squat", or "Wall Ball".

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
name string The movement's name.
videos array

Actions

GET /movements Returns a list of all Movements.
GET /movements/{movement_id} Returns a single of Movement.

Tracks

A Track is calendar of Workouts scheduled for a particular group of athletes. Usually corresponds to a program that the Affiliate runs like Workout of the Day, Barbell Club, Competitors, or Oly Lifting.

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
name string The display name for this track
type string "private_group", "public_group", and (future) "individual"

Actions

GET /tracks Returns a list of Tracks in this Affiliate.
POST /tracks Given a name and type, creates and returns a new Track.

Workouts

A workout scheduled by an Affiliate for a particular date and Track. Note, Workouts are scheduled for a date, not by class time.

Attributes

id string The unique identifier
created_at timestamp When this object was created in the system
title string The workout's title
description string The workout's description (visible to athletes)
score_type string "rounds", "reps", "load", "time", or "other"
track Track The track this workout has been scheduled in. See Track for the full spec.
scheduled_date_int integer The date that this workout is scheduled to be performed, in integer format. See notes about dates.
scheduled_at timestamp The date that this workout is scheduled to be performed, in timestamp format. See notes about dates.
movement_ids array An array of Movements IDs contained in this Benchmark.
publish_at timestamp The date/time when this workout becomes visible to Athletes.
is_published boolean True when this workout is visible to Athletes, false otherwise.

Actions

GET /workouts?dates={YYYYMMDD[-YYYYMMDD]}&track_id={TRACK_ID} Retrieve a list of Workouts. Optionally, filter by dates or track_id. Dates can be a singular date_int or a range separated with a hyphen. Default is "today". Note that "today" on our server in the UTC time zone may be different than what you intended. If no track_id is given, defaults to "all".
GET /workouts/{workout_id} Returns a single Workout.
GET /workouts/{workout_id}/athletes Returns a list of Athletes that logged a score for this Workout.

Workouts HQ

This route gives access to the CrossFit HQ mainsite workout programming. This route is an follows exactly the same format as Workout, with the exception that the /athletes is not available for WorkoutsHQ.

SugarWOD is in no way affiliated with CrossFit. We provide this access only as a service to the CrossFit affiliate community.

SugarWOD Mobile Apps

SugarWOD offers native Android and iOS apps to athletes, coaches and box owners. If your gym has a custom app (perhaps from a gym management vendor), you can link directly to and launch our apps.

iOS App Linking

From your iOS app, you can launch the SugarWOD iOS app using a technique called "custom URLs".

Please see this Objective-C code example hosted on GitHub.

Android App Linking

From your Android app, you can launch the SugarWOD Android app by using the Android PackageManager to find the SugarWOD "LAUNCH" Intent.

Please see this Java code example hosted on GitHub.