---
title: "Ingest Pitch Sessions"
method: POST
path: "/api/v1/baseball/pitch-sessions"
tags: ["Baseball Pitch Sessions"]
---

# Ingest Pitch Sessions

`POST /api/v1/baseball/pitch-sessions`

Create or update baseball pitch sessions.

Send one or more pitcher sessions with pitch-level tracking measurements.
Stable source identifiers make retries idempotent. The returned gameId can
be used with schedule and game detail APIs.

## 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

- PitchSessionsRequest
  - `season` string, nullable — Optional season label. When omitted, each session uses the year from scheduledAt or sessionDate, so one request may span calendar years.
  - `seasonType` string — Season type.
  - `gameTier` string — Competition tier.
  - `venue` string — Venue or source label.
  - `velocityUnit` 'kph' | 'mph' — Input unit used by velocity and exitVelocity. Defaults to kph, meaning kilometres per hour (km/h). Preciser tracking responses are also returned in km/h.
  - `syncMode` 'snapshot' | 'upsert' — snapshot treats every submitted session as its complete current state and removes previously stored pitches that are omitted. upsert keeps omitted pitches.
  - `maxExitVelocity` number, nullable — Ignore exit velocity values above this source-unit threshold. Set null to keep all values.
  - `strikeZoneBounds` StrikeZoneBounds
    - `xMin` number, required
    - `xMax` number, required
    - `zMin` number, required
    - `zMax` number, required
  - `sessions` PitchSession[], required — Pitch sessions to create or update.
    - `sourceSessionId` string, nullable — Stable session identifier from your system. Recommended for idempotent retries.
    - `session` string, nullable — Session label shown to users.
    - `sessionDate` string, date, required — Session date.
    - `scheduledAt` string, date-time, nullable — Optional exact session timestamp.
    - `team` PitchTrackingEntity, required
      - `externalId` string, nullable — Stable identifier from your system. If omitted, name is used for matching.
      - `name` string, required — Display name.
      - `color` string, nullable — Optional hex color for team display.
    - `pitcher` PitchTrackingEntity, required
      - `externalId` string, nullable — Stable identifier from your system. If omitted, name is used for matching.
      - `name` string, required — Display name.
      - `color` string, nullable — Optional hex color for team display.
    - `pitches` PitchMeasurement[], required — Pitch measurements in this session.
      - `sourcePitchId` string, nullable — Stable identifier for this physical pitch. Preferred identity for updates and idempotent retries.
      - `pitchNo` integer, required — Display sequence within the session. It is not used as the identity when sourcePitchId, capturedAt, or time is present.
      - `capturedAt` string, date-time, nullable — Exact pitch timestamp. Used for stable matching and chronological order.
      - `time` string, nullable — Local pitch time in HH:MM or HH:MM:SS format. Used for stable matching and chronological order when capturedAt is omitted.
      - `velocity` number, nullable — Pitch velocity in velocityUnit.
      - `exitVelocity` number, nullable — Exit velocity in velocityUnit.
      - `horizontalBreak` number, nullable — Horizontal break from the source system.
      - `verticalBreak` number, nullable — Vertical break from the source system.
      - `strikeZone` StrikeZonePoint
        - `x` number, nullable — Horizontal plate location from the source system.
        - `y` number, nullable — Depth value from the source system.
        - `z` number, nullable — Vertical plate location from the source system.
      - `normalizedPlateX` number, nullable — Optional normalized plate x value from 0 to 1.
      - `normalizedPlateZ` number, nullable — Optional normalized plate z value from 0 to 1.
      - `spin` PitchSpin
        - `total` number, nullable — Spin rate, if available.
        - `direction` string, nullable — Measured spin direction as a clock-face value in H:MM format, for example 12:45.
        - `tiltHhmm` string, nullable — Deprecated alias for direction. Clock-face value in H:MM format, for example 12:45.
      - `pitchType` string, nullable — Pitch type label, if available.
      - `verticalApproachAngle` number, nullable
      - `horizontalApproachAngle` number, nullable
      - `sswVerticalBreak` number, nullable
      - `sswHorizontalBreak` number, nullable
      - `videoUrl` string, nullable — Optional video URL for this pitch.

## Response `200`

Successful Response

- PitchSessionsResponse
  - `success` boolean, required
  - `summary` PitchSessionsSummary, required
    - `sessions` integer, required
    - `pitches` integer, required
    - `teams` integer, required
    - `pitchers` integer, required
  - `items` PitchSessionImportItem[], required
    - `sourceSessionId` string, nullable
    - `gameId` string, required
    - `teamId` string, required
    - `pitcherId` string, required
    - `pitchesAccepted` integer, required
    - `pitchesSkipped` integer, required
  - `warnings` string[]

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-27** `9b0abde08b06` — 4 breaking, 8 info
  - the `header` request parameter `League` became required
  - the `header` request parameter `x-api-key` became required
  - `header` request parameter `League` list-of-types was narrowed by removing types `null`
  - `header` request parameter `x-api-key` list-of-types was narrowed by removing types `null`
  - …8 more

[Change history](https://skmtc.dev/preciser/apis/preciser-data-management-api/changes/api/v1/baseball/pitch-sessions/post.md)

---

[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)