Making requests

All Club API operations use the production base URL:

https://api-gw.uptivo.fit/club

Append the path shown in the API reference to this URL. For example, the public path /Profile becomes https://api-gw.uptivo.fit/club/Profile.

Resource path segments use PascalCase. This includes compound names such as ByEmail, ClientStage, EngagementSummary, and UserSubscriptions. Copy the path spelling from the API reference; do not convert resource names to snake_case or kebab-case. Query parameter names keep the spelling declared by each operation, such as fromId, publishState, and cursor.

Required headers

Every request must send both credentials:

X-Sub-Key: <subscription-key>
Authorization: Bearer <club-api-key>

The Subscription Key identifies the integration. The Club API Key selects the club and determines whether the caller has Read or ReadWrite access. See Authentication for credential handling and failure cases.

For a request with a JSON body, also send:

Content-Type: application/json

Sending Accept: application/json is recommended but not required.

A complete write request

This example assigns a Subscription to an Athlete. The IDs and credentials are placeholders:

curl --request POST \
  --url https://api-gw.uptivo.fit/club/UserSubscriptions \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "ClassSubscriptionId": 500001,
    "UserId": 300001,
    "From": "2030-09-01T00:00:00+02:00",
    "To": "2030-10-01T00:00:00+02:00",
    "MaxActivities": 8,
    "ClassSubscriptionPlanId": null
  }'

Write operations require a Club API Key with ReadWrite access. Before writing, call GET /Profile and verify that the returned ClubId is the intended club.

Path and query parameters

Path parameters identify a resource and replace the placeholder in the route:

GET /Athletes/{userId}
GET /Athletes/300001

Query parameters follow ? and are separated with &:

GET /Trainings?origin=Club&fromId=1&count=30

Follow these rules:

• use the exact enum spelling shown in the API reference, such as origin=Club;
• send Boolean values as true or false;
• omit an optional parameter when it is not needed instead of sending an empty string;
• percent-encode query values, especially the + sign in timezone offsets;
• respect the minimum, maximum, and default values declared for each operation.

Let curl encode date/time query values safely:

curl --get \
  --url https://api-gw.uptivo.fit/club/Trainings \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data-urlencode "origin=Club" \
  --data-urlencode "from=2030-09-01T08:00:00+02:00" \
  --data-urlencode "to=2030-09-01T12:00:00+02:00" \
  --data-urlencode "count=30"

Without URL encoding, +02:00 may be interpreted as a space and rejected.

JSON conventions

The public JSON contract uses PascalCase property names. Copy names from the schema rather than deriving them from the naming conventions of your language:

{
  "UserId": 300001,
  "PaymentMode": "Subscription",
  "Trial": false
}

Enums are JSON strings, not their internal numeric values. Enum spelling is exact: for example, use "ReadWrite", "InSite", or "Published" when that value is allowed by the operation.

Send valid JSON without comments or trailing commas. JSON numbers must not be quoted, and Boolean and null values are lowercase: true, false, and null.

Required, optional, and nullable are different

The API reference describes each property independently:

• required means the property must be present;
• optional means the property may be omitted;
• nullable means the property may explicitly contain null.

Do not assume that omission and null have the same effect. This is especially important for update operations, where omission may mean “leave unchanged.” Only send properties whose intended value is known.

Some response properties are omitted when they do not apply or when the corresponding expansion option was not requested. Consumers must tolerate both an absent optional property and an explicitly nullable value where the schema permits them.

Dates and times

Use ISO 8601 date/time values with either Z or an explicit UTC offset:

2030-09-04T08:15:30Z
2030-09-04T10:15:30+02:00

These examples represent the same instant. Use Z for UTC values, especially properties whose names end in Utc or UTC. Use the correct local offset when expressing a club-local schedule.

The TimeZoneCode returned by GET /Profile, for example Europe/Rome, is the club’s timezone. Use a timezone-aware library and that code when converting local schedules. Do not permanently store a fixed offset such as +01:00, because daylight-saving transitions can change the applicable offset.

DateFormat and TimeFormat in the club profile are display preferences. They do not replace ISO 8601 in API requests.

Range boundaries

ID boundaries are inclusive. Training and telemetry time boundaries are also inclusive. Calendar ranges are half-open: from is included and to is excluded. When both ends are supplied, from must be earlier than to, and fromId must not be greater than toId.

• Training ranges may be open-ended. Use either the ID range or the date/time range; combining both produces 400 Bad Request.
• Calendar requests can use ID bounds or open-ended date bounds. A finite calendar window returns Classes whose Begin is in the [from, to) interval.
• Telemetry requests require both from and to and allow at most five hours.

For pagination, repeat the same endpoint and all parameters from the initial request, then pass NextCursor or PrevCursor unchanged through the cursor parameter. Only count may change. See Pagination and synchronization for complete loops, migration from range pagination, checkpoints, and recovery.

Durations

Duration properties such as Duration, Zone1Time, and TargetZoneTime use this format:

0.00:45:00.000

The format is days.hours:minutes:seconds.fraction; it is a duration, not a time of day or an ISO 8601 timestamp.

Units

The API uses canonical units even when the club profile has a different UnitsSystem display preference.

Field or value	Unit
Athlete Weight	kilograms
Athlete Height	centimeters
Training and geolocation Distance	meters
Training speed fields	kilometers per hour
Heart-rate values	beats per minute (bpm)
Power values	watts
Cadence values	revolutions per minute (rpm)
Latitude and longitude	decimal degrees
Geolocation altitude	meters
Telemetry timestamps	Unix epoch milliseconds in UTC
Subscription-plan Amount	smallest currency unit

For money, use UnitMultiplier to convert an integer Amount to the currency’s major unit. For example, an Amount of 12000 with a UnitMultiplier of 100 represents 120.00 in the currency identified by Currency.

Credits, tickets, activity limits, and booking limits are integer counts, not monetary amounts.

Handle the response

Validate the HTTP status before deserializing the success schema. Error bodies are not uniform across all status codes, so use Errors to decide whether to fix the request, replace credentials, or retry safely.

Clients should ignore unknown response properties. This keeps integrations compatible when Uptivo adds non-breaking fields to an existing response.