Skip to content

feat(teams): add operation IDs for integration and coach endpoints #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
12458 merged 5 commits into from
Oct 2, 2025
Merged

feat(teams): add operation IDs for integration and coach endpoints #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a2bba47
feat(teams): add operation IDs for integration and coach endpoints
terra-alex Jul 3, 2025
ced6a98
fix: correct default behavior
terra-alex Jul 24, 2025
cebbbdf
feat(api): add user_id parameter to workout plans endpoint
terra-alex Aug 20, 2025
4c7066c
feat: add biological age
terra-alex Sep 26, 2025
389f376
feat: add biological age property to ScoresData schema and update web…
terra-alex Sep 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions data_models/specs/data_models/common.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,13 @@ model ScoresData {
@minValue(0.0)
@maxValue(100.0)
sleep?: float;


@doc("Biological age computed for the given day.")
@example(27.0)
@minValue(0.0)
@maxValue(100.0)
biological_age?: float;
}

model OxygenData {
Expand Down
7 changes: 7 additions & 0 deletions schemas/ScoresData.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,10 @@ properties:
minimum: 0
maximum: 100
description: Sleep score for the given day, pertaining to the previous night's sleep.
biological_age:
type: number
examples:
- 27
minimum: 0
maximum: 100
description: Biological age computed for the given day.
29 changes: 20 additions & 9 deletions teams.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ paths:
description: indicates that an error happened (value is error)
/integrations/detailed:
get:
operationId: getDetailedIntegrations
summary: Get detailed information about available integrations
description: Returns detailed information about available providers, including required login fields and logos.
security: []
Expand All @@ -111,6 +112,7 @@ paths:
- Integrations
/coaches:
get:
operationId: listCoaches
summary: List all coaches
responses:
'200':
Expand All @@ -122,6 +124,7 @@ paths:
tags:
- Coaches
post:
operationId: createCoach
summary: Create a new coach
description: Registers a new coach with credentials and integration specifics.
requestBody:
Expand All @@ -146,6 +149,7 @@ paths:
/coaches/{coachId}:
delete:
summary: Delete a coach
operationId: deleteCoach
description: Deletes a coach and all associated athletes, activities, and tests.
parameters:
- name: coachId
Expand All @@ -167,6 +171,7 @@ paths:
- Coaches
/coaches/{coachId}/athletes:
get:
operationId: getAthletesForCoach
summary: Retrieve all athletes under a specific coach
parameters:
- name: coachId
Expand All @@ -192,6 +197,7 @@ paths:
- Coaches
/coaches/{coachId}/activities:
get:
operationId: getActivitiesForCoach
summary: Retrieve all activities recorded by athletes under a specific coach
parameters:
- name: coachId
Expand Down Expand Up @@ -229,6 +235,7 @@ paths:
- Coaches
/coaches/{coachId}/activities/metrics/schema:
get:
operationId: getActivityMetricsSchemaForCoach
summary: Retrieve activity metrics schema for a coach
description: Returns the schema of activity metrics available for the specified coach.
parameters:
Expand Down Expand Up @@ -262,6 +269,7 @@ paths:
- Coaches
/coaches/{coachId}/tests:
get:
operationId: getTestsForCoach
summary: Retrieve all tests conducted by athletes under a specific coach
parameters:
- name: coachId
Expand Down Expand Up @@ -299,12 +307,15 @@ paths:
- Coaches
/athletes:
get:
operationId: getAthletes
summary: List all athletes
responses:
'200':
description: An array of athletes
content:
$ref: '#/components/schemas/AthletesReturned'
application/json:
schema:
$ref: '#/components/schemas/AthletesReturned'
tags:
- Athletes
patch:
Expand Down Expand Up @@ -370,6 +381,7 @@ paths:
$ref: '#/components/schemas/ErrorResponse'
/athletes/{athleteId}:
get:
operationId: getAthlete
summary: Retrieve a specific athlete by their ID
parameters:
- name: athleteId
Expand All @@ -387,6 +399,7 @@ paths:
tags:
- Athletes
patch:
operationId: updateAthlete
summary: Update an athlete's information
parameters:
- name: athleteId
Expand Down Expand Up @@ -450,7 +463,7 @@ components:
type: string
description: "Identifier of the coach on the provider's systems"
readOnly: true
reference_id:
reference_id:
type: string
description: "ID of the coach on your system"
region:
Expand Down Expand Up @@ -569,7 +582,6 @@ components:
description: "Indicates if the athlete is from the home team"
participation:
$ref: '#/components/schemas/ParticipationType'
nullable: true
description: "Type of participation in an activity"
function:
type: string
Expand Down Expand Up @@ -805,7 +817,7 @@ components:
movement:
$ref: '#/components/schemas/BiomechanicalMovement'
default: -1

Test:
type: object
properties:
Expand Down Expand Up @@ -908,20 +920,20 @@ components:
type:
type: string
format: uri
examples:
examples:
- "https://api.tryterra.co/probs/not-found"
title:
type: string
examples:
examples:
- "Resource Not Found"
status:
type: integer
format: int32
examples:
examples:
- 404
detail:
type: string
examples:
examples:
- "The coach with the provided ID does not exist."
Comment on lines +923 to 937
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Invalid use of "examples" inside Schema properties; use "example" or components/examples.

In OpenAPI 3.1, Schema Object supports "example" (singular). "examples" here will fail validation in many tools.

Apply this diff:

         type:
           type: string
           format: uri
-          examples:
-            - "https://api.tryterra.co/probs/not-found"
+          example: "https://api.tryterra.co/probs/not-found"
         title:
           type: string
-          examples:
-            - "Resource Not Found"
+          example: "Resource Not Found"
         status:
           type: integer
           format: int32
-          examples:
-            - 404
+          example: 404
         detail:
           type: string
-          examples:
-            - "The coach with the provided ID does not exist."
+          example: "The coach with the provided ID does not exist."

Also ensure your predefined examples are placed under components.examples (not within components.schemas). See related comment below.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
examples:
- "https://api.tryterra.co/probs/not-found"
title:
type: string
examples:
examples:
- "Resource Not Found"
status:
type: integer
format: int32
examples:
examples:
- 404
detail:
type: string
examples:
examples:
- "The coach with the provided ID does not exist."
type:
type: string
format: uri
example: "https://api.tryterra.co/probs/not-found"
title:
type: string
example: "Resource Not Found"
status:
type: integer
format: int32
example: 404
detail:
type: string
example: "The coach with the provided ID does not exist."
🤖 Prompt for AI Agents 
In teams.yml around lines 923-937, the Schema properties incorrectly use the
plural "examples" (OpenAPI 3.1 requires the singular "example") and embed
predefined examples inside schema properties; replace each "examples" with a
single "example" containing the representative value (e.g., example:
"https://api.tryterra.co/probs/not-found", example: "Resource Not Found",
example: 404, example: "The coach with the provided ID does not exist.") and
move any shared/reusable example objects into components.examples (referencing
them from the schema with $ref if needed) so the file validates with OpenAPI
3.1.

instance:
type: string
Expand Down Expand Up @@ -1008,7 +1020,6 @@ components:
description: "Data type of the metric (e.g., integer, float)."
sport:
$ref: '#/components/schemas/Sport'
nullable: true
description: "Sport associated with the metric."
IntegrationsResponse:
type: object
Expand Down
23 changes: 15 additions & 8 deletions v5-bundled.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -353,7 +353,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -514,7 +514,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -604,7 +604,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -892,7 +892,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1003,7 +1003,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1114,7 +1114,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1403,7 +1403,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1486,6 +1486,13 @@ paths:
operationId: PlannedWorkout_Write
description: Used to post workout plans users can follow on their wearable. This can be strength workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)
summary: Post workout plans to a provider
parameters:
- name: user_id
in: query
description: Terra user ID (UUID format) to retrieve data for
schema:
type: string
required: true
requestBody:
content:
application/json:
Expand Down Expand Up @@ -1582,7 +1589,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down
23 changes: 15 additions & 8 deletions v5.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -350,7 +350,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -517,7 +517,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -610,7 +610,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -920,7 +920,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1034,7 +1034,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1148,7 +1148,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1460,7 +1460,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down Expand Up @@ -1546,6 +1546,13 @@ paths:
Used to post workout plans users can follow on their wearable. This can be strength workouts (sets, reps, weight lifted)
or cardio workouts (warmup, intervals of different intensities, cooldown etc)
summary: Post workout plans to a provider
parameters:
- name: user_id
in: query
description: Terra user ID (UUID format) to retrieve data for
schema:
type: string
required: true
requestBody:
content:
application/json:
Expand Down Expand Up @@ -1651,7 +1658,7 @@ paths:
- name: to_webhook
in: query
description: |
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)
schema:
type: boolean
required: false
Expand Down
Loading