Loading documentation

Access required

Your account doesn't have access to the documentation. Contact your administrator.

Sign out
Skip to main content

Trinity Engine API documentation

This directory is the public contract for every endpoint the Trinity Engine exposes. It is read by three audiences: external customers integrating against the API, internal engineers writing consumers, and AI indexers that help customers generate client code. Every file here is a standalone reference — readable cold, with no prior context about the engine's internals.

Every endpoint the engine exposes is documented here. The analytical surface (73 external wire endpoints, including the composite analytics family, the TrinityAssist clinical surfaces, the engine-owned nudge lifecycle, the case grading family, the lookup family (industry injury rates, federal regulations, ICD-10-CM and CPT codes, and workers' comp fee schedules), the OSHA recordability analysis family, the claim-cost classifier, the claim-complexity classifier, and the underwriting basis) is covered by these markdown files: shared reference pages, a multi-language quickstart, two pattern docs that cover the repeated instrument contracts, and per-endpoint files everywhere else.

New to the engine? Read quickstart.md first — it shows the full calling pattern in curl, Python, Node.js, TypeScript, Go, Java, C#, and PowerShell (plus smoke-only snippets for Ruby, PHP, Rust, and wget). Every per-endpoint doc assumes that scaffolding.

If you want to...Read
Make your first call in your language of choicequickstart.md
Learn how apikey authentication worksauthentication.md
Look up every error code and envelope extraserrors.md
Understand rate-limit headers and backoffrate-limits.md
Understand credit costs, billing headers, and 402credits.md
See the standing JSON, timestamp, and de-id rulesconventions.md
Check whether the engine is upinfrastructure-api-health-check.md
Check what build is liveinfrastructure-version-get.md
See whether the engine's models are healthymodel-services-health.md
Discover what the engine exposescatalog-get.md
Score a single instrumentpatterns-score.md + the relevant instruments-<resource>.md
Fetch CDRI questions for a UIcomposite-cdri-questions.md
Compute the flagship composite (index + channels + phenotype)composite-cdri-compute.md
Get the per-channel severities ("how much")composite-cdri-compute.md — the phenotypes block
Get the priority of risk against time ("how urgent")composite-cdri-compute.md — the acuity block, by sending case
Get the phenotype + recommendations only ("which pattern, what next")composite-phenotype-classify.md
Read a finished visit's transcript for answerscomposite-cdri-extract.md
Grade a care team's handling of a case (all priorities)grading-case-composite.md
Grade a care team on one priority onlygrading-case-priority.md
Find an industry by name or NAICS code prefixlookup-naics-search.md
Look up an industry's BLS injury benchmarkslookup-naics-get.md
Compare an employer's OSHA-300 numbers to the national ratelookup-naics-calculate.md
Search the Code of Federal Regulations or OSHA guidancelookup-regulations-search.md
Fetch one CFR section's full text with its citationlookup-regulations-get.md
Browse a CFR part as a nested section treelookup-regulations-tree.md
Autocomplete ICD-10-CM diagnosis codeslookup-icd10cm-search.md
Fetch one ICD-10-CM code with the coding notes of every ancestorlookup-icd10cm-get.md
Browse the ICD-10-CM hierarchy one level at a timelookup-icd10cm-tree.md
Autocomplete CPT codes for occupational health delivered virtuallylookup-cpt-search.md
Fetch one CPT code's descriptors, category, and add-on statuslookup-cpt-get.md
Browse the CPT codebook's section structurelookup-cpt-tree.md
Get the workers' comp maximum allowable for one service linelookup-fee_schedule-get.md
Price a slice of a jurisdiction's fee schedulelookup-fee_schedule-search.md
See which fee-schedule jurisdictions, versions, and localities are coveredlookup-fee_schedule-tree.md
Get cited OSHA recordability decision support for a caserecordability-analyze.md
Analyze one recordability factor at a fraction of the costrecordability-factor.md
Get the complete work-relatedness answer in one callwork_relatedness-analyze.md
Get an employer's claims, cost by claim size, and savings at your own rates for pricing a programmeunderwriting-basis.md
Classify a workers' comp claim's likely cost tier and bandclaimcost-classify.md
List the injury and body-part values the claim-cost model acceptsclaimcost-categories.md
Predict whether a claim will become procedurally complexclaimcomplexity-predict.md
List the gender codes and industries the claim-complexity model acceptsclaimcomplexity-options.md
Work out what a live visit is about and which of your care directives applynudge-helper.md
Generate clinical-decision nudge candidates from a transcript windownudge-suggest.md
Decide which open nudges a transcript window has resolvednudge-check-resolution.md
Pre-fill a clinical note's structured fields from a visit transcript, or draft a check-in's noteencounters-document-draft.md
Generate TrinityAssist typed reflection questions for a casecase_reflection-questions.md
Forward a signed TrinityAssist case reflection to the learning corpuscase_reflection-ingest.md

Contents​

All 70 files, grouped by role.

Cross-cutting references​

Shared rules every endpoint doc links to. Read once; referenced from everywhere.

  • authentication.md — The apikey header, key rotation, gateway 401 behavior.
  • errors.md — Error envelope and the full error code taxonomy.
  • rate-limits.md — RateLimit-* headers, Retry-After, backoff guidance.
  • credits.md — Credit metering, the X-Credits-* headers, 402 PaymentRequired, and per-key / account budgets.
  • conventions.md — Timestamps, request IDs, null-vs-missing, the de-identification contract.

Quickstart​

  • quickstart.md — Multi-language calling guide. Full Tier 1/2 patterns (curl, Python, Node, TypeScript, Go, Java, C#, PowerShell) plus Tier 3 smoke snippets (Ruby, PHP, Rust, wget). Covers auth, error envelope parsing, retries, and Retry-After.

Infrastructure endpoints​

Platform-level endpoints outside the catalog.

Model Services endpoints​

Operational visibility into the engine's model fleet — the models the engine runs as part of its analytics but that callers cannot reach directly.

  • model-services-health.md — GET /api/model_services/health: per-model health across the engine's model catalog (ok / unreachable / unconfigured). Built for status pages and fleet monitors.

Claim-cost classification​

A model-backed classifier that estimates the cost category of a workers' comp claim from a de-identified injury, body part, and age. Returns a binary cost tier and a three-band cost band in one call. Fixed per-call cost; a statistical signal, not a reserve or a claim decision.

  • claimcost-classify.md — POST /api/claimcost/classify: injury + body part + age in; a binary cost tier (High/Low) and a three-band cost band (High/Medium/Low) out, each with confidence and full probabilities.
  • claimcost-categories.md — GET /api/claimcost/categories: the accepted injury and bodyPart vocabularies, sourced live from the model. Validate inputs against it to avoid a billed 400.

Underwriting​

The actuarial basis for pricing an employer's workers' compensation programme. Arithmetic over the caller's input and a versioned calibration; returns no prices, costs, margins or terms. Never fails on a sparse body.

  • underwriting-basis.md — POST /api/underwriting/basis: employer facts in; claims a year, cost parts, indirect and movable cost, five claim sizes, the blended savings rate at your own or the default rates, readiness and confidence out.

Claim-complexity classification​

A model-backed classifier that predicts whether a workers' comp claim is likely to become procedurally complex — hearings, repeated independent medical exams, alternative dispute resolution — from six de-identified early-claim attributes. A research proxy for administrative friction, not an official determination, not severity, and not cost. Complements claim-cost rather than replacing it.

  • claimcomplexity-predict.md — POST /api/claimcomplexity/predict: six features in; a high_complexity / standard_complexity label with confidence and full probabilities out.
  • claimcomplexity-options.md — GET /api/claimcomplexity/options: accepted gender codes, industry_title values, numeric ranges, and the target definition the model was trained against. Validate inputs against it to avoid a billed 400.

Catalog endpoints (self-describing API)​

Discovery surface. All accept ?audience=employee|employer|provider except /operations.

  • catalog-get.md — GET /api/catalog/get: full catalog tree. Discovery entry point.
  • catalog-categories.md — GET /api/catalog/categories: categories with nested resources.
  • catalog-resources.md — GET /api/catalog/resources: flat resource list with path_prefix. Codegen surface.
  • catalog-operations.md — GET /api/catalog/operations: flat (method, path, version) tuples. No ?audience=.
  • catalog-category.md — GET /api/catalog/category: single category by ?name=.
  • catalog-resource.md — GET /api/catalog/resource: single resource by ?name=, optionally narrowed by ?category=.

Debug​

  • debug-echo.md — POST /api/debug/echo: integration-test echo. Also the cleanest worked example of the de-identification contract firing in isolation.

Instrument patterns​

The shared contract behind every instrument's /score operation. Per-instrument docs defer to it for everything that isn't unique to that instrument.

  • patterns-score.md — POST /api/:category/:resource/score contract, including ?depth=basic|contextual|full semantics.

Reading an instrument's items is not a per-instrument operation. See composite-cdri-questions.md, which answers for every instrument at once.

Per-instrument docs (14 instruments)​

Each file carries what is unique to that instrument: item map, scoring method, band cutoffs, required items, worked example, and clinical caveats. Grouped here by catalog category.

Pain (/api/pain/...)

Function (/api/function/...)

Psychosocial (/api/psychosocial/...)

Fear-avoidance (/api/fear_avoidance/...)

Return-to-work belief (/api/rtw_belief/...)

Occupational (/api/occupational/...)

Iatrogenic (/api/iatrogenic/...)

Composite​

The CDRI family. All four share one vocabulary — a question is a bank item_id, an answer is a code on a 0–6 ladder, and an {item_id, value} object moves between them unchanged — and the same permissive input posture: any number of answers is valid, including none.

These endpoints and the instruments do not meet. The CDRI is scored from a curated question bank; the published instruments are a separate family with their own /score endpoints, and the two share no identifiers and no inputs.

  • composite-cdri-compute.md — POST /api/cdri/compute: the flagship. A 0–100 index with its seven-level band, one reading per risk channel carrying that channel's level, its own evidence figure and its residual, a breadth measure, phenotype classification, confidence, and an optional acuity block ("how much, and how closely does it need watching").
  • composite-phenotype-classify.md — POST /api/phenotype/classify: phenotype + recommendations, no scoring envelope ("which pattern, and what next"). The only endpoint that returns recommendations.
  • composite-cdri-questions.md — POST /api/cdri/questions: the question source. Render-ready questions from the bank, gated by audience and rapport floor, in the order you ask for.
  • composite-cdri-extract.md — POST /api/cdri/extract: the bank questions a finished visit's transcript already answered, each with a confidence tier and the quote behind it.

Case Grading​

Grades a whole care team's handling of a single case and returns one role-filtered result per member — a 0.0–1.0 grade decomposed into priorities and KPIs, each with a rationale. De-identified and processing-only: the engine resolves no identity and stores no caller data.

  • grading-case-composite.md — POST /api/grading/case/composite: grade across all seven priorities in one call. The full request/response contract.
  • grading-case-priority.md — POST /api/grading/case/{priority_key}: grade one priority only; same shape, scoped to a single priority.

Lookup​

Reference data you search, fetch, and navigate, under /api/lookup/{resource}/.... Every resource offers search and get, and every record carries code and label, so one autocomplete or detail component works against all of them; every resource except NAICS adds tree. Every search validates q (at least two characters) and limit (1–50, default 10) the same way, with the same error messages. Reference data, not analysis — no AI.

NAICS industry injury rates (/api/lookup/naics/...) — BLS injury and illness incidence rates by NAICS code, plus an OSHA-300 calculator that compares an employer's case counts against its industry.

  • lookup-naics-search.md — GET /api/lookup/naics/search: type-ahead by industry name or numeric code prefix.
  • lookup-naics-get.md — GET /api/lookup/naics/get: single benchmark record for one NAICS code.
  • lookup-naics-calculate.md — POST /api/lookup/naics/calculate: employer rate computation and side-by-side comparison against the looked-up benchmark.

CFR regulations (/api/lookup/regulations/...) — the full Code of Federal Regulations plus an OSHA recordkeeping guidance corpus (FAQs, rulemaking-preamble excerpts, and letters of interpretation tied to 29 CFR 1904). Accurate, citable source text; every item carries the official source_url.

  • lookup-regulations-search.md — GET /api/lookup/regulations/search: ranked search by natural language, partial words, or a section-number fragment; ?type=guidance searches the OSHA guidance corpus instead.
  • lookup-regulations-get.md — GET /api/lookup/regulations/get: one section's complete text by id or section number (paragraph references resolve to their section).
  • lookup-regulations-tree.md — GET /api/lookup/regulations/tree: one CFR part as a nested subpart/section tree in document order.

ICD-10-CM diagnosis codes (/api/lookup/icd10cm/...) — the US ICD-10-CM code set of the release in effect, every chapter, section, header, and billable code, with the release named on every response.

  • lookup-icd10cm-search.md — GET /api/lookup/icd10cm/search: autocomplete over codes, descriptions, inclusion terms, and the alphabetic index.
  • lookup-icd10cm-get.md — GET /api/lookup/icd10cm/get: one code's record with the coding notes of each ancestor.
  • lookup-icd10cm-tree.md — GET /api/lookup/icd10cm/tree: one level of the chapter, section, category, and code hierarchy.

CPT procedure codes (/api/lookup/cpt/...) — a curated CPT codebook for occupational health delivered virtually (visits and work evaluations, rehabilitation, behavioral health, remote monitoring, care management), not the full CPT code set.

  • lookup-cpt-search.md — GET /api/lookup/cpt/search: autocomplete by code prefix or descriptor words.
  • lookup-cpt-get.md — GET /api/lookup/cpt/get: one code's descriptors, category, add-on status, and ancestors.
  • lookup-cpt-tree.md — GET /api/lookup/cpt/tree: one level of the codebook's section structure.

Workers' comp fee schedules (/api/lookup/fee_schedule/...) — the maximum a workers' compensation jurisdiction allows for one professional service line, computed from the published CMS fee schedule and that jurisdiction's adopted rules, with the version in force and its citation. One request and response shape for every jurisdiction.

  • lookup-fee_schedule-get.md — GET /api/lookup/fee_schedule/get: the maximum allowable for one service line in one jurisdiction and location.
  • lookup-fee_schedule-search.md — GET /api/lookup/fee_schedule/search: a priced slice of one jurisdiction's schedule by code prefix or descriptor text.
  • lookup-fee_schedule-tree.md — GET /api/lookup/fee_schedule/tree: the jurisdictions covered, their version history, and their localities.

OSHA recordability analysis​

Regulation-grounded decision support for OSHA 29 CFR 1904 recordability determinations. Every analysis cites the exact regulation paragraphs and official OSHA guidance it relied on, and the engine never makes the final determination — responses are weighted, cited suggestions for the recordkeeping professional.

  • recordability-analyze.md — POST /api/recordability/analyze: the full composite — five key factors analyzed concurrently and combined along the 1904.4 decision tree into a recordability score plus confidence.
  • recordability-factor.md — POST /api/recordability/{factor}: one focused factor (work_relatedness, exceptions, recurrence, treatment, significance) for callers that need a single answer.
  • work_relatedness-analyze.md — POST /api/work_relatedness/analyze: the standalone work-relatedness surface — the 1904.5 presumption and all nine 1904.5(b)(2) exceptions combined into one score.

TrinityAssist clinical surfaces​

Engine-side AI clinical generation plus the inbound learning corpus path. Covers clinical-decision nudges, SOAP drafts, and typed per-case reflection prompts. Metered like every other endpoint, subject to the same de-identification contract. The engine is a pure REST API -- it does not transcribe audio; the consumer brings its own transcript and feeds it to these endpoints.

  • nudge-helper.md — POST /api/nudge/helper: reads the intake, the recent conversation and your care-directive index, and returns a brief -- the visit's current focus and the directives that apply -- for suggest to work from.
  • nudge-suggest.md — POST /api/nudge/suggest: stateless endpoint that proposes clinical-decision nudge candidates for a transcript window, for the reader you describe. The consumer drives it on a cadence during a live visit.
  • nudge-check-resolution.md — POST /api/nudge/check_resolution: stateless endpoint that decides which currently-open nudges a transcript window has resolved.
  • encounters-document-draft.md — POST /api/encounters/document/draft: reads one finished visit's diarized transcript and pre-fills the structured fields of a clinical note — the subjective history, objective exam findings, ranked differential, plan, any spoken vitals, and the work-status / work-relatedness proposals. Every value is a code from the consumer's exam catalog at the requested catalog_version. A full visit returns no prose: the consumer composes its own narrative from the structure, so one composer produces every note. A check-in (encounter_purpose: "check_in") returns a short narrative note instead, never empty. Called once per encounter, after the visit ends.
  • case_reflection-questions.md — POST /api/case_reflection/questions: 3-10 typed reflection questions (yes/no, 0-10 numeric scale, date, single-/multi-select, short text) scoped to the longitudinal case.
  • case_reflection-ingest.md — POST /api/case_reflection/ingest: persist a signed case reflection (typed questions + typed clinician answers + sign-off metadata) to the engine learning corpus.

Doc shapes​

Not every file follows the same template. Five distinct shapes are in use.

  1. Title + status / category / added / last-reviewed frontmatter.
  2. Summary (1–3 sentences — decide from this alone whether this is the endpoint you want).
  3. Endpoint (method, path, full URL, auth, body, idempotency).
  4. Purpose (why the endpoint exists, what problem it solves).
  5. Authentication (points to authentication.md).
  6. Request (headers, path / query parameters, body, body fields).
  7. Response (success examples, response fields, status codes).
  8. Examples (curl, Python, Node).
  9. Intended use (non-obvious valid scenarios).
  10. Mistaken use (common wrong uses, with the right alternative).
  11. Debugging (numbered checklist).
  12. Rate limits (points to rate-limits.md).
  13. Related.
  14. Change history.

Cross-cutting reference (authentication.md, errors.md, rate-limits.md, conventions.md). Same frontmatter and change history, but the body is organized around the concept, not an HTTP call. No Endpoint / Request / Response sections.

Pattern doc (patterns-score.md). Endpoint-doc shape, but the path template uses :category/:resource placeholders. Describes the shared contract that per-instrument docs inherit. Per-instrument docs link back for the full rules.

Per-instrument doc (instruments-<resource>.md). Compact structure focused on what is unique:

  1. Frontmatter.
  2. Summary.
  3. Resource identity table (category, resource, instrument ID, rubric version, path prefix).
  4. Operations table (questions + score with links to the pattern docs).
  5. Items (IDs, paraphrased prompts, answer-choice range).
  6. Scoring (method + parameters).
  7. Bands (inclusive ranges + clinical meaning).
  8. Required items.
  9. Worked example (curl + computation walkthrough).
  10. Clinical interpretation.
  11. Intended use / Mistaken use.
  12. Debugging.
  13. Related.
  14. Change history.

Composite doc (composite-cdri-compute.md, composite-cdri-questions.md, composite-cdri-extract.md, composite-phenotype-classify.md). Endpoint-doc shape with the phenotype taxonomy, the band scale, and the confidence shape. Internal scoring mechanics are intentionally out of scope (see Out of scope). Uses a ⚠ callout for the safety disclaimer; sibling composite docs cross-link to the CDRI compute doc for the shared blocks, and the recommendation modes and item shape live on composite-phenotype-classify.md, which is the only endpoint that returns them.

Frontmatter block​

Every doc starts with a standardized block:

# <Title>

> **Status:** `stable` | `beta` | `deprecated`
> **Category:** `<category-name>`
> **Added:** `YYYY-MM-DD`
> **Last reviewed:** `YYYY-MM-DD`

The Category value is one of: reference (cross-cutting pages), patterns, infrastructure, model_services, catalog, debug, composite, trinityassist, grading, lookup, or a catalog category name for per-instrument docs (pain, function, psychosocial, fear_avoidance, rtw_belief, occupational, iatrogenic).

Added is the date the doc first landed; Last reviewed is bumped when someone reads the doc end-to-end and confirms it still describes the deployed behavior.

Code-example conventions​

  • Fenced code blocks always carry a language tag (json, bash, http, python, ts).
  • curl examples use -sS (silent, show errors) and keep argument order consistent: URL, then -H headers, then -d body. For response inspection add -w "\nHTTP %{http_code}\n".
  • Every curl example assumes ENGINE_API_KEY is set in the caller's environment. Do not embed literal keys.
  • Python examples use the requests library; Node examples use the native fetch. One of each per endpoint doc, minimum.
  • JSON examples in ## Response sections must be complete — no ... placeholders inside objects. Abbreviate between sections by stating "abbreviated for readability" and trimming repeated entries, not by using ellipses inside a JSON object.

Response-field tables​

Every response field gets three things in the table: a type, an always-present flag, and a one-sentence description. Missing any one of the three is a review blocker. Nested fields use dotted paths (finding.context.percentile).

Status-code tables​

Every status code the endpoint can return appears in the Status codes section, with meaning (the error code where applicable) and the condition that fires it. Rows cite the envelope extras (field, missing, retry_after) alongside the error class when they can appear.

Cross-linking​

  • Internal links use the relative filename path (./authentication.md, ./patterns-score.md#confidence-renormalization).
  • Per-instrument docs link back to the pattern doc for every shared rule. The pattern doc does not forward-reference specific instruments.
  • Every doc ends with a ## Related section listing the closest neighbors (typically the patterns it inherits from, related domain docs, and the cross-cutting references).
  • Use backtick-wrapped endpoint paths in link text when they appear in prose ([GET /api/catalog/resources](./catalog-resources.md)).

Intended use / Mistaken use pattern​

Every endpoint doc pairs an Intended use list with a Mistaken use list. Mistaken use bullets are not "do not call this endpoint" — they are "do not use this endpoint for X; use Y instead." Each bullet names the right alternative. This pattern is the directory's dominant way of routing readers to the correct endpoint when the names alone are ambiguous.

Out of scope for this directory​

  • Internal architecture. How the engine computes its results, and its startup and data-migration internals. The docs describe how to call the API, not how it is built.
  • Clinical deep-dives. Longer-form explanations of what the instruments measure, how CDRI works conceptually, and the phenotype taxonomy in plain language.
  • SDK / client-library references. Each endpoint doc carries curl, Python, and Node examples. First-class SDK reference is NOT a product we serve right now.