---
title: "Ingest Sessions"
method: POST
path: "/api/v1/biomech/sessions"
tags: ["Biomech"]
---

# Ingest Sessions

`POST /api/v1/biomech/sessions`

Ingest biomech sessions, pitches, and frames.

Idempotency: pitch_uuid is derived server-side from
``uuid5(NAMESPACE_DNS, "{player_id}:{session_id}:{source_pitch_id}:{pitch_index}")``.
Callers MUST send the same ``source_pitch_id`` + ``pitch_index`` for the same
physical pitch on every retry; otherwise a retry inserts a new pitch row
instead of updating the existing one. ``pitch_index`` should be unique within
a session.

## Headers

- `x-api-key` string, nullable
- `League` string, nullable

## Request body

- BiomechSessionsRequest
  - `sessions` BiomechSession[], required
    - `session_id` string, required
    - `player` PlayerRef, required — Reference a player either by canonical player_id or pitchbio alias.
      - `player_id` string, nullable — Canonical player_id
      - `alias` string, nullable — Pitchbio player alias, for example pitcher_001
    - `team_id` string, nullable
    - `session_date` string, date-time, nullable
    - `note` string, nullable
    - `pitches` BiomechPitch[], required
      - `source_pitch_id` string, nullable
      - `pitch_index` integer, required
      - `fp_frame` integer, nullable
      - `mer_frame` integer, nullable
      - `br_frame` integer, nullable
      - `frames` BiomechFrame[], required
        - `frame` integer, required
        - `shoulder_abduction` number, nullable
        - `shoulder_horizontal_abduction` number, nullable
        - `shoulder_external_rotation` number, nullable
        - `elbow_flexion` number, nullable
        - `left_hip_flexion` number, nullable
        - `right_hip_flexion` number, nullable
        - `left_knee_flexion` number, nullable
        - `right_knee_flexion` number, nullable
        - `stride_length` number, nullable
        - `pelvis_rotation` number, nullable
        - `torso_rotation` number, nullable
        - `hip_shoulder_separation` number, nullable
        - `elbow_varus_torque` number, nullable
        - `trunk_anterior_tilt` number, nullable
        - `trunk_lateral_tilt` number, nullable

## Response `200`

Successful Response

- BiomechSessionsResponse
  - `success` boolean, required
  - `sessions_upserted` integer, required
  - `pitches_upserted` integer, required
  - `frames_upserted` integer, required
  - `items` BiomechSessionItemResponse[], required
    - `session_id` string, required
    - `player_id` string, required
    - `pitches` integer, required
    - `frames` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/preciser/apis/preciser-data-management-api.md) · [All operations](https://skmtc.net/preciser/apis/preciser-data-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/preciser/preciser-data-management-api/versions/42cb7b14430f/schema)