---
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, nullable
- `League` string, nullable

## Request body

- PitchSessionsRequest
  - `season` string, required — Season label, for example 2026.
  - `seasonType` string — Season type.
  - `gameTier` string — Competition tier.
  - `venue` string — Venue or source label.
  - `velocityUnit` 'kph' | 'mph' — Unit used by velocity fields.
  - `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.
      - `pitchNo` integer, required — Pitch number within the session.
      - `time` string, nullable — Pitch time, for example 00:41 or 00:41:12.
      - `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 — Spin direction, if available.
        - `tiltHhmm` string, nullable — Spin tilt in HH:MM format.
      - `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

---

[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/c5f6b8674011/schema)