API Endpoints

Generates a link to redirect an end user to for them to select an integration and log in with their fitness data provider

post

/widget/api/session

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

providersstring

Comma separated list of providers to display on the device selection page

Example: VALD,CATAPULT

languagestring

Display language of the widget

Example: en

reference_idstring

Identifier of the end user on your system, such as a user ID or email associated with them

Example: [email protected]

auth_success_redirect_urlstring

URL the user is redirected to upon successful authentication

Example: https://myapp.com/success

auth_failure_redirect_urlstring

URL the user is redirected to upon unsuccessful authentication

Example: https://myapp.com/failure

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://access.tryterra.co/widget/api/session' \
  --header 'dev-id: text' \
  --header 'x-api-key: text' \
  --header 'Content-Type: application/json' \
  --data '{"providers":"VALD,CATAPULT","language":"en","reference_id":"[email protected]","auth_success_redirect_url":"https://myapp.com/success","auth_failure_redirect_url":"https://myapp.com/failure"}'

200

400

403

{
  "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
  "expires_in": 900,
  "status": "success"
}

Returned when authentication link could be successfully generated

Get detailed information about available integrations

Returns detailed information about available providers, including required login fields and logos.

get

/integrations/detailed

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/integrations/detailed'

200

{
  "providers": [
    {
      "provider": "text",
      "name": "text",
      "icon": "text",
      "login_fields": [
        {
          "field": "text",
          "name": "text",
          "type": "text",
          "required": true,
          "options": [
            "text"
          ]
        }
      ],
      "types": {
        "tests": true,
        "activities": true
      }
    }
  ]
}

Integrations retrieved successfully.

List all coaches

get

/coaches

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/coaches' \
  --header 'x-api-key: YOUR_API_KEY'

200

{
  "data": [
    {
      "coach_id": "text",
      "external_coach_id": "text",
      "reference_id": "text",
      "region": "text",
      "provider": "text",
      "created_at": "2025-02-22T15:47:55.400Z",
      "client_id": "text",
      "client_secret": "text",
      "token": "text"
    }
  ]
}

A list of coaches

Create a new coach

Registers a new coach with credentials and integration specifics.

post

/coaches

Authorizations

Body

coach_idstring

Unique identifier for the coach, generated by the server.

external_coach_idstring

Identifier of the coach on the provider's systems

reference_idstring

ID of the coach on your system

regionstring

Region in which the coach operates.

providerstring

Integration provider associated with the coach (e.g., VALD, Catapult).

created_atstring · date-time

The date and time when the coach was registered.

client_idstring

Public identifier for the coach.

client_secretstring

Secret key or token for authentication.

tokenstring

API key or token for the coach object

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/teams/coaches' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

201

400

409

{
  "coach_id": "text",
  "external_coach_id": "text",
  "reference_id": "text",
  "region": "text",
  "provider": "text",
  "created_at": "2025-02-22T15:47:55.400Z",
  "client_id": "text",
  "client_secret": "text",
  "token": "text"
}

Coach created successfully

Delete a coach

Deletes a coach and all associated athletes, activities, and tests.

delete

/coaches/{coachId}

Authorizations

Path parameters

coachIdstringrequired

Unique identifier of the coach to be deleted.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.tryterra.co/v2/teams/coaches/{coachId}' \
  --header 'x-api-key: YOUR_API_KEY'

204

404

No body

Coach deleted successfully.

Retrieve all athletes under a specific coach

get

/coaches/{coachId}/athletes

Authorizations

Path parameters

coachIdstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/coaches/{coachId}/athletes' \
  --header 'x-api-key: YOUR_API_KEY'

200

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-02-22T15:47:55.400Z",
    "client_id": "text",
    "client_secret": "text",
    "token": "text"
  },
  "data": [
    {
      "coach_id": "text",
      "athlete_id": "text",
      "external_athlete_id": "text",
      "reference_id": "text",
      "provider": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "created_at": "2025-02-22T15:47:55.400Z",
      "date_of_birth": "2025-02-22",
      "last_updated_at": "2025-02-22T15:47:55.400Z",
      "active": true
    }
  ]
}

An array of athletes coached by the specified coach

Retrieve all activities recorded by athletes under a specific coach

get

/coaches/{coachId}/activities

Authorizations

Path parameters

coachIdstringrequired

Query parameters

start_timestring · date-time

end_timestring · date-time

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/coaches/{coachId}/activities' \
  --header 'x-api-key: YOUR_API_KEY'

200

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-02-22T15:47:55.400Z",
    "client_id": "text",
    "client_secret": "text",
    "token": "text"
  },
  "data": [
    {
      "activity_id": "text",
      "start_timestamp_us": 1,
      "end_timestamp_us": 1,
      "description": "text",
      "athlete_participation": {
        "full": [],
        "partial": [],
        "unknown": []
      },
      "tz_offset_seconds": 0,
      "teams": [
        {
          "name": "text",
          "is_home": 1
        }
      ],
      "athletes": [
        {
          "coach_id": "text",
          "athlete_id": "text",
          "external_athlete_id": "text",
          "reference_id": "text",
          "provider": "text",
          "first_name": "text",
          "last_name": "text",
          "email": "text",
          "created_at": "2025-02-22T15:47:55.400Z",
          "date_of_birth": "2025-02-22",
          "last_updated_at": "2025-02-22T15:47:55.400Z",
          "active": true
        }
      ],
      "periods": [],
      "activity_metrics": [],
      "events": [
        "text"
      ],
      "athlete_metrics": {}
    }
  ]
}

List of activities within the specified time range for all athletes under the coach

Retrieve activity metrics schema for a coach

Returns the schema of activity metrics available for the specified coach.

get

/coaches/{coachId}/activities/metrics/schema

Authorizations

Path parameters

coachIdstringrequired

Unique identifier of the coach.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/coaches/{coachId}/activities/metrics/schema' \
  --header 'x-api-key: YOUR_API_KEY'

200

404

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-02-22T15:47:55.400Z",
    "client_id": "text",
    "client_secret": "text",
    "token": "text"
  },
  "data": [
    {
      "key": "text",
      "display_name": "text",
      "unit": "text",
      "type": "text",
      "sport": 1
    }
  ]
}

Schema retrieved successfully.

Retrieve all tests conducted by athletes under a specific coach

get

/coaches/{coachId}/tests

Authorizations

Path parameters

coachIdstringrequired

Query parameters

start_timestring · date-time

end_timestring · date-time

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/coaches/{coachId}/tests' \
  --header 'x-api-key: YOUR_API_KEY'

200

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-02-22T15:47:55.400Z",
    "client_id": "text",
    "client_secret": "text",
    "token": "text"
  },
  "data": [
    {
      "test_id": "text",
      "display_name": "text",
      "timestamp_us": 1,
      "test_type": 1,
      "exercise_type": 1,
      "athlete_weight": 1,
      "movement": 1,
      "tz_offset_seconds": 0,
      "category": 1,
      "duration_us": 1,
      "body_region": 1,
      "position": 1,
      "notes": "text",
      "device": "text",
      "test_result_metrics": [
        {
          "side": 1,
          "aspect": 1,
          "statistic_type": 1,
          "metric_type": 1,
          "contraction_type": 1,
          "value": 1
        }
      ],
      "sets": [
        {
          "timestamp_us": 1,
          "duration_us": 1,
          "side": 0,
          "aspect": -1,
          "weight": 1,
          "exercise_name": "text",
          "movement": -1,
          "metrics": [
            {
              "side": 1,
              "aspect": 1,
              "statistic_type": 1,
              "metric_type": 1,
              "contraction_type": 1,
              "value": 1
            }
          ],
          "reps": [
            {
              "offset_us": 1,
              "duration_us": 1,
              "metrics": [
                {
                  "side": 1,
                  "aspect": 1,
                  "statistic_type": 1,
                  "metric_type": 1,
                  "contraction_type": 1,
                  "value": 1
                }
              ]
            }
          ],
          "variations": [
            null
          ]
        }
      ]
    }
  ]
}

List of tests within the specified time range for all athletes under the coach

List all athletes

get

/athletes

Authorizations

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/athletes' \
  --header 'x-api-key: YOUR_API_KEY'

200

type

properties

No body

An array of athletes

Update an athlete's information

patch

/athletes/{athleteId}

Authorizations

Path parameters

athleteIdstringrequired

Body

coach_idstring

The ID of the coach to which the athlete belongs

athlete_idstring

Unique identifier for the athlete, generated by the server.

external_athlete_idstring

Unique identifier for the athlete on the provider's system, generated by the provider (e.g. VALD, Catapult)

reference_idstring

A string to reference the Athlete. This can be a UUID, email, or other, and can be used to reconcile the Athlete with your internal systems.

providerstring

Integration provider associated with the Athlete (e.g., VALD, Catapult).

first_namestring

Athlete's first name.

last_namestring

Athlete's last name

emailstring

Athlete's email

created_atstring · date-time

The date and time when the athlete was registered.

date_of_birthstring · date

The date of birth of the athlete

last_updated_atstring · date-time

The date and time when the athlete was last updated (e.g. updated their first and last name).

activeboolean

Determines whether or not Terra will send webhooks for the given athlete

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.tryterra.co/v2/teams/athletes/{athleteId}' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

200

No body

Athlete updated

Bulk update multiple athletes

Allows a developer to partially update multiple athlete records in a single request.

patch

/athletes

Authorizations

Header parameters

dev-idstringrequired

Your developer ID

Example: testingTerra

x-api-keystringrequired

Your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

dataobject[]required

Array of partial athlete objects for update.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.tryterra.co/v2/teams/athletes' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"data":[{"athlete_id":"text"}]}'

200

207

400

403

{
  "data": [
    {
      "coach_id": "text",
      "athlete_id": "text",
      "external_athlete_id": "text",
      "reference_id": "text",
      "provider": "text",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "created_at": "2025-02-22T15:47:55.400Z",
      "date_of_birth": "2025-02-22",
      "last_updated_at": "2025-02-22T15:47:55.400Z",
      "active": true
    }
  ],
  "errors": [
    {
      "athlete_id": "text",
      "error": "text"
    }
  ]
}

All athlete updates were successful.

Retrieve a specific athlete by their ID

get

/athletes/{athleteId}

Authorizations

Path parameters

athleteIdstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/teams/athletes/{athleteId}' \
  --header 'x-api-key: YOUR_API_KEY'

200

{
  "coach_id": "text",
  "athlete_id": "text",
  "external_athlete_id": "text",
  "reference_id": "text",
  "provider": "text",
  "first_name": "text",
  "last_name": "text",
  "email": "text",
  "created_at": "2025-02-22T15:47:55.400Z",
  "date_of_birth": "2025-02-22",
  "last_updated_at": "2025-02-22T15:47:55.400Z",
  "active": true
}

Detailed information about the athlete

Authentication

Integrations

Coach management

Coach Data retrieval

Athlete Management

Authentication

Integrations

Coach management

Coach Data retrieval

Athlete Management

Generate an authentication link, using the Terra Authentication Widget

Get detailed information about available integrations

List all coaches

Create a new coach

Delete a coach

Retrieve all athletes under a specific coach

Retrieve all activities recorded by athletes under a specific coach

Retrieve activity metrics schema for a coach

Retrieve all tests conducted by athletes under a specific coach

List all athletes

Update an athlete's information

Bulk update multiple athletes

Retrieve a specific athlete by their ID