---
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: when source_pitch_id is present, pitch_uuid is derived from the
player, session, and source_pitch_id only; pitch_index is a display sequence.
The default sync_mode=snapshot removes pitches/frames omitted from a re-upload.

## Headers

- `x-api-key` string, required — Required API key issued by Preciser.
- `League` string, required — Required tenant/database selector, for example pitchbio-master.

## 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 — Stable physical-pitch identifier used for updates and retries.
      - `pitch_index` integer, required — Display sequence within the session. It is not part of the identity when source_pitch_id is provided.
      - `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
  - `sync_mode` 'snapshot' | 'upsert' — snapshot treats every submitted session as complete and removes omitted pitches/frames. upsert keeps omitted rows.

## 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.dev/preciser/apis/preciser-data-management-api.md) · [All operations](https://skmtc.dev/preciser/apis/preciser-data-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/preciser/preciser-data-management-api/revisions/9b0abde08b06/schema)