Terra Docs
Dashboard
  • Docs
  • API Reference
  • Changelog
  • Health & Fitness API
    • REST API Endpoints
    • Supported integrations
    • Event Types
    • Data models
    • Samples
    • Core concepts
    • Destinations
    • Mobile SDK
      • iOS (Swift)
      • Android (Kotlin)
      • React Native
      • Flutter
  • Streaming API
    • REST API Endpoints
    • Supported Integrations
    • Core Concepts
    • Websocket Reference
    • Mobile SDK
      • iOS (Swift)
      • Android (Kotlin)
      • Flutter
      • React Native
  • Teams API - Beta
    • Supported Integrations
    • Core Concepts
    • API Endpoints
    • Event types
Powered by GitBook
On this page

Was this helpful?

  1. Teams API - Beta

API Endpoints

PreviousCore ConceptsNextEvent types

Was this helpful?

Authentication

Integrations

Coach management

Coach Data retrieval

Athlete Management

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-10T01:07:23.286Z"
    }
  ]
}

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-10T01:07:23.286Z"
  },
  "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-10T01:07:23.286Z",
      "date_of_birth": "2025-05-10",
      "last_updated_at": "2025-05-10T01:07:23.286Z",
      "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-10T01:07:23.286Z"
  },
  "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-10T01:07:23.286Z",
          "date_of_birth": "2025-05-10",
          "last_updated_at": "2025-05-10T01:07:23.286Z",
          "active": true
        }
      ],
      "athlete_participation": {
        "full": [
          "text"
        ],
        "partial": [
          "text"
        ],
        "unknown": [
          "text"
        ]
      },
      "tz_offset_seconds": 1,
      "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-10T01:07:23.286Z"
  },
  "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-10T01:07:23.286Z"
  },
  "data": [
    {
      "test_id": "text",
      "display_name": "text",
      "timestamp_us": 1,
      "test_type": 1,
      "exercise_type": 1,
      "athlete_weight": 1,
      "movement": 1,
      "tz_offset_seconds": 1,
      "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": 1,
          "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-10T01:07:23.286Z",
  "date_of_birth": "2025-05-10",
  "last_updated_at": "2025-05-10T01:07:23.286Z",
  "active": true
}
  • Authentication
  • POSTGenerate an authentication link, using the Terra Authentication Widget
  • Integrations
  • GETGet detailed information about available integrations
  • Coach management
  • GETList all coaches
  • POSTCreate a new coach
  • DELETEDelete a coach
  • Coach Data retrieval
  • GETRetrieve all athletes under a specific coach
  • GETRetrieve all activities recorded by athletes under a specific coach
  • GETRetrieve activity metrics schema for a coach
  • GETRetrieve all tests conducted by athletes under a specific coach
  • Athlete Management
  • GETList all athletes
  • PATCHUpdate an athlete's information
  • PATCHBulk update multiple athletes
  • GETRetrieve a specific athlete by their ID

Generate an authentication link, using the Terra Authentication Widget

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-10T01:07:23.286Z",
  "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-10T01:07:23.286Z"
}

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-10",
  "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-10T01:07:23.286Z",
      "date_of_birth": "2025-05-10",
      "last_updated_at": "2025-05-10T01:07:23.286Z",
      "active": true
    }
  ],
  "errors": [
    {
      "athlete_id": "text",
      "error": "text"
    }
  ]
}