# Record a weigh-in

`POST https://api.coach-platform.com/api/public/trainees/{traineeId}/body-metrics`

Record a weigh-in for a trainee: weight, body fat, and/or body measurements. This is the only way to write weight through the API, because weight is kept as a dated history rather than a single field: the previous value is moved into the history and the new one becomes current. PATCH /trainees/{traineeId} therefore does NOT accept weight.

Every field is optional, but send at least one. Send only what was actually measured; omitted fields are left untouched, and each measurement field keeps its own dated history. Measurements are in cm, weight in kg, bodyFat in percent.

- Resource: Trainees
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-body-metrics
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `traineeId` | string | Yes |   |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | No | Optional. Send a unique key (e.g. a UUID) to make this POST safe to retry. The same key within 24h returns the original result instead of creating a duplicate. |

## Request body

Content type: `application/json`. Required.

| Field | Type | Required | Description |
|---|---|---|---|
| `weight` | number | No | Body weight in kg. Becomes the current weight; the previous one is pushed onto the weight history. Minimum: `0`. |
| `bodyFat` | number | No | Body fat percentage. Kept as a dated history, exactly like weight. Minimum: `0`. |
| `date` | string | No | ISO date this measurement was taken. Defaults to now. Use it to backfill an earlier weigh-in. |
| `chest` | number | No | chest in cm. Minimum: `0`. |
| `waist` | number | No | waist in cm. Minimum: `0`. |
| `rightArm` | number | No | rightArm in cm. Minimum: `0`. |
| `leftArm` | number | No | leftArm in cm. Minimum: `0`. |
| `rightThigh` | number | No | rightThigh in cm. Minimum: `0`. |
| `leftThigh` | number | No | leftThigh in cm. Minimum: `0`. |
| `rightCalf` | number | No | rightCalf in cm. Minimum: `0`. |
| `leftCalf` | number | No | leftCalf in cm. Minimum: `0`. |
| `neck` | number | No | neck in cm. Minimum: `0`. |
| `butt` | number | No | butt in cm. Minimum: `0`. |
| `navel` | number | No | navel in cm. Minimum: `0`. |
| `lowerAbdomen` | number | No | lowerAbdomen in cm. Minimum: `0`. |
| `upperAbdomen` | number | No | upperAbdomen in cm. Minimum: `0`. |
| `upperHip` | number | No | upperHip in cm. Minimum: `0`. |
| `lowerHip` | number | No | lowerHip in cm. Minimum: `0`. |

## Responses

| Status | Description |
|---|---|
| `201` Created |  |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `404` Not Found |  |
| `409` Conflict |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 201 Created

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object |   |
| `data.traineeId` | string |   |
| `data.date` | string<date-time> |   |
| `data.weight` | number \| null |   |
| `data.bodyFat` | number \| null |   |
| `data.measurements` | object | The measurement fields recorded by this request, in cm. |
| `warnings` | object[] | Non-fatal problems with follow-up writes. The resource was created, but each listed field was not applied. |
| `warnings[].field` | string |   |
| `warnings[].message` | string |   |

Example:

```json
{
  "data": {
    "traineeId": "<string>",
    "date": "<date-time>",
    "weight": 123,
    "bodyFat": 123,
    "measurements": {}
  },
  "warnings": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}
```

### Error responses 400, 401, 403, 404, 409, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request POST \
  --url 'https://api.coach-platform.com/api/public/trainees/<traineeId>/body-metrics' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "weight": 123
}'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/trainees/<traineeId>/body-metrics', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cp_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "weight": 123
  }),
});

const data = await response.json();
```

## Related endpoints

- [List trainees](https://www.coach-platform.com/docs/api/reference/get-trainees/index.md): `GET /api/public/trainees`. List trainees of the coach, filterable by label/search.
- [Create a trainee](https://www.coach-platform.com/docs/api/reference/post-trainees/index.md): `POST /api/public/trainees`. Create a new trainee for the coach.
- [Approve or reject pending trainees](https://www.coach-platform.com/docs/api/reference/post-trainees-pending/index.md): `POST /api/public/trainees/pending`. Approve or reject trainees from the coach's approval queue, which GET /trainees?status=pending lists.
- [Get a trainee](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id/index.md): `GET /api/public/trainees/{traineeId}`. Get a single trainee by id.
- [Update a trainee](https://www.coach-platform.com/docs/api/reference/patch-trainees-trainee-id/index.md): `PATCH /api/public/trainees/{traineeId}`. Update a trainee's personal details.
- [Remove a trainee](https://www.coach-platform.com/docs/api/reference/delete-trainees-trainee-id/index.md): `DELETE /api/public/trainees/{traineeId}`. Remove a trainee from the coach account.
- [Restore an archived trainee](https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-restore/index.md): `POST /api/public/trainees/{traineeId}/restore`. Bring a trainee back from the archive, exactly as the dashboard does it.
- [Send access details to a trainee](https://www.coach-platform.com/docs/api/reference/post-trainees-trainee-id-send-credentials/index.md): `POST /api/public/trainees/{traineeId}/send-credentials`. Send the trainee their app access details by email, and optionally by WhatsApp.
- [Get a trainee's weekly activity](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-weekly-activity/index.md): `GET /api/public/trainees/{traineeId}/weekly-activity`. Day-by-day activity for the week containing the given date (workouts, cardio, nutrition logging, water, measurements, form submissions).
- [Get a trainee's body measurements](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-measurements/index.md): `GET /api/public/trainees/{traineeId}/measurements`. A trainee's body measurements: weight history, body-fat history, circumference history, and custom measurement types.
- [List a trainee's progress photos](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-photos/index.md): `GET /api/public/trainees/{traineeId}/photos`. A trainee's progress photos as temporary viewable image URLs (valid a few minutes).
- [List a trainee's personal records](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-personal-records/index.md): `GET /api/public/trainees/{traineeId}/personal-records`. A trainee's personal records per exercise: best weight, estimated 1RM, top-set reps, max reps, set and total volume, and max duration, each with the value achieved, the previous record and when it was set.
- Previous: [Get a trainee's body measurements](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-measurements/index.md): `GET /api/public/trainees/{traineeId}/measurements`. A trainee's body measurements: weight history, body-fat history, circumference history, and custom measurement types.
- Next: [List a trainee's progress photos](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-photos/index.md): `GET /api/public/trainees/{traineeId}/photos`. A trainee's progress photos as temporary viewable image URLs (valid a few minutes).