Transfer Images

A transfer job copies whole-slide image files from a Patholytix study to your cloud storage bucket. The job runs asynchronously — the API returns a jobId immediately and you poll or stream for progress.

Before you start

You'll need a stored cloud credential pointing to your destination bucket. Create one via POST /api/v1/cloud/credentials — see the Cloud Image API Reference for provider-specific configuration examples (AWS S3, GCS, Wasabi, Azure).

Start a transfer job

curl -X POST "https://api.dev2.patholytix.com/api/v1/image/jobs:transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "studyId": "507f1f77bcf86cd799439011",
    "name": "Transfer to GCS 2026-09-01",
    "fileType": "NATIVE",
    "destination": {
      "bucket": "my-transfer-bucket",
      "prefix": "transfers/study-001/",
      "credentialId": "507f1f77bcf86cd799439033"
    }
  }'

fileType controls which slide records are transferred:

• NATIVE — original scanner files
• CONVERTED — derived image files
• BOTH — all files

Returns 202 Accepted with the job record.

Monitor the job

# Get a specific job
curl "https://api.dev2.patholytix.com/api/v1/image/jobs/{jobId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# List all jobs
curl "https://api.dev2.patholytix.com/api/v1/image/jobs?pageNumber=1&pageSize=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

jobStatus.status progresses through: CREATED → IN_PROGRESS → COMPLETED / PARTIAL / FAILED / CANCELLED.

List supports optional status and type filters.

Per-file records

curl "https://api.dev2.patholytix.com/api/v1/image/jobs/{jobId}:listFiles?pageNumber=1&pageSize=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Each record includes the file name, transfer status, and fileChecksum for verification.

Stream progress events

curl "https://api.dev2.patholytix.com/api/v1/image/jobs/{jobId}:streamProgress" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: text/event-stream"

Emits progress events until the job reaches a terminal state, then closes with a complete event.

Cancel a job

curl -X POST "https://api.dev2.patholytix.com/api/v1/image/jobs/{jobId}:cancel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Only possible for jobs in CREATED or IN_PROGRESS state. Files already transferred are left in place at the destination.

Retry a failed job

curl -X POST "https://api.dev2.patholytix.com/api/v1/image/jobs/{jobId}:retry" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Only available for jobs started with a stored credentialId.

Rate limits

A concurrent job limit applies per organisation. 429 Too Many Requests is returned if exceeded.

Next steps

• Ingest Images — bring images into Patholytix from your bucket
• Cloud Image API Reference — full schema and credential configuration