OpenAPI reference

This page is generated by npm run docs:prepare from route-level OpenAPI comments.

Download the published OpenAPI JSON from https://deepphe.github.io/dphe-data-api/openapi.json, or run the API and open http://localhost:3333/docs.

Generated content

Do not edit this page directly. Update the OpenAPI comments in src/routes/ and rerun npm run docs:prepare.

DeepPhe

GET /v1/deepphe-api/deepphe/attributes/classes

Get all unique attribute classes

Returns list of unique attribute class names

Responses

Status	Description
200	List of attribute class names
500	Internal server error

GET /v1/deepphe-api/deepphe/attributes/instances

Get all attribute instances for a specific class

Returns list of attribute objects for a specific class (without patient identifier arrays)

Parameters

Name	In	Required	Type	Description
groupname	query	yes	string	Group name

Responses

Status	Description
200	List of attributes
400	Missing required parameters
404	No attributes found for this class
500	Internal server error

GET /v1/deepphe-api/deepphe/attributes/instances/patient/{patientId}

Get attribute instances for a specific class and patient

Returns attribute rows where the specified patient appears

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID
groupname	query	yes	string	Group name

Responses

Status	Description
200	List of matching attributes
400	Missing required parameters
404	No attributes found for this class and patient
500	Internal server error

GET /v1/deepphe-api/deepphe/attributes/instances/patients

Get all attribute instances for a specific class including patient identifiers

Returns list of attribute objects for a specific class with patient identifier arrays

Parameters

Name	In	Required	Type	Description
groupname	query	yes	string	Group name

Responses

Status	Description
200	List of attributes with patient identifier arrays
400	Missing required parameters
404	No attributes found for this class
500	Internal server error

GET /v1/deepphe-api/deepphe/attributes/summary

Get all attribute classes and instances in one response

Returns attribute classes with instances grouped by class, with optional patient identifier data

Parameters

Name	In	Required	Type	Description
includePatientIds	query	no	boolean	When false, omit patient identifier arrays from instance rows

Responses

Status	Description
200	Attribute summary payload
500	Internal server error

GET /v1/deepphe-api/deepphe/cancers/classes

Get all unique cancer classes

Returns list of unique cancer class classUri values

Responses

Status	Description
200	List of cancer class classUri values
500	Internal server error

GET /v1/deepphe-api/deepphe/cancers/instances

Get all cancer instances for a specific class

Returns list of cancer objects for a specific class (without patient identifier arrays)

Parameters

Name	In	Required	Type	Description
classUri	query	yes	string	Class URI

Responses

Status	Description
200	List of cancers
400	Missing required parameters
404	No cancers found for this class
500	Internal server error

GET /v1/deepphe-api/deepphe/cancers/instances/patient/{patientId}

Get cancer instances for a specific class and patient

Returns cancer rows where the specified patient appears

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID
classUri	query	yes	string	Class URI

Responses

Status	Description
200	List of matching cancers
400	Missing required parameters
404	No cancers found for this class and patient
500	Internal server error

GET /v1/deepphe-api/deepphe/cancers/instances/patients

Get all cancer instances for a specific class including patient identifiers

Returns list of cancer objects for a specific class with patient identifier arrays

Parameters

Name	In	Required	Type	Description
classUri	query	yes	string	Class URI

Responses

Status	Description
200	List of cancers with patient identifier arrays
400	Missing required parameters
404	No cancers found for this class
500	Internal server error

GET /v1/deepphe-api/deepphe/cancers/summary

Get all cancer classes and instances in one response

Returns cancer classes with instances grouped by class, with optional patient identifier data

Parameters

Name	In	Required	Type	Description
includePatientIds	query	no	boolean	When false, omit patient identifier arrays from instance rows

Responses

Status	Description
200	Cancer summary payload
500	Internal server error

GET /v1/deepphe-api/deepphe/concepts/classes

Get all unique concept classes

Returns list of unique concept class dpheGroup values

Responses

Status	Description
200	List of concept class dpheGroup values
500	Internal server error

GET /v1/deepphe-api/deepphe/concepts/instances

Get all concept instances for a specific class

Returns list of concept objects for a specific class (without patient identifier arrays)

Parameters

Name	In	Required	Type	Description
dpheGroup	query	yes	string	DPHE Group

Responses

Status	Description
200	List of concepts
400	Missing required parameters
404	No concepts found for this class
500	Internal server error

GET /v1/deepphe-api/deepphe/concepts/instances/patient/{patientId}

Get concept instances for a specific class and patient

Returns concept rows where the specified patient appears

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID
dpheGroup	query	yes	string	DPHE Group

Responses

Status	Description
200	List of matching concepts
400	Missing required parameters
404	No concepts found for this class and patient
500	Internal server error

GET /v1/deepphe-api/deepphe/concepts/instances/patients

Get all concept instances for a specific class including patient identifiers

Returns list of concept objects for a specific class with patient identifier arrays

Parameters

Name	In	Required	Type	Description
dpheGroup	query	yes	string	DPHE Group

Responses

Status	Description
200	List of concepts with patient identifier arrays
400	Missing required parameters
404	No concepts found for this class
500	Internal server error

GET /v1/deepphe-api/deepphe/concepts/summary

Get all concept classes and instances in one response

Returns concept classes with instances grouped by class, with optional patient identifier data

Parameters

Name	In	Required	Type	Description
includePatientIds	query	no	boolean	When false, omit patient identifier arrays from instance rows

Responses

Status	Description
200	Concept summary payload
500	Internal server error

GET /v1/deepphe-api/deepphe/patient/{patientId}

Get patient documents with text excluded by default

Returns list of DocumentXn objects for a specific patient, with the text field excluded.

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID

Responses

Status	Description
200	List of DocumentXn objects without text
400	Missing or invalid patientId
404	Patient not found

GET /v1/deepphe-api/deepphe/patient/{patientId}/cancers

Get the cancers file for a patient

Returns the raw parsed JSON from the {patientId}_Cancers.json key-value entry in the database.

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID

Responses

Status	Description
200	Cancers data for the patient
400	Missing patientId
404	Cancers file not found for this patient
500	Internal server error

GET /v1/deepphe-api/deepphe/patient/{patientId}/concepts

Get the concepts file for a patient

Returns the raw parsed JSON from the {patientId}_Concepts.json key-value entry in the database.

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID

Responses

Status	Description
200	Concepts data for the patient
400	Missing patientId
404	Concepts file not found for this patient
500	Internal server error

GET /v1/deepphe-api/deepphe/patient/{patientId}/documents

Get all documents for a patient

Returns list of all DocumentXn objects for a specific patient with optional property exclusions.

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID
documentIds	query	no	string	Comma-separated list of document IDs to filter by. Only documents matching these IDs will be returned.
excludeProperties	query	no	string	Comma-separated list of DocumentXn properties to exclude from results (e.g., "mentions,mentionRelations,sections"). Valid properties: id, name, type, date, episode, text, mentions, mentionRelations, sections

Responses

Status	Description
200	List of DocumentXn objects with all properties
400	Missing or invalid patientId
404	Patient not found

GET /v1/deepphe-api/deepphe/patient/{patientId}/documents/episodes

Get episode counts for patient documents

Returns an object keyed by normalized episode type with counts for the patient's documents.

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID
documentIds	query	no	string	Optional comma-separated list of document IDs to include in the count.

Responses

Status	Description
200	Episode counts keyed by episode type
400	Missing or invalid patientId
500	Internal server error

Filter

POST /v1/deepphe-api/deepphe/filter/count

Count patients matching multi-criteria filters

Accepts an array of filter items. Each item specifies a data type
(omop, attributes, cancers, concepts), a class within that type,
and one or more instance values.
Within an item the instances are OR'd: a patient matches if they
have any of the listed values.
Across items the results are AND'd: a patient must satisfy
every filter item.
Timing metrics are always returned so callers can monitor performance.

Parameters

Name	In	Required	Type	Description
includePatientIds	query	no	boolean	When true, also return the list of matching patient IDs
autoIncludeThreshold	query	no	integer	Automatically include patient IDs when the matching count is below this threshold, even when includePatientIds is false. Set to 0 to disable auto-inclusion.

Request body: required (application/json)

Responses

Status	Description
200	Patient count with timing metrics
400	Validation error
500	Internal server error

POST /v1/deepphe-api/deepphe/filter/count/batch

Batch count patients for multiple independent filter queries

Accepts an array of independent filter queries and returns a result for
each in positional order. All queries are executed concurrently on the
server, replacing N sequential HTTP round trips with a single request.
Each query uses the same filter schema as POST /count. Per-query errors
are captured and returned inline rather than failing the entire batch.

Request body: required (application/json)

Responses

Status	Description
200	Array of per-query results in positional order
400	Validation error
500	Internal server error

POST /v1/deepphe-api/deepphe/filter/summary

Get patient summaries for a list of patient IDs

Accepts a set of patient IDs and returns matching patient summaries
from patient_summaries with uncompressed json_text payloads.

Request body: required (application/json)

Responses

Status	Description
200	List of patient summaries with uncompressed json_text
400	Validation error
500	Internal server error

OMOP

GET /v1/deepphe-api/omop/classes

Get all supported OMOP classes

Returns list of OMOP class names available for OMOP instances queries

Responses

Status	Description
200	List of OMOP class names
500	Internal server error

GET /v1/deepphe-api/omop/instances

Get all OMOP instances for a specific class

Returns OMOP rows from one of the OMOP tables by class (without patient identifier arrays)

Parameters

Name	In	Required	Type	Description
attribute	query	yes	`AGE_AT_DX	ETHNICITY

Responses

Status	Description
200	OMOP class rows
400	Missing or invalid required parameters
404	No OMOP rows found for this class
500	Internal server error

GET /v1/deepphe-api/omop/instances/patient/{patientId}

Get OMOP instances for a specific class and patient

Returns OMOP rows where the specified patient appears

Parameters

Name	In	Required	Type	Description
patientId	path	yes	string	Patient ID
attribute	query	yes	`AGE_AT_DX	ETHNICITY

Responses

Status	Description
200	Matching OMOP class rows for the patient
400	Missing or invalid required parameters
404	No OMOP rows found for this class and patient
500	Internal server error

GET /v1/deepphe-api/omop/instances/patients

Get all OMOP instances for a specific class including patient identifiers

Returns OMOP rows from one of the OMOP tables by class with patient identifier arrays

Parameters

Name	In	Required	Type	Description
attribute	query	yes	`AGE_AT_DX	ETHNICITY

Responses

Status	Description
200	OMOP class rows with patient identifier arrays
400	Missing or invalid required parameters
404	No OMOP rows found for this class
500	Internal server error

GET /v1/deepphe-api/omop/summary

Get all OMOP classes and instances in one response

Returns OMOP classes with instances grouped by class, with optional patient identifier data

Parameters

Name	In	Required	Type	Description
includePatientIds	query	no	boolean	When false, omit patient identifier arrays from instance rows

Responses

Status	Description
200	OMOP summary payload
500	Internal server error