Challenges and results

Challenges define time-bounded activity goals or rankings. The Club API provides read-only access to the Challenges available to the selected club and to scored results for its current Athletes.

Choose an operation

Need	API reference
List available Challenges	GET /Challenges
Read one Challenge	GET /Challenges/{challengeId}
List the selected club’s Athlete results	GET /Challenges/{challengeId}/Results
Read one Athlete’s result	GET /Challenges/{challengeId}/Results/{userId}

The route casing is part of the public contract: use /Challenges and /Results exactly as shown.

List available Challenges

Start an ascending scan from the first ID:

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/Challenges?fromId=1&count=100" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The list includes Challenges owned by the selected club, including disabled ones. A brand Challenge is visible only when it is enabled and brand gamification is active. Scheduled templates are excluded; their concrete monthly instances can be returned.

The default page size is 100 and the accepted range is 1 through 1,000. A count outside that range returns 400 Bad Request.

The recommended continuation repeats all parameters from the first request and passes the opaque token unchanged:

GET /Challenges?fromId=1&count=100&cursor=<NextCursor>

NextCursor moves towards larger TrainingChallengeId values and PrevCursor moves towards smaller values. See Pagination and synchronization.

Interpret a Challenge

ClubChallengeDTO includes:

Property	Meaning
TrainingChallengeId	Stable Challenge identifier used in detail and result paths.
OwnerClubId, OwnerBrandId	Nullable owner scope. A Challenge can be owned by a club or brand.
Name, Description, PictureUri	Display content; optional values can be null.
From, To	Optional Challenge interval as ISO 8601 instants.
Enabled	Whether this concrete Challenge is enabled.
Awarded	Whether final award processing has completed, not whether every Athlete earned a medal.
AwardGoals, AwardRanks, AwardGoalsAtEnd	Award-policy settings.
RankingCriteria	Metric used to calculate scores and ranks.
Origin	Training-origin filter applied to the Challenge.
AssignMode	Athletes, Open, or Invite.
Gender	Optional gender eligibility rule.

Immediate goals can award medals before Awarded becomes true. Do not treat that flag or a result row as an award notification. Use the Badge.Awarded webhook for a saved Athlete award. To import or reconcile saved award history, use the Badge awards operations, not the live result ranks.

GET /Challenges/{challengeId} returns 404 Not Found for an inaccessible club or brand Challenge, a personal Challenge, or a scheduled template.

Read results

List the selected club’s current Athlete results:

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/Challenges/900001/Results?fromId=1&count=100" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

Pagination is by UserId, not rank. Repeat the initial parameters and add the opaque token:

GET /Challenges/900001/Results?fromId=1&count=100&cursor=<NextCursor>

The default page size and accepted range are the same as the Challenge list: 100 by default, 1 through 1,000.

Only current, non-demo Athletes of the selected club are returned. However, Rank, RankPrc, and Participants are calculated across all scored participants in the Challenge, which can include Athletes from other clubs of the same brand. Participants is therefore the full Challenge count, not the number of rows in this page or club.

Each TrainingChallengeRankingDTO contains UserId, score and rank fields, workout totals, optional badge image number, Athlete display fields, and club name. Scores and ranks can change while pages are being read; the result set is not a snapshot.

Use GET /Challenges/{challengeId}/Results/{userId} when both identifiers are known. It returns the same envelope with exactly one result and Continue: false. It returns 404 Not Found when the Challenge is inaccessible, the Athlete is outside the selected club or is a demo Athlete, or the Athlete has no scored activity. The API does not invent a zero score or enroll the Athlete.

Synchronization guidance

Challenge and result cursors enumerate the currently visible rows. They do not freeze ranks or provide an update/delete feed. Store results with TrainingChallengeId and UserId as the local identity, upsert idempotently, and refresh live rankings according to the needs of the application. Use Badge.Awarded for actual award changes rather than inferring them from a ranking page.

Reads require Read or ReadWrite access. Missing or invalid credentials return 401; an inactive Club API license or insufficient key permission returns 403.