-
Notifications
You must be signed in to change notification settings - Fork 0
API Reference
Every export, method, option, return field, and error code. For narrative walkthroughs, see Guides and Use-Cases.
// create.ts
import { createHolonClient } from "@ontomorph/holon-client";
const holon = createHolonClient({
apiUrl: "https://holon-api.ontomorph.com",
apiKey: process.env.HOLON_API_KEY, // holon_…
timeout: 30_000,
});createHolonClient(config) returns a HolonClient. It takes one config object.
HOLON API base URL, for example https://holon-api.ontomorph.com. Type string. Required.
Your holon_… key, sent as a bearer token in the Authorization: Bearer <apiKey> header on every request. Type string. Required.
Per-request timeout in milliseconds, applied via AbortSignal.timeout. Type number. Optional.
The object returned by createHolonClient. It exposes five namespaces:
A ConceptsApi. Search and resolve concepts, and walk the hierarchy.
An InteractionsApi. Screen drugs for known interactions.
A MappingsApi. Move a code across vocabularies.
A ReferenceRangesApi. Read normal ranges for lab tests.
A PhenotypeApi. Score similarity between two sets of phenotype terms.
await holon.concepts.getById("40213251"); // ConceptResponseLook up a single concept by its conceptId. Returns a ConceptResponse.
await holon.concepts.getByCode("197361", "RxNorm");Resolve a raw vocabulary code to its concept.
The source code, for example "197361".
The vocabulary the code belongs to, for example "RxNorm".
await holon.concepts.search("metformin", { domain: "Drug", page: 1, pageSize: 20 });Search concepts by term. options is optional.
The search term.
Narrow the search to one domain, for example "Drug".
The page number to return.
The number of hits per page.
Returns { hits, total, page, pageSize }.
The array of matching concepts. Each hit carries a conceptId, conceptCode, conceptName, vocabularyId, and domainId.
The total number of matches across all pages.
The page number returned.
The number of hits per page.
await holon.concepts.getAncestors(40213251); // hierarchy upReturn the concepts above this one in the hierarchy.
await holon.concepts.getDescendants(40213251); // hierarchy downReturn the concepts below this one in the hierarchy.
await holon.interactions.getByDrugId(11289); // all interactions for a drugReturn every known interaction recorded for a single drug.
await holon.interactions.check(11289, 1191); // → { hasInteraction, interactions }Pairwise check between two drugs. Returns { hasInteraction, interactions }.
true when at least one interaction exists between the pair.
The array of interactions found.
await holon.interactions.checkList([11289, 1191, 197361]); // whole-list screenScreen a whole medication list. Takes an array of drug ids and reports interactions within the set.
await holon.mappings.getByConceptId(40213251); // all cross-vocab mappingsReturn all cross-vocabulary mappings for a concept.
await holon.mappings.translate("197361", "RxNorm", "SNOMED"); // → { source, target, mappings }Translate a code from one vocabulary into another. Returns { source, target, mappings }.
The source code to translate, for example "197361".
The vocabulary the code comes from, for example "RxNorm".
The vocabulary to translate into, for example "SNOMED". Optional. Omit it to get mappings into every available vocabulary.
The source code and vocabulary echoed back.
The target vocabulary of the translation.
The array of mapping entries produced.
await holon.referenceRanges.getByConceptId(3004249); // by HOLON concept idReturn reference ranges for a HOLON measurement concept.
await holon.referenceRanges.getByLoincCode("2093-3", 45, "male"); // by LOINC, age and sex adjustedReturn reference ranges for a LOINC code, optionally adjusted for a demographic.
The LOINC code, for example "2093-3".
The patient age. Optional. Supply it to narrow the range.
The patient sex, for example "male". Optional. Supply it to narrow the range.
// Score similarity between two sets of phenotype concept ids.
await holon.phenotype.match([9826, 4245975], [9826, 31967]);Score how alike two sets of phenotype concept ids are.
The first set of phenotype concept ids.
The second set of phenotype concept ids.
A non-2xx response, or a network or timeout failure, throws a HolonError from @ontomorph/holon-types. It carries a machine-readable ErrorCode and the raw response detail.
// error-handling.ts
import { HolonError, ErrorCode } from "@ontomorph/holon-types";
try {
await holon.concepts.getByCode("bogus", "RxNorm");
} catch (err) {
if (err instanceof HolonError) {
console.error(err.code, err.message); // e.g. CONCEPT_NOT_FOUND …
if (err.code === ErrorCode.RATE_LIMIT_EXCEEDED) backOff();
// err.details holds { status, body } from the response
}
}The machine-readable ErrorCode for the failure.
The human-readable message.
The raw response detail, holding { status, body } from the response.
CONCEPT_NOT_FOUND, VOCABULARY_NOT_FOUND, NO_MAPPING_FOUND, INTERACTION_CHECK_FAILED, UNAUTHORIZED, FORBIDDEN, RATE_LIMIT_EXCEEDED, VALIDATION_ERROR. The full ErrorCode enum lives in @ontomorph/holon-types.
Response and entity types are exported for you to annotate with:
// types.ts
import type {
HolonClient,
ConceptResponse,
SearchResponse,
InteractionsResponse,
MappingEntry,
ReferenceRangeEntry,
PhenotypeMatch,
} from "@ontomorph/holon-client";The lower-level *Api classes (ConceptsApi, InteractionsApi, MappingsApi, ReferenceRangesApi, PhenotypeApi) are exported too, if you want to construct a single namespace on its own.