Make your product
work with UP.

API Structure


UP API uses the version directly in the URL for each call. Version is not currently required although it may be in the future, so it is recommended that you include it for all calls in your code. If no version is included, currently the UP API will default to v.1.0. See release notes for more details on API updates.

Version Updates:

v.1.1 - current, released 4/2/2014. See Release Notes for more details.

v.1.0 - superseded by v1.1 but still supported. Original public API release.

Format of requests

All GET requests should contain the parameters in the query-string.

Accept Headers

UP API supports responses in JSON, so it expects HTTP requests to have the header:

Accept: application/json

Future implementations may allow other output formats.


For PUT and POST requests, UP API supports either of the following headers:

Content-Type: application/x-www-form-urlencoded
Content-Type: multipart/form-data

Format of responses

API responses have two sections: data and metadata.


The data section will contain objects, which are abstractions of resources in the system. There are two main types of resources: common objects and collections.

  • A common object represents abstractions of the system resources (see Section VI. Object Data Types for a list of Objects).

For example, a common object that represents a User in UP, might look like:

    “xid”: “akj1212d91”,
    “first”: “James”,
    “last”: “Franklin”,
    “image”: “”
  • A Collection provides a list of resources and links to related resources.
Field Name Type Occurs Description
items object[] 1 A list of the resources in the Collection.
size int 1 The size of the elements in the collection.
links dict(rel, URI) 1 Related resources. For each entry in the dictionary, the key names the relationship, e.g. “self”, and the value is the URI of the resource.

For example:

         { ... },
         { ... },
         { ... }
    “size”: 3,
         “next”: “”,
         “prev”: “”,

The API endpoint determines the relationship of the resources “next” and “prev” with the current resource. For example, if the endpoint being queried returns data about the list of workouts, then “next” and “prev” indicate the workouts in that temporal order to the current workout.

Note: each object (users and events) will have a unique ID called a 'XID' that you can use to refer to that object.


The metadata section contains information related to the request itself, and information about the type of data obtained. The metadata is a JSON object with the following fields:

Field Name Type Occurs Description
code int 1 HTTP response code.
message string 1 HTTP response message.
user_xid string 0..1 Encrypted id of the consumer.
error_type string 0..1 Application-specific error type.
error_detail string 0..1 More information about the error, targeted to Developers. For example, a response with code 400 Bad Request might have error_type “param_error”, and the error_detail field could specify which parameter was missing or invalid.
error_user_msg string 0..1 A localized error messages targeted to the end user, when available.

For example:

     “code”: 200,
     “message”: “OK”,
     “user_xid”: “b9yCLa3f01yf”

Complete Response

Finally, all the responses from UP API will combine the data and metadata into the following format:

    “meta”: { ... Response Metadata ... },
    “data”: { ... Resource or Collection ... }

Application Error Codes

In addition to the HTTP response code, in some cases the server may report more detailed application-specific error types and messages to the Developer. These will be included in the “meta” portion of the response in the fields error_type and error_detail. The following error types are reported by the application.

Error Type Details
authentication_error The request requires an authenticated user and no user was logged in.
authorization_error The logged-in user is not authorized to perform the requested operation.
param_error A required parameter was missing or a parameter was malformed. The actual missing or bad parameter will be defined in the error_detail field.
endpoint_error The requested path does not exist.
deprecated Something about this request is using deprecated functionality, or the response format may be about to change.
other Some other type of error occurred.