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: /gyms/settings/developer-keys

If you have any questions, please email SugarWOD Support.

A note on nomenclature: Throughout these docs, curly braces {} are used to reflect places where user values should be supplied. Square braces [] are used to reflect optional perameters. E.g. if the docs list the route:/workouts?dates={YYYYMMDD[-YYYYMMDD]}&track_id={TRACK_ID} then /workouts?dates=20190717&track_id=ABCDEFG or /workouts?dates=20190717-20190830&track_id=ABCDEFG are valid routes. No API routes include these characters explicitly.

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:

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:

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:

The best route to get started with is:

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": {
        ...
    }
}

Links

In addition to the links called on by the JSONAPI spec, the API includes two additional types of links. API links and UI links.

API links can be used programmatically, but are more likely useful as a way to explore the provided endpoints in an interactive REST client (such as Postman or Advanced Rest Client).

UI links (property names prefixed with ui_) provide relevant deep-links into the SugarWOD coach's portal, suitable for presenting to end users (registered SugarWOD coaches) for linking through a web browser. These links should be referenced via API data rather than copied, hard coded, or stored locally by another service, to avoid problems if the coach’s portal URL scheme changes in the future.

For example, the /box endpoint offers the following links:

{
    "data": {
        ...
    },
    "links": {
        "self": "https://api.sugarwod.com/v2/box",
        "athletes": "https://api.sugarwod.com/v2/athletes",
        "workouts": "https://api.sugarwod.com/v2/workouts",
        "tracks": "https://api.sugarwod.com/v2/tracks",
        "ui_home": "https://app.sugarwod.com/home"
    }
}

Pagination

Per the JSONAPI spec, paging facilities are provided through the "links" property of the returned data. The API uses a limit and skip based method for paging. These parameters can be sent via GET as elements of the page variable, like so:

Would return the "third" page of Athletes in the Affiliate, and will include the following paging links:

{
    "links": {
        "self": "https://api.sugarwod.com/v2/athletes?page[skip]=100&page[limit]=50",
        "prev": "https://api.sugarwod.com/v2/athletes?page[skip]=50&page[limit]=50",
        "next": "https://api.sugarwod.com/v2/athletes?page[skip]=150&page[limit]=50"
    }
}

The default page length is 25 items. The links property will include a next property unless the remaining number of items is fewer than the requested number. This means a next link may lead to an empty result set in some cases.

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.