Import status, cancellation, and recovery

The v1 API exposes:

• GET /v1/repositories/{repositoryId}/connections/{connectionId}/imports/{importId}
• POST /v1/repositories/{repositoryId}/connections/{connectionId}/imports/{importId}/cancel
• POST /v1/repositories/{repositoryId}/connections/{connectionId}/imports/{importId}/retry

Repository-bound reads

Send either a Sync-audience human OAuth bearer or a marketplace bot bearer. Reading requires sync:read; cancellation and recovery require sync:resolve. Recovery additionally requires a human OAuth bearer and cannot be authorized by a bot. The connection must belong to the route repository and the import must belong to that connection.

A 404 can mean that the import is missing or that it is not available through the repository in the request. Route identifiers never authorize access.

The status response contains lifecycle state, phase, version, timestamps, bounded progress counters, outage or quarantine guidance, and its canonical resource link. The strong ETag contains the current positive import version. It does not expose credentials or private execution state.

When recoverable is true, recoveryHref identifies the exact recovery operation available for that quarantined import. A false value and null link mean that callers must not infer or attempt recovery.

Idempotent cancellation

Cancellation requires:

• Idempotency-Key: <canonical ULID> for the logical request; and
• If-Match: "<positive decimal version>" copied from the observed strong ETag.

A successful cancellation atomically stops the active import generation. An exact replay returns the same cancelled resource without applying the transition twice.

Conflicts are closed and machine-readable:

Code	Meaning
VERSION_CONFLICT	The observed import version is stale.
IDEMPOTENCY_KEY_REUSED	The key was used already for different input.
IMPORT_NOT_CANCELLABLE	The import is already terminal.

Each conflict includes only the current version, current state, and canonical resource link. Read the current resource before deciding whether to retry; Sync does not silently repeat a stale mutation.

Cancellation stops this import generation. It does not disconnect the GitHub installation, change two-way authority, resolve Git divergence, or remove retained Git/LFS data.

A quarantined import is terminal and cannot be cancelled. Its retained evidence remains available whether or not a human later authorizes recovery.

Human-authorized quarantine recovery

Recovery uses the same Idempotency-Key and If-Match headers as cancellation. It applies only to a quarantined initial import whose retained evidence proves that its bounded automatic recovery attempts are exhausted.

The operation retains the quarantined import and returns a new successor import. The response is 202 when the successor is first accepted and 200 for an exact replay. Sync never reopens or rewrites the failed generation.

Code	Meaning
VERSION_CONFLICT	The observed quarantined import version is stale.
IDEMPOTENCY_KEY_REUSED	The key was used already for different input.
IMPORT_NOT_RECOVERABLE	The retained evidence does not allow a new successor.

Read the returned successor resource to follow progress. Recovery does not choose a winner for a Git divergence or bypass a paused ref.