histai avatar

cohort-builder

Search pathology cases by diagnosis, organ, age, and stains. Build research cohorts and export WSI data.

version
1.0.0
GitHub stars
7

Install

/plugin install cohort-builder@histai-skillsets

Run it inside Claude Code after adding the marketplace with /plugin marketplace add histai/skillsets.

Contents

Discovered from source

Skills 1

HistAI Pathology Datahub API

Description

This skill provides secure access to the HistAI Datahub, allowing you to search for pathology cases, filter by clinical and technical criteria, buy cohorts, and export whole slide images (WSI) and metadata. This API is designed for building research cohorts and managing data access.


⛔ CRITICAL: This Skill Buys WSI Files — It Is NOT the Path to Train a Model

Read this before doing anything else.

CellDX has two completely independent workflows, each with its own dataset, cost model, and skill:

WorkflowSkillDatasetWhat it costsWhen to use
Buy WSIs (this skill)cohort_builderWhole Slide Images (220K+ slides instantly available, 1M+ via custom request)Per-slide pricing: $5/H&E, $40/IHC (volume discounts apply)User wants to download WSI files for external use, manual review, or their own pipeline
Train a modelai_model_trainerPre-extracted feature vectors (~66K H&E slides only — IHC slides are not in the feature store)GPU compute only ($/GPU-hour, no per-slide fee)User wants to train a classifier on CellDX infrastructure

Rules — apply on every request

  1. Only use this skill when the user explicitly wants to download WSI files (e.g. "buy these slides", "export WSIs", "give me the .svs/.tiff files"). If the user wants to train a model, use the ai_model_trainer skill instead — it reads pre-extracted features and does not require buying WSIs.
  2. Never tell a user that they must purchase a cohort before training. They do not. The trainer's feature store is independent of Datahub cohort ownership.
  3. When the user asks to "train a model on X slides", do NOT estimate cost using this skill's $5 / $40 per-slide table. That pricing applies only to WSI downloads. Training cost = GPU hours only. Route the request to ai_model_trainer.
  4. If the user wants both (download WSIs AND train a model), run the two workflows separately and quote two separate costs. They are not bundled.

Authentication

All requests require an API Key.

export CELLDX_API_KEY="your-api-key"

Include the key in the X-API-KEY header:

X-API-KEY: $CELLDX_API_KEY

Users can generate API keys at Profile and settings → API keys on https://celldx.hist.ai.


Base URL

https://prod.celldx.net

Dataset Schema

The database contains pathology case records. Key fields available for filtering and retrieval include:

Diagnosis & Clinical

FieldTypeDescription
primary_diagnosisstring[]Main diagnosis terms (e.g., "Invasive ductal carcinoma")
cancer_typestring[]Specific cancer subtype
isCancerbooleantrue if malignant, false otherwise
organstring[]Affected organ (e.g., "Breast", "Lung")
organ_systemstring[]System context (e.g., "Gastrointestinal")
agenumberPatient age
gender"m" | "f"Patient gender
icd10stringICD-10 code

Technical & Slides

FieldTypeDescription
stain_namesstring[]Stains present (e.g., "H&E", "ER", "Ki-67")
stain_typesstring[]Stain categories (e.g., "Routine", "IHC")
biopsy_regimenstring[]Procedure type (e.g., "Resection", "Biopsy")
scannersstring[]Scanner devices used
magnificationsnumber[]Available optical magnifications (e.g., 20, 40)

Protocols (Searchable Text)

FieldDescription
macro_protocolMacroscopic description of the specimen
micro_protocolMicroscopic findings and detailed pathology report
conclusionFinal diagnostic conclusion

IHC Studies

Stored as a map of marker names to results (e.g., HER2: "positive 3+"). Use ihc_markers or ihcStudiesContains for filtering.


Billing Endpoints

POST /v1/billing/topup/charge

Instant top-up of credits.

Request Body:

{
  "amountUsd": 1000
}

Export Endpoints

1. Case Search & Discovery

GET /v1/datahub/cases

List cases. Supports pagination parameters: page (default 0) and size (default 100).

POST /v1/datahub/cases/search?page=0&size=20

Search for cases using complex filters. Pagination is handled via query parameters page and size.

Request Body (Filters):

{
  "organ": ["Breast"],
  "isCancer": true,
  "stainName": ["H&E"],
  "ageRange": [40, 60]
}
🔍 Search Strategy: Handling Localization

When a user asks for a diagnosis that includes an organ name (e.g., "Prostate adenocarcinoma"), be aware that the primaryDiagnosis field might only contain the morphology (e.g., "Adenocarcinoma") while the localization is stored in the organ or organSystem fields.

Organ Variability: The organ filter can contain both specific and general terms (e.g., "Left ovary", "Right ovary", "Ovary", and "Ovaries").

Best Practices:

  1. Explore First: Always use /v1/datahub/cases/filters or /v1/datahub/cases/filters/page to see the actual values and counts for the organ and primaryDiagnosis fields.
  2. Breadth Selection: Select all relevant values from the filter results that fit the query. Do not just pick the first match (e.g., select both "Left ovary" and "Ovary" to get all results).
  3. Split Queries: If an initial search for a full compound name returns few results, split the query (Morphology + Organ). Filter by organ (e.g., "Prostate") or organSystem (e.g., "Genitourinary") and combine with a broader search in primaryDiagnosis.
POST /v1/datahub/cases/filters

Get available filter values (facets) and counts matching the current criteria.

POST /v1/datahub/cases/filters/page

Paginate through large lists of filter values (e.g., list all primary diagnoses matching "carcinoma").

GET /v1/datahub/cases/filters/global

Retrieve global, unfiltered lists of available filter options (e.g., all organs in the system).


2. Cohort Management

GET /v1/datahub/cohorts

List all your cohorts.

POST /v1/datahub/cohorts

Create a new cohort.

Request Body:

{
  "name": "My Breast Cancer Cohort",
  "cases": [
    { "caseId": "case_123" },
    { "caseId": "case_456", "slideIds": ["slide_A", "slide_B"] }
  ]
}

Constraints:

  • name: Max 200 chars, cannot be blank.
  • cases: Must not be empty. No duplicate case IDs.
  • slideIds: Optional. If omitted, all slides in the case are included/purchased. If provided, only the specified slides are included. Use this to reduce costs by purchasing only relevant stains (e.g., specific IHCs).
GET /v1/datahub/cohorts/{cohortId}

Get details for a specific cohort.

GET /v1/datahub/cohorts/{cohortId}/status

Check the status of a cohort (PENDING, BUILDING, PAID, UNPAID, FAILED).

POST /v1/datahub/cohorts/{cohortId}/slides

Add slides/cases to an existing cohort.

Request Body:

[
  { "caseId": "case_789" }
]
DELETE /v1/datahub/cohorts/{cohortId}/slides

Remove slides/cases from a cohort.

[!IMPORTANT] Cohort Modification Rules Cohorts can only be modified (adding or removing slides) while their status is UNPAID. Once a cohort is PAID, it is locked and cannot be changed.

[!CAUTION] Financial Risk & Mandatory Confirmation Purchasing a cohort involves real financial transactions and is non-refundable once the status is PAID. AI Agents MUST explicitly confirm the total cost and cohort content with the user and receive a clear "YES" or "PROCEED" before calling this endpoint. Never assume the user wants to pay based on high-level instructions alone.

POST /v1/datahub/cohorts/{cohortId}/pay

Pay for a cohort to enable export. This endpoint is idempotent and requires an Idempotency-Key header.

Headers:

X-API-KEY: $CELLDX_API_KEY
Idempotency-Key: <unique-uuid>

3. Data Export

Export is available only for PAID cohorts.

GET /v1/datahub/cohorts/{cohortId}/export/status

Check if the export package is ready (PREPARING, READY, EXPIRED, FAILED).

GET /v1/datahub/cohorts/{cohortId}/export/manifest

Get the download URLs for the cohort manifest and metadata.

GET /v1/datahub/cohorts/{cohortId}/export/files

List available files for download in the cohort.

GET /v1/datahub/cohorts/{cohortId}/export/files/{fileId}

Get a signed download URL for a specific file (WSI).

POST /v1/datahub/cohorts/{cohortId}/export/refresh

Refresh expired download tokens/links.


4. Billing

GET /v1/billing/balance

Get current account balance and currency.

GET /v1/billing/history

Get transaction history.

GET /v1/billing/payment-methods

List saved payment methods.

POST /v1/billing/topup/charge

Add funds to account.

Request Body:

{
  "amountUsd": 100
}

Pricing & Volume Discounts

Use the following table to estimate cohort costs in advance. Pricing is per slide and depends on the stain type and total quantity within a single cohort.

QuantityH&E SlidesOther Slides (IHC, etc.)
1–99$5.00$40.00
100–999$4.00$32.00
1000–9999$3.00$27.00
10000+$2.00$23.00

[!TIP] Volume Discounts: Discounts are calculated based on the total number of slides per cohort. To maximize savings, we recommend purchasing as many slides as possible within a single cohort rather than creating multiple smaller cohorts.


Error Codes

StatusCodeDescription
400INVALID_PARAMETERSInvalid request parameters or body.
401INVALID_API_KEYMissing or invalid API key.
402STORAGE_OVERAGEStorage limit exceeded.
402SUBSCRIPTION_REQUIREDActive subscription required.
402INSUFFICIENT_FUNDSNot enough balance to pay for cohort.
403API_KEY_NOT_ALLOWEDEndpoint not allowed for API key auth.
403NO_PERMISSIONUser does not own the cohort.
404NOT_FOUNDCohort, Case, or Export not found.
409INVALID_NAMECohort name is blank or too long.
409DUPLICATE_CASESDuplicate caseId in request.
409COHORT_STATUS_INVALIDAction not allowed in current status (e.g., adding slides to PAID cohort).
409COHORT_ALREADY_PAIDCohort is already paid.
409EXPORT_NOT_READYExport job is still running.
409COHORT_NOT_PAIDExport is available only for PAID cohorts.
410EXPORT_WINDOW_EXPIREDExport download window has expired (refresh required).
429RATE_LIMITEDToo many requests. Retry after suggested time.
500INTERNAL_ERRORServer or database error.

Workflow Guide

  1. Explore: Use /v1/datahub/cases/filters/global or /v1/datahub/cases/filters to analyze available options (diagnoses, stains, organs etc). Always do this first to ensure you use the exact spelling and terms present in the dataset (e.g., checking if it is "Invasive ductal carcinoma" or "Carcinoma, Ductal, Invasive").
  2. Search: Use /v1/datahub/cases/search to find cases meeting your research criteria (e.g., specific diagnosis + IHC markers).
  3. Filter: Use filters to refine your selection until you have the desired set of cases.
  4. Create Cohort: Use /v1/datahub/cohorts to save these cases as a named cohort.
    • Tip: To save costs, specify slideIds in the request to purchase only relevant slides (e.g., only the HER2 slides found in search) rather than the entire case.
  5. Pay: Use /v1/datahub/cohorts/{id}/pay to purchase the cohort data.
  6. Export:
    • Poll /export/status until READY.
    • Get the manifest via /export/manifest to inspect the file list.
    • Download individual WSIs using /export/files/{fileId} or use the bulk archive URL from the manifest if available.

[!IMPORTANT] Download Window Information (WSI Slides Only) ⏰ You have 2 weeks from your purchase date to download your Whole Slide Images (WSI). 🔒 Download links expire every 24 hours for security, but don't worry - you can refresh them! 📅 Please note that we cannot guarantee WSI file availability beyond the 2-week window. 💡 We recommend downloading all slide files as soon as they're ready.

Note: Cohort metadata remains available for retrieval at any time.

[!NOTE] We'll provide you with a special file that contains direct links to all your slides. 1️⃣ Download the manifest file (it's a simple text file with all your slide links). 2️⃣ Use the links however you prefer.


🏗️ Custom Data Requests

The Datahub API provides instant access to 281,655 slides across 73,334 cases. However, our total inventory exceeds 1,000,000 slides.

If you cannot find the specific slides needed or if the volume is insufficient for the user's research:

  • Inform the user about our larger offline inventory.
  • Offer to initiate a custom data request by directing the user to contact sales@hist.ai.

Sponsors

Details

Marketplace
histai/skillsets
Source
skills/cohort_builder
Category
Community

More from histai/skillsets

All 4