---
title: "Create mainframe push reservation"
method: POST
path: "/v1/integration/mainframe/projects/{projectId}/pipelines/{pipelineId}/push-reservation"
tags: ["Build and Configure Mainframe Integration Projects"]
---

# Create mainframe push reservation

`POST /v1/integration/mainframe/projects/{projectId}/pipelines/{pipelineId}/push-reservation`

## Request

- Base URL: `https://integration-adapter.connect.cloud.precisely.com`
- URL: `https://integration-adapter.connect.cloud.precisely.com/v1/integration/mainframe/projects/{projectId}/pipelines/{pipelineId}/push-reservation`
- Auth: HTTP bearer

Acquires a distributed reservation required for batched mainframe push requests.
Validates that the client's snapshot baseline matches the remote state.
If drift is detected (canReserve=false), returns conflict details without acquiring a lock.
If baseline matches, reserves exclusive access and returns a reservationId valid for 5 minutes.

**Features:**
- Distributed reservation locking (Redis-backed TTL of 5 minutes)
- Preflight fingerprint validation against the current remote snapshot
- Snapshot drift detection: returns canReserve=false with remote snapshot details on mismatch
- Hidden/system files are excluded from fingerprint evaluation by default (`includeHidden=false`)
- Concurrent push blocking: 409 response if another push already holds the lock
- Atomic check-and-lock pattern: ensures the baseline matches before the reservation is acquired
- Heartbeat extension during multi-batch push (each batch extends TTL)

**Use Cases:**
- Preflight validation before batching multi-file push to remote
- Blocking concurrent push attempts to same pipeline
- Obtaining unique reservationId for multi-phase orchestration
- Detecting stale local snapshot before starting expensive push operations

**Workflow:**
1. Extension computes local snapshot fingerprint
2. POST /push-reservation with fingerprint
3. If canReserve=true: proceed with batched push, use reservationId for each batch
4. If canReserve=false: show snapshot drift with remote files, prompt user for refresh/rebase

**Required Permissions:** `replication-pipeline::create` when permission harmonization is enabled; otherwise, `replication-pipeline::manage`.

## Path parameters

- `projectId` string, required
- `pipelineId` string, required

## Query parameters

- `includeHidden` boolean

## Request body

- MainframePushReservationRequest: Request to acquire a mainframe push reservation. The adapter compares the provided snapshot fingerprint against the current remote snapshot before it attempts to acquire the lock.
  - `expectedSnapshotFingerprint` string, required: Canonical snapshot fingerprint computed by the client from its stored baseline. Algorithm: SHA-256 over sorted tuples of id|fileName|contentHash, joined by newline. Used to detect remote snapshot drift before acquiring the reservation.

## Response `200`

Reservation response (acquired or snapshot drift detected)

- MainframePushReservationResponse: Response returned after acquiring or attempting to acquire a mainframe push reservation. Successful responses include a reservation identifier and expiry timestamp. Drift responses include the latest remote snapshot fingerprint and file snapshot for UI review.
  - `reservationId` string: Reservation identifier that must be sent with each push batch.
  - `expiresAt` string, date-time: Reservation expiry timestamp. Null if reservation was not acquired.
  - `canReserve` boolean: Whether the remote snapshot matches the client baseline.
  - `remoteSnapshotFingerprint` string: Remote snapshot fingerprint currently stored on the adapter side.

## Other responses

- `400`: Bad Request - Invalid request parameters or validation failed: - Missing or empty expectedSnapshotFingerprint - Invalid fingerprint format (must be a 64-character SHA-256 hex string) - Project ID or Pipeline ID mismatch (not found or not associated) - Request body validation failure
- `401`: Unauthorized - Authentication required, valid credentials not provided
- `403`: Forbidden - User lacks the required 'replication-pipeline::create' or legacy 'replication-pipeline::manage' permission
- `404`: Not Found - Project or pipeline does not exist: - Project with given projectId not found - Pipeline with given pipelineId not found in project - Pipeline is not a Mainframe pipeline
- `409`: Conflict - Another push already in progress: - Reservation already held by another user/client - Concurrent push attempt detected
- `500`: Internal Server Error - Reservation acquisition failed: - Remote snapshot fetch failed (network or service issue) - Fingerprint validation failure (remote inconsistency) - Redis cache write failure - Service unavailability

---

[API](https://skmtc.dev/precisely/apis/precisely-integration-adapter-service.md) · [All operations](https://skmtc.dev/precisely/apis/precisely-integration-adapter-service/llms.txt) · [OpenAPI document](https://skmtc.dev/precisely/apis/precisely-integration-adapter-service/revisions/2d2629f4987d?raw)