Guides

Guides

One section per capability. Each has a code example and a note on when to reach for it. For exact signatures, params, and errors see API-Reference.

dtp.twins

Connect to a patient's twin with their grant token.

// connect.ts
import { DTP } from "@ontomorph/dtp-sdk";

const dtp = new DTP({ apiKey: process.env.DTP_API_KEY });

const twin = await dtp.twins.connect(grantToken);
twin.grant.twinId;  // the twin this grant authorizes
twin.grant.systems; // e.g. ["cardiovascular"], or null for all

connect decodes the grant locally and returns a Twin. It does not hit the network (the token is verified server-side on the first data request), so it returns fast, and the grant claims (grantId, twinId, systems, eventTypes) are available right away.

When to use: at the start of any interaction with a patient's data. Everything else hangs off the Twin it returns.

twin.systems

Read one body system as a SystemView.

// read-system.ts
const view = await twin.systems.get("cardiovascular");
// SystemView: { system, twinId, events: HealthEvent[] }
console.log(view.events.length);

A SystemView is built from the twin's grant-scoped events filtered by event.data.system. Clinical fields (code, value, unit, system) live inside each event's data object, not at the top level.

When to use: when you want the current picture of one system in a single call.

twin.events

List events once, or watch for new ones.

// events.ts
// One-shot list (paginated).
const events = await twin.events.list({ system: "cardiovascular", limit: 50 });

// Continuous watch. Returns a handle; call stop() to end it.
const handle = twin.events.stream(
  { system: "cardiovascular", intervalMs: 5_000 },
  (event) => console.log("new event", event.id),
);
handle.stop();

How stream works: twin-core has no grant-scoped push stream, so stream polls list on an interval (every 5s by default, set by intervalMs) and emits only events it has not seen before. For high-frequency needs, poll list yourself on your own schedule.

When to use list: for a snapshot, a report, or your own polling loop. When to use stream: to react to new events without writing the polling loop yourself.

twin.flag

Write a flag event back onto the twin.

// flag.ts
await twin.flag("cardiovascular", {
  code: "LDL",
  value: 190,
  title: "LDL above target",
  description: "Consider statin review",
});

Any HealthEvent satisfies FlagInput, so a streamed event can be forwarded straight through. The grant must permit the flag's eventType, which defaults to "flag".

When to use: when your integration reaches a finding worth recording on the twin, so it becomes a health event others can read.

dtp.keys

Manage your own API keys. Requires sessionToken in the constructor, because this surface is user-authed.

// keys.ts
const keys = await dtp.keys.list();

const created = await dtp.keys.create({
  name: "CI pipeline",
  keyType: "personal",   // personal | org | device | research
  scopes: ["twins:read"],
  environment: "live",   // live | test
});
console.log(created.key); // the raw key, shown exactly once

await dtp.keys.revoke(created.id);

When to use: to provision keys for CI, rotate a key on a schedule, or revoke one that leaked. The raw key on create is shown once, so store it immediately.

dtp.holon

Reach the HOLON clinical-knowledge API. Requires holonApiUrl and holonApiKey in the constructor.

// holon.ts
const results = await dtp.holon.concepts.search("atorvastatin");
const drugA = results.hits[0].conceptId;

// check a pair of drug concept ids for a known interaction
const interaction = await dtp.holon.interactions.check(drugA, otherDrugId);

dtp.holon returns a configured @ontomorph/holon-client. See its docs for the full clinical-knowledge surface.

When to use: to interpret twin data, for example resolving a drug name to a concept id, checking interactions, or looking up a reference range.

Related: Use-Cases combines these end to end.