Ingest Images

An ingest job copies whole-slide image files from your cloud storage bucket into a Patholytix study. 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 source 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).

Alternatively, pass credentials inline on the request itself — inline credentials are never stored and jobs using them cannot be retried.

Start an ingest job

curl -X POST "https://api.dev2.patholytix.com/api/v1/image/jobs:ingest" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "studyId": "507f1f77bcf86cd799439011",
    "name": "Batch ingest 2026-09-01",
    "source": {
      "bucket": "my-wsi-bucket",
      "prefix": "studies/batch-001/",
      "credentialId": "507f1f77bcf86cd799439022"
    },
    "fileNames": ["slide_001.svs", "slide_002.svs"]
  }'

Omit fileNames to ingest all files under the prefix. Returns 202 Accepted with the job record.

Monitor the job

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

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

PARTIAL means some files succeeded and some failed — check jobStatus.failedFiles and use GET /api/v1/image/jobs/{jobId}:listFiles to see which.

Stream progress events

For real-time updates, open a Server-Sent Events stream:

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

The stream emits progress events (bytes transferred, speed, ETA) until the job reaches a terminal state, then closes with a complete event.

Retry a failed job

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

Creates a new job from the original specification. Only available for jobs started with a stored credentialId.

Idempotency

Include Idempotency-Key on the request to avoid duplicate jobs when retrying on network failure:

-H "Idempotency-Key: ingest-batch-2026-09-01-001"

Rate limits

A concurrent job limit applies per organisation. 429 Too Many Requests is returned if exceeded — wait for a running job to complete before starting another.

Next steps

• Transfer Images — export study images back to your bucket
• Cloud Image API Reference — full schema and credential configuration