Data Model

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

Hierarchy

Study
└── Subject
    └── Organ
        └── Slide
            └── Finding

Each level is a distinct resource with its own identifier and set of fields. Slides are ingested by the Patholytix platform and are not yet accessible via the Integration API. Findings are read-only via the Integration API — they are created by pathologists within the Patholytix application.

Study

A Study is the top-level organisational unit. It represents a single pre-clinical or clinical pathology study.

Field	Type	Required	Description
studyId	string	—	System-assigned identifier (read-only)
name	string	Yes	Human-readable study name
description	string	No	Optional free-text description
attributes	object	No	Extensible key-value metadata (see Extensible Attributes)
createdDate	string (ISO 8601)	—	Timestamp of creation (read-only)
updatedDate	string (ISO 8601)	—	Timestamp of last update (read-only)

Required scope: Study:Read to read, Study:Write to create/update, Study:Delete to delete.

Subject

A Subject represents an individual animal or participant within a study.

Field	Type	Required	Description
subjectId	string	—	System-assigned identifier (read-only)
studyId	string	—	Parent study identifier (read-only)
name	string	Yes	Subject identifier — stored as the SUBJID key. Immutable after creation.
attributes	object	No	Extensible key-value metadata
codes	object	—	Filtered view of the study's Codes dictionary — only keys present in this subject's attributes are included
createdDate	string (ISO 8601)	—	Read-only
updatedDate	string (ISO 8601)	—	Read-only

Required scope: Study:Read to read, Study:Write to create/update, Study:Delete to delete.

Delete constraints: A subject cannot be deleted if it has organs or scores registered against it (returns 422).

Organ

An Organ represents a tissue type or anatomical location assessed for a subject.

Field	Type	Required	Description
organId	string	—	System-assigned identifier (read-only)
studyId	string	—	Parent study identifier (read-only)
subjectId	string	—	Parent subject identifier (read-only)
name	string	Yes	Organ specimen name — stored as the MISPEC key. Immutable after creation.
attributes	object	No	Extensible key-value metadata
codes	object	—	Filtered view of the study's Codes dictionary — only keys present in this organ's attributes are included
createdDate	string (ISO 8601)	—	Read-only
updatedDate	string (ISO 8601)	—	Read-only

Required scope: Study:Read to read, Study:Write to create/update, Study:Delete to delete.

Delete constraints: An organ cannot be deleted if it has findings or scores registered against it (returns 422).

Slide

A Slide represents a physical or digital slide image associated with an organ. Slides are ingested by the Patholytix image ingestion pipeline and are not yet accessible via the Integration API — slide read endpoints are planned for a future release.

Finding

A Finding represents a pathologist's observation recorded against a slide. Findings are read-only via the Integration API — they are created by pathologists within the Patholytix application.

Field	Type	Required	Description
findingId	string	—	System-assigned identifier (read-only)
studyId	string	—	Parent study identifier (read-only)
subjectId	string	—	Parent subject identifier (read-only)
organId	string	—	Parent organ identifier (read-only)
slideId	string	—	Parent slide identifier (read-only)
type	string	—	Finding type / classification
severity	string	—	Finding severity grade
createdDate	string (ISO 8601)	—	Read-only

Required scope: Finding:Read to read.

Extensible Attributes

Study, Subject, and Organ resources support an attributes object for storing custom key-value metadata. Values must be strings.

{
  "attributes": {
    "protocol": "GLP-2024-001",
    "sponsor": "Acme Pharma",
    "species": "Rat"
  }
}

Keys and values are free-form strings. The Patholytix platform does not validate or interpret attribute keys — any string key is accepted. Use a consistent naming convention within your organisation.

The following attribute keys are reserved and managed automatically — they cannot be overridden via the API:

Key	Set on	Value
STUDYID	Study	Study name
SUBJID	Subject	Subject name (name field)
MISPEC	Organ	Organ name (name field)

Identifier format

All system-assigned identifiers (studyId, subjectId, etc.) are opaque strings. Treat them as case-sensitive identifiers; do not attempt to parse or infer structure from them.

Next steps

• Codes — define column label dictionaries for a study
• API Reference — full schema definitions for every resource