API Endpoints

Terra Docs

Dashboard

Get detailed information about available integrations

get

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

Responses

200

Integrations retrieved successfully.

application/json

get

GET /v2/teams/integrations/detailed HTTP/1.1
Host: api.tryterra.co
Accept: */*

200

Integrations retrieved successfully.

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

List all coaches

get

Authorizations

Responses

200

A list of coaches

application/json

get

GET /v2/teams/coaches HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

200

A list of coaches

{
  "data": [
    {
      "coach_id": "text",
      "external_coach_id": "text",
      "reference_id": "text",
      "region": "text",
      "provider": "text",
      "created_at": "2025-05-30T04:57:01.915Z"
    }
  ]
}

Delete a coach

delete

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

Authorizations

Path parameters

coachIdstringRequired

Unique identifier of the coach to be deleted.

Responses

204

Coach deleted successfully.

404

Coach not found.

application/json

delete

DELETE /v2/teams/coaches/{coachId} HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

No content

Retrieve all athletes under a specific coach

get

Authorizations

Path parameters

coachIdstringRequired

Responses

200

An array of athletes coached by the specified coach

application/json

Responseall of

get

GET /v2/teams/coaches/{coachId}/athletes HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

200

An array of athletes coached by the specified coach

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-05-30T04:57:01.915Z"
  },
  "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-05-30T04:57:01.915Z",
      "date_of_birth": "2025-05-30",
      "last_updated_at": "2025-05-30T04:57:01.915Z",
      "active": true
    }
  ]
}

Retrieve all activities recorded by athletes under a specific coach

get

Authorizations

Path parameters

coachIdstringRequired

Query parameters

start_timestring · date-timeOptional

end_timestring · date-timeOptional

Responses

200

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

application/json

Responseall of

get

GET /v2/teams/coaches/{coachId}/activities HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

200

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

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-05-30T04:57:01.915Z"
  },
  "data": [
    {
      "activity_id": "text",
      "start_timestamp_us": 1,
      "end_timestamp_us": 1,
      "description": "text",
      "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-05-30T04:57:01.915Z",
          "date_of_birth": "2025-05-30",
          "last_updated_at": "2025-05-30T04:57:01.915Z",
          "active": true
        }
      ],
      "athlete_participation": {
        "full": [
          "text"
        ],
        "partial": [
          "text"
        ],
        "unknown": [
          "text"
        ]
      },
      "tz_offset_seconds": 0,
      "periods": [
        {
          "period_id": "text",
          "name": "text",
          "athlete_participation": {
            "full": [
              "text"
            ],
            "partial": [
              "text"
            ],
            "unknown": [
              "text"
            ]
          },
          "detailed_athlete_participation": [
            {
              "athlete_id": "text",
              "external_athlete_id": "text",
              "is_home_team": 1,
              "participation": 1,
              "function": "text"
            }
          ],
          "start_timestamp_us": 1,
          "end_timestamp_us": 1,
          "athlete_metrics": [
            {
              "athlete_id": "text",
              "metrics": [
                {
                  "name": "text",
                  "value": 1,
                  "unit": "text"
                }
              ]
            }
          ]
        }
      ],
      "activity_metrics": [
        {
          "name": "text",
          "value": 1,
          "unit": "text"
        }
      ],
      "athlete_metrics": {
        "ANY_ADDITIONAL_PROPERTY": [
          {
            "name": "text",
            "value": 1,
            "unit": "text"
          }
        ]
      },
      "events": [
        "text"
      ]
    }
  ]
}

Retrieve activity metrics schema for a coach

get

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

Authorizations

Path parameters

coachIdstringRequired

Unique identifier of the coach.

Responses

200

Schema retrieved successfully.

application/json

Responseall of

404

Coach not found.

application/json

get

GET /v2/teams/coaches/{coachId}/activities/metrics/schema HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-05-30T04:57:01.915Z"
  },
  "data": [
    {
      "key": "text",
      "display_name": "text",
      "unit": "text",
      "type": "text",
      "sport": 1
    }
  ]
}

Retrieve all tests conducted by athletes under a specific coach

get

Authorizations

Path parameters

coachIdstringRequired

Query parameters

start_timestring · date-timeOptional

end_timestring · date-timeOptional

Responses

200

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

application/json

Responseall of

get

GET /v2/teams/coaches/{coachId}/tests HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

200

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

{
  "coach": {
    "coach_id": "text",
    "external_coach_id": "text",
    "reference_id": "text",
    "region": "text",
    "provider": "text",
    "created_at": "2025-05-30T04:57:01.915Z"
  },
  "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": [
        {
          "metrics": [
            {
              "side": 1,
              "aspect": 1,
              "statistic_type": 1,
              "metric_type": 1,
              "contraction_type": 1,
              "value": 1
            }
          ],
          "timestamp_us": 1,
          "duration_us": 1,
          "side": 0,
          "aspect": -1,
          "reps": [
            {
              "offset_us": 1,
              "duration_us": 1,
              "metrics": [
                {
                  "side": 1,
                  "aspect": 1,
                  "statistic_type": 1,
                  "metric_type": 1,
                  "contraction_type": 1,
                  "value": 1
                }
              ]
            }
          ],
          "weight": 1,
          "exercise_name": "text",
          "variations": [
            null
          ],
          "movement": -1
        }
      ]
    }
  ]
}

List all athletes

get

Authorizations

Responses

200

An array of athletes

get

GET /v2/teams/athletes HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

200

An array of athletes

No content

Retrieve a specific athlete by their ID

get

Authorizations

Path parameters

athleteIdstringRequired

Responses

200

Detailed information about the athlete

application/json

get

GET /v2/teams/athletes/{athleteId} HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

200

Detailed information about the athlete

{
  "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-05-30T04:57:01.915Z",
  "date_of_birth": "2025-05-30",
  "last_updated_at": "2025-05-30T04:57:01.915Z",
  "active": true
}

post

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

Header parameters

dev-idstringRequired

your developer ID

Example: testingTerra

x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

providersstringOptional

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

Example: VALD,CATAPULT

languagestringOptional

Display language of the widget

Example: en

reference_idstringOptional

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

Example: [email protected]

auth_success_redirect_urlstringOptional

URL the user is redirected to upon successful authentication

Example: https://myapp.com/success

auth_failure_redirect_urlstringOptional

URL the user is redirected to upon unsuccessful authentication

Example: https://myapp.com/failure

Responses

200

Returned when authentication link could be successfully generated

application/json

400

Returned when one or more parameters is malformed - an appropriate error message will be returned

application/json

403

Returned when credentials (dev ID and API key) are invalid

application/json

post

POST /widget/api/session HTTP/1.1
Host: access.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 192

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

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

Create a new coach

post

Registers a new coach with credentials and integration specifics.

Authorizations

Body

coach_idstringRead-onlyOptional

Unique identifier for the coach, generated by the server.

external_coach_idstringRead-onlyOptional

Identifier of the coach on the provider's systems

reference_idstringOptional

ID of the coach on your system

regionstringOptional

Region in which the coach operates.

providerstringOptional

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

created_atstring · date-timeOptional

The date and time when the coach was registered.

client_idstringWrite-onlyOptional

Public identifier for the coach.

client_secretstringWrite-onlyOptional

Secret key or token for authentication.

tokenstringWrite-onlyOptional

API key or token for the coach object

Responses

201

Coach created successfully

application/json

400

Invalid input, object invalid

409

The coach already exists for your dev-id

post

POST /v2/teams/coaches HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "reference_id": "text",
  "region": "text",
  "provider": "text",
  "created_at": "2025-05-30T04:57:01.915Z",
  "client_id": "text",
  "client_secret": "text",
  "token": "text"
}

{
  "coach_id": "text",
  "external_coach_id": "text",
  "reference_id": "text",
  "region": "text",
  "provider": "text",
  "created_at": "2025-05-30T04:57:01.915Z"
}

Update an athlete's information

patch

Authorizations

Path parameters

athleteIdstringRequired

Body

coach_idstringRead-onlyOptional

The ID of the coach to which the athlete belongs

athlete_idstringRead-onlyOptional

Unique identifier for the athlete, generated by the server.

external_athlete_idstringRead-onlyOptional

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

reference_idstringOptional

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.

providerstringRead-onlyOptional

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

first_namestringOptional

Athlete's first name.

last_namestringOptional

Athlete's last name

emailstringOptional

Athlete's email

created_atstring · date-timeRead-onlyOptional

The date and time when the athlete was registered.

date_of_birthstring · dateOptional

The date of birth of the athlete

last_updated_atstring · date-timeRead-onlyOptional

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

activebooleanOptional

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

Responses

200

Athlete updated

patch

PATCH /v2/teams/athletes/{athleteId} HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "reference_id": "text",
  "first_name": "text",
  "last_name": "text",
  "email": "text",
  "date_of_birth": "2025-05-30",
  "active": true
}

200

Athlete updated

No content

Bulk update multiple athletes

patch

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

Authorizations

Header parameters

dev-idstringRequired

Your developer ID

Example: testingTerra

x-api-keystringRequired

Your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

Responses

200

All athlete updates were successful.

application/json

207

Partial success, some athletes updated while others failed.

application/json

400

Bad Request. Invalid input or all updates failed due to validation errors.

application/json

403

Unauthorized. Invalid credentials provided.

application/json

patch

PATCH /v2/teams/athletes HTTP/1.1
Host: api.tryterra.co
x-api-key: text
dev-id: text
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "data": [
    {
      "athlete_id": "text",
      "active": true,
      "reference_id": "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-05-30T04:57:01.915Z",
      "date_of_birth": "2025-05-30",
      "last_updated_at": "2025-05-30T04:57:01.915Z",
      "active": true
    }
  ],
  "errors": [
    {
      "athlete_id": "text",
      "error": "text"
    }
  ]
}

Authentication

Integrations

Coach management

Coach Data retrieval

Athlete Management

Authentication

Integrations

Coach management

Coach Data retrieval

Athlete Management

Get detailed information about available integrations

List all coaches

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

Retrieve a specific athlete by their ID

Generate an authentication link, using the Terra Authentication Widget

Create a new coach

Update an athlete's information

Bulk update multiple athletes