Data Model

The Patholytix Integration API is built around a study hierarchy. Understanding this hierarchy is essential for constructing correct requests and interpreting responses.

Each level is a distinct resource with its own identifier. Slides are created by the ingestion pipeline — the API can read, update, and delete them, but not create them. Findings are read-only.

For full field definitions and schema, see the API Reference.

Study

The top-level organisational unit representing a single pathology study.

{
  "studyId": "5ff73eb894507b0001c43d49",
  "studyName": "GLP-2024-001",
  "siteId": "60a1c2d3e4f5a6b7c8d9e0f1",
  "glpStatus": "ACTIVE",
  "studyType": "PRECLINICAL",
  "attributes": {
    "sponsor": "Acme Pharma",
    "species": "Rat"
  },
  "createdDate": "2024-03-01T09:00:00Z",
  "updatedDate": "2024-03-15T14:30:00Z"
}

Subject

An individual animal or participant within a study. Identified by SUBJID — immutable after creation.

{
  "subjectId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "studyId": "5ff73eb894507b0001c43d49",
  "name": "M001",
  "attributes": {
    "sex": "M",
    "doseGroup": "HIGH"
  },
  "createdDate": "2024-03-02T10:00:00Z",
  "updatedDate": "2024-03-02T10:00:00Z"
}

Renaming a subject via PUT cascades the new SUBJID value to all linked organs, slides, and findings.

Organ

A tissue type or anatomical location assessed for a subject. Identified by MISPEC — immutable after creation.

{
  "organId": "75b2c3d4e5f6a7b8c9d0e1f2",
  "studyId": "5ff73eb894507b0001c43d49",
  "subjectId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "name": "Brain",
  "attributes": {
    "weight": "1.42g"
  },
  "createdDate": "2024-03-02T11:00:00Z",
  "updatedDate": "2024-03-02T11:00:00Z"
}

Slide

A digital slide image produced by the ingestion pipeline and associated with a subject and one or more organs.

{
  "slideId": "85c3d4e5f6a7b8c9d0e1f2a3",
  "studyId": "5ff73eb894507b0001c43d49",
  "subjectId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "organIds": ["75b2c3d4e5f6a7b8c9d0e1f2"],
  "file": {
    "fileName": "M001_Brain_001.svs",
    "originalFileName": "M001_Brain_001.svs",
    "fileSizeInBytes": 524288000,
    "fileExtension": "svs",
    "fileType": "CONVERTED"
  },
  "status": "UPLOADED",
  "attributes": {
    "stain": "H&E",
    "block": "A1"
  },
  "createdDate": "2024-03-03T08:00:00Z",
  "updatedDate": "2024-03-03T08:00:00Z"
}

NATIVE and CONVERTED slides

Ingested files can produce two records: a NATIVE record (the original scanner file) and a CONVERTED record (the processed derivative). Attribute filtering, structural assignment, and updates apply to CONVERTED records only. PUT and DELETE against a NATIVE or glass slide return 422.

Finding

A pathologist's observation recorded against a slide. Read-only via the Integration API.

{
  "findingId": "95d4e5f6a7b8c9d0e1f2a3b4",
  "studyId": "5ff73eb894507b0001c43d49",
  "subjectId": "65a1b2c3d4e5f6a7b8c9d0e1",
  "organId": "75b2c3d4e5f6a7b8c9d0e1f2",
  "slideId": "85c3d4e5f6a7b8c9d0e1f2a3",
  "type": "Inflammation",
  "severity": "Minimal",
  "attributes": {
    "distribution": "Focal"
  },
  "createdDate": "2024-03-10T15:00:00Z"
}

Codes

A study-level dictionary that maps attribute keys to human-readable column labels. When present, Study, Subject, Organ, Slide, and Finding responses include a codes object containing only the keys that appear in that record's attributes.

{
  "studyId": "5ff73eb894507b0001c43d49",
  "codes": {
    "sex": "Sex",
    "doseGroup": "Dose Group",
    "stain": "Stain Type"
  }
}

Custom Attributes

Study, Subject, Organ, and Slide resources support an attributes object for key-value metadata. Values must be strings. List endpoints for all these resources accept attributes as a filter parameter using KEY:VALUE syntax.

The following keys are reserved and managed by the platform — values supplied for them in API requests are ignored:

Key	Managed on
`STUDYID`	Study
`SUBJID`	Subject, Slide
`MISPEC`	Organ, Slide
`FILE NAME`, `BLOCKID`	Slide

Study​

Subject​

Organ​

Slide​

NATIVE and CONVERTED slides​

Finding​

Codes​

Custom Attributes​