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 CFR regulation reference, the OSHA recordability analysis family, and the claim-cost classifier) 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 an instrument's items for a UIpatterns-questions.md + the relevant instruments-<resource>.md
Compute the flagship composite (score + phenotype + magnitudes)composite-cdri-compute.md
Get the per-phenotype severities only ("how much")composite-magnitude-compute.md
Get the priority of risk against time ("how urgent")composite-acuity-compute.md
Get the phenotype + recommendations only ("which pattern")composite-phenotype-classify.md
Drive an adaptive intake questionnaireintake-next.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
Look up an industry's BLS injury benchmarksnaics-get.md
Compare an employer's OSHA-300 numbers to the national ratenaics-calculate.md
Search the Code of Federal Regulations or OSHA guidanceregulations-search.md
Fetch one CFR section's full text with its citationregulations-get.md
Browse a CFR part as a nested section treeregulations-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
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
Generate clinical-decision nudge candidates from a transcript windownudge-suggest.md
Decide which open nudges a transcript window has resolvednudge-check-resolution.md
Condense a live-call transcript window into clinical contentencounters-transcript-trim.md
Generate a TrinityAssist SOAP draft from an encounter transcriptencounters-soap-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 54 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.

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​

Shared contracts that cover every instrument's /questions and /score operations. Per-instrument docs defer to these for everything that isn't unique to that instrument.

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

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 composite analytics family. All share the same permissive input posture (any subset of the 14 instruments plus optional demographics) and the same pipeline; each surfaces a different slice of the result.

  • composite-cdri-compute.md — POST /api/cdri/compute: the flagship. Non-punitive peak cdri_score, seven phenotype magnitudes, phenotype classification, top-level red flags, and an optional embedded acuity view.
  • composite-magnitude-compute.md — POST /api/magnitude/compute: Risk Magnitude — the seven per-phenotype severities plus a ranked ordering ("how much").
  • composite-acuity-compute.md — POST /api/acuity/compute: Risk Acuity — priority of risk against time with a priority band ("how urgent"). Replaces the retired /screen/acute.
  • composite-phenotype-classify.md — POST /api/phenotype/classify: phenotype + recommendations only, no scoring envelope ("which pattern").
  • intake-next.md — POST /api/intake/next: engine-driven adaptive intake — returns the next batch of questions or signals completion.

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.

NAICS industry safety reference​

BLS injury and illness benchmarks plus an OSHA-300 incidence-rate calculator. Outside the clinical-instrument category tree — reference data plus arithmetic, not assessment.

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

CFR regulation reference​

Read-only lookup over 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 — no analysis, no AI. Every row carries the official source_url for citation.

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

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-suggest.md — POST /api/nudge/suggest: stateless endpoint that proposes clinical-decision nudge candidates for a transcript window. 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-transcript-trim.md — POST /api/encounters/transcript/trim: periodic condensation of a live-call transcript window into a clinical-content extract. Haiku-tier; the consumer's 5-minute scheduler ships one window per tick during an active visit. Output feeds the SOAP-draft refresh + final passes.
  • encounters-soap-draft.md — POST /api/encounters/soap/draft: SOAP narrative + structured extraction generated from a multi-session diarized transcript or a pre-condensed trimmed_transcript. Three call modes (on_demand / refresh / final) drive the engine's tier selection.
  • 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-questions.md, 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-magnitude-compute.md, composite-acuity-compute.md, composite-phenotype-classify.md, intake-next.md). Endpoint-doc shape with the phenotype taxonomy, the magnitudes/score scale note, red-flag and confidence shapes, and the recommendations modes. 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 doc for the shared blocks.

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, 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.