API documentation

1. Overview

The platform receives whole-slide images (WSI) from outside sources such as the GDC/TCGA archive, GTEx and direct uploads. It files each slide under a controlled vocabulary, checks the file, cuts it into patches, extracts features on GPU servers, and trains or runs diagnosis models on those features.

The API has two audiences:

• Systems that label slides before sending them in. They read the taxonomy (/api/v1/taxonomy…) and use /resolve to check that a label will be accepted.
• GPU workers (RunPod feature-extraction, CLAM training and inference servers). The platform sends them jobs, and they report back through the callback endpoints.

All responses are JSON. Send Accept: application/json so that validation errors come back as JSON instead of a redirect. Timestamps are ISO-8601.

2. Authentication

Every endpoint under /api/v1 requires a server API key. Keys belong to server records (admin → Settings → Servers). Only keys on active servers are accepted. Send the key in either header:

Authorization: Bearer <api_key>
X-API-Key: <api_key>

Keys are compared in constant time. The server that owns the key is recorded against the calls it makes; for example, a feature-extraction report is stamped with the reporting server.

GET /api/health is the only endpoint that works without a key. Use it to test connectivity.

3. The classification tree

Every slide is filed under a three-level tree. The third level can nest further:

Rules the platform enforces

• The leaf rule. A slide must be labelled with the most specific disease available. If a disease has finer diseases under it, it cannot be chosen. Detail that was never captured cannot be recovered later. The error names the choices, for example: "Malignant" is refined further — pick one of: IDC, ILC.
• Organ boundary. A category belongs to one organ. A disease takes its organ_id from its category and never sets it on its own. If a category is moved to another organ, its diseases move with it. The move is refused if the category already has slides, or if one of its disease names already exists in the destination organ.
• Depth limit. Diseases nest at most 5 levels deep, where a root disease is depth 1.
• Deletion guards. The platform refuses to delete an organ, category, disease or stain that slides still use. It also refuses to delete a category that still has diseases, or a disease that still has children.
• Renames carry through. Renaming a disease rewrites the denormalised samples.disease_subtype text on every slide filed under it.
• Inactive rows stay in the tree so that historical slides keep their labels, but they are hidden from pickers. /resolve accepts an inactive row and adds a warning.

Each row has a qualified name that reads as a path, for example Breast › Tumor › Malignant › IDC. The /resolve endpoint returns this path.

4. Organs, categories and diseases (live)

This is the current tree for active organs, generated from the database when the page loads. GET /api/v1/taxonomy returns the same data as JSON. The number after each name is its id, which the API accepts in place of the name.

Organs with no categories yet

These organs exist and can be chosen, but no clinical groups are defined under them yet, so a slide cannot be filed against them until an administrator adds one:

Adrenal gland #18   Bladder #11   Bowel #7   Cervix #15   Eye #23   Head & Neck #16   Kidney #3   Liver #5   Lymph #17   Ovary #13   Pancreas #8   Pleura #22   Skin #9   Soft tissue #21   Stomach #6   Testis #20   Thymus #19   Thyroid #10   Uterus #14

5. Stains

The stain says how the tissue was prepared. It is recorded next to the tree, not inside it. A stain can be matched by id, by abbreviation or by full name, ignoring case. For immunohistochemistry stains, the marker column names the target protein.

Allowed types: routine, special, IHC, ISH, fluorescent, cytology, other. Names and abbreviations are unique.

How a slide's stain is set. A stain chosen at upload is kept. Otherwise:

• Slides from TCGA and GTEx projects are assumed to be H&E during verification.
• If the slide file names a stain, verification reads it with OpenSlide. A stain name the platform has never seen is added automatically as a routine stain, so it should be reviewed afterwards.

6. Scan and processing settings

These settings decide how a slide is processed. They also decide which models can read its features: a model only accepts features made with the same patch size, magnification and feature extractor it was trained on. GET /api/v1/taxonomy/reference returns all three tables below.

Magnifications

Patch sizes

Data sources

7. How incoming slides are classified

Slides enter the platform in several ways. They do not all carry the same information, so the table below shows which part of the classification each one sets. Every path is idempotent: each slide is identified by a natural key, so running an import again updates rows instead of duplicating them.

Linking a slide to its patient case

A slide is linked to its case by the patient barcode. The platform tries entity_submitter_id first, then the file name.

• TCGA: the first three barcode segments name the patient (TCGA-AC-A23C-01Z-00-DX1 → TCGA-AC-A23C).
• GTEx: the first two segments name the donor (GTEX-1117F-0126 → GTEX-1117F).

Linking works in both directions: a case that arrives after its slides picks up those orphan slides. Changing a slide's case, organ, category or disease queues a new verification.

Refining labels from the clinical record

A slide imported with only a coarse label, such as "Malignant", often has its exact diagnosis in the patient's GDC clinical record. php artisan taxonomy:refile-from-clinical moves such slides down to the matching leaf disease. It is a dry run unless --apply is passed. It matches on the ICD-O-3 morphology code, not the free-text diagnosis, because the code is a controlled vocabulary:

A slide is only moved when all of these hold:

• the target disease exists in the slide's own organ and its own category;
• the barcode's sample type is a tumour (01–09), not adjacent normal tissue (10–19). The diagnosis belongs to the patient, not to every slide the patient has;
• the slide currently has no disease, or has a coarser ancestor of the target. A slide already filed under a different leaf is reported as a conflict and never overwritten.

Mixed tumours (8522/3, 8523/3, 8524/3) are distinct entities and need a pathologist's decision, so they are reported and left unchanged.

Verification

Every slide is checked before it can be used. The checks are: can OpenSlide open the file, is the file intact, and can a region be read. The platform also checks that the slide has at least 2 pyramid levels, is at least 1024 px on each side, was scanned at 20× or more, and has a valid microns-per-pixel value. It needs enough tissue (at least 10 % of the area or 50 patches) and a usable label. The clinical fields patient id, case id, project, gender and age at index must be present. A slide is failed if any check fails, needs_clinical_info if only clinical fields are missing, and otherwise passed or pending. Blur, artefact and background scores only produce warnings.

8. Pipeline stages and statuses

A slide can be used for training only when its features are completed, its quality is passed, its verification is passed, and it is marked usable.

Drive paths follow the tree, so files are laid out by source, organ and group:

samples/{source}/{organ}/{category}/{file_id}/{file_name}
sliced_slides/{magnification}/{source}/{organ}/{category}/{case}/sample_{id}_{px}px/patches.tar.gz
features/{model}/{magnification}/{source}/{organ}/{category}/{case}/sample_{id}_{px}px/

9. Endpoint reference

Health

curl https://ai.histopathology.cloud/api/health

{"success":true,"service":"histopathology-management-api","time":"2026-09-24T10:00:00+00:00"}

curl -H "Authorization: Bearer $KEY" https://ai.histopathology.cloud/api/v1/health

{"success":true,"server":"runpod-titan-1","time":"2026-09-24T10:00:00+00:00"}

Taxonomy (read-only)

curl -H "Authorization: Bearer $KEY" "https://ai.histopathology.cloud/api/v1/taxonomy?organ=Breast"

{
  "success": true,
  "levels": ["organ", "category", "disease"],
  "max_disease_depth": 5,
  "organs": [{
    "id": 1, "name": "Breast", "is_active": true,
    "categories": [{
      "id": 4, "label": "Tumor", "is_active": true,
      "diseases": [{
        "id": 7, "name": "Malignant", "depth": 1, "is_leaf": false, "is_active": true,
        "children": [
          {"id": 11, "name": "IDC", "depth": 2, "is_leaf": true, "is_active": true, "children": []},
          {"id": 12, "name": "ILC", "depth": 2, "is_leaf": true, "is_active": true, "children": []}
        ]
      }]
    }]
  }],
  "unrooted_categories": []
}

{"success":true,"organs":[{"id":1,"name":"Breast","is_active":true,"categories_count":2,"diseases_count":3}, …]}

{"success":true,"stains":[{"id":1,"name":"Hematoxylin & Eosin","abbreviation":"H&E","type":"routine",
  "type_label":"Routine","marker":null,"description":"…","is_active":true}, …]}

{"success":true,
 "magnifications":[{"id":2,"label":"x20","value":20,"folder_name":"20x","is_active":true}, …],
 "patch_sizes":[{"id":1,"size_px":224,"overlap_px":0,"wsi_level":0,"label":"224×224 px","ai_model_id":1,"is_active":true}, …],
 "data_sources":[{"id":1,"name":"TCGA-BRCA","full_name":"…","base_url":null,"is_active":true}, …]}

curl -G -H "Authorization: Bearer $KEY" https://ai.histopathology.cloud/api/v1/taxonomy/resolve \
     --data-urlencode organ=Breast --data-urlencode category=Tumor \
     --data-urlencode disease=IDC  --data-urlencode "stain=H&E"

HTTP 200
{
  "success": true,
  "valid": true,
  "classification": {
    "organ":    {"id": 1, "name": "Breast"},
    "category": {"id": 4, "label": "Tumor"},
    "disease":  {"id": 11, "name": "IDC", "parent_id": 7, "depth": 2, "is_leaf": true, "path": ["Malignant", "IDC"]},
    "stain":    {"id": 1, "name": "Hematoxylin & Eosin", "abbreviation": "H&E"}
  },
  "qualified_name": "Breast › Tumor › Malignant › IDC",
  "errors": [],
  "warnings": []
}

GET /api/v1/taxonomy/resolve?organ=Breast&category=Tumor&disease=Malignant

HTTP 422
{"success":true,"valid":false, …,
 "errors":["\"Malignant\" is refined further — pick one of: IDC, ILC."],"warnings":[]}

Feature extraction callbacks

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Accept: application/json" \
  https://ai.histopathology.cloud/api/v1/feature-extraction/report -d '{
    "sample_id": 42, "slide_id": "TCGA-AC-A23C-01Z-00-DX1.svs", "status": "completed",
    "features_gdrive_path": "features/TITAN/20x/TCGA-BRCA/Breast/Tumor/…/sample_42_224px",
    "patch_count": 5312, "failed_patch_count": 0, "model_name": "TITAN", "model_version": "TITAN-v1"
  }'

{"success":true,"message":"Status updated.","sample":{"id":42,"status":"completed"}}

{"success":true,"sample":{"id":42,"slide_id":"TCGA-….svs","feature_extraction_status":"completed",
  "feature_extraction_completed_at":"…","features_gdrive_path":"…","features_gdrive_folder_id":null,
  "features_runpod_path":null,"features_patch_count":5312,"features_failed_patch_count":0,
  "features_model_version":"TITAN-v1","feature_extraction_error":null}}

Training callbacks

{"run_id": 17, "epoch": 3, "total_epochs": 50,
 "metrics": {"train_loss": 0.41, "val_loss": 0.47, "val_auc": 0.91}}

{"run_id": 17, "status": "completed", "metrics": {…},
 "model_path": "training/CLAM/run_17/best_model.pt", "error": null}

Inference callbacks

{"inference_run_id": 5, "stage": "loading_features", "message": "Loading .h5 features from Drive"}

{"inference_run_id": 5, "status": "completed",
 "prediction": {"class_label": "IDC", "class_index": 0, "confidence": 0.923,
                "probabilities": {"0": 0.923, "1": 0.077}},
 "attention_map_path": "inference/results/run_5/attention.png", "error": null}

10. Calls the platform makes to GPU servers

A GPU worker must serve these endpoints. The platform calls them with the worker's own key as the Bearer token. Every worker must answer GET /health without authentication. The platform calls /health before each dispatch: if it is unhealthy, the job is retried after 60 s; if it is unreachable, after 90 s.

Feature extraction worker

POST {worker}/jobs/start
{
  "sample_id": 42,
  "slide_id": "TCGA-AC-A23C-01Z-00-DX1.svs",
  "patch_size_px": 224,
  "magnification": "x20", "magnification_folder": "20x",
  "gdrive_input_path": "sliced_slides/20x/TCGA-BRCA/Breast/Tumor/…/sample_42_224px",
  "gdrive_input_archive": "patches.tar.gz",
  "gdrive_output_path": "features/TITAN/20x/TCGA-BRCA/Breast/Tumor/…/sample_42_224px",
  "ai_model": {"id": 1, "name": "TITAN", "slug": "…", "huggingface": "…", "version": "v1",
               "embedding_dim": "768", "input_resolution": "512x512"},
  "callback": {"url": "https://ai.histopathology.cloud/api/v1/feature-extraction/report", "token": "<api_key>", "method": "POST"},
  "dispatched_at": "2026-09-24T10:00:00+00:00"
}

A 401 or 403 from the worker fails the job at once. A 404 or 5xx is retried.

CLAM training and inference server

This server's /health must report "service":"clam_training". This stops a training run from being sent to a feature-extraction worker.

11. From taxonomy to model classes

A training run turns the tree into class labels, in one of three ways:

A run is limited to one organ: the organ is the scope, the category is the coarse class, and the disease is the fine class. Labels are fixed when the run is dispatched, so editing a slide afterwards cannot change what the model was trained on. Other rules:

• Every slide in the run must use the same feature model, patch size and magnification.
• Slides from one patient never appear in more than one split.
• Every class needs at least one training slide.
• Validation needs at least 2 slides covering at least 2 classes.

Deployed diagnosis models

Before a slide is scored, its features are checked against the model's requirements. If they were made with a different feature extractor, patch size or magnification, or have too few patches, the slide is refused and the reason is given. A model's classes are plain names, for example IDC; they are not linked to disease ids in the tree.

12. Errors and troubleshooting

• You get an HTML page instead of JSON: add Accept: application/json.
• 403 with a key that used to work: the server may have been marked inactive, or its key was rotated in admin → Settings → Servers.
• A slide never moves past needs_clinical_info: import the case's clinical record (GDC clinical JSON or CSV) so that gender and age at index are present.
• A training run is refused for mixed organs: a run covers one organ only. Check that every selected slide's category belongs to the same organ.