All Catalog Categories

Status: stable Category: catalog Added: 2026-04-20 Last reviewed: 2026-10-14

Summary

Returns the list of registered categories with their nested resources and operations. Same shape as the categories array from /api/catalog/get, but without the surrounding version / last_updated header and without the top_level_resources block.

Reach for this when you only need the category tree and do not need the top-level resources (composites, analysis and assist surfaces, infrastructure, debug).

Endpoint

Field	Value
Method	GET
Path	/api/catalog/categories
Full URL	https://engine.tripod-health.com/api/catalog/categories
Authentication	API key (required)
Request body	none
Response body	application/json
Idempotent	Yes
Rate-limited	Yes

Purpose

Trinity groups related resources under a small number of categories: seven instrument categories (pain, function, psychosocial, fear_avoidance, rtw_belief, occupational, iatrogenic), the clinical encounters surface, case grading, and the lookup reference data. Many UIs want only that structure — a left-nav, a category selector, a domain picker. This endpoint returns the category tree and nothing else.

If you additionally need composites like cdri or infrastructure endpoints, use /api/catalog/get instead — those live under top_level_resources, which this endpoint does not return.

Authentication

Send a valid API key in the apikey header. See authentication.md.

Request

Headers

Header	Required	Description
apikey	Yes	Consumer API key.

Path parameters

None.

Query parameters

Parameter	Type	Required	Default	Description
audience	string	No	none	One of employee, employer, provider. Replaces each entity's display_name with that audience's alias (falling back to the canonical display_name). When omitted, canonical labels are returned.

Body

None.

Response

Success — 200 OK

Top-level array. Every element is a category object (identical to the category shape inside /api/catalog/get). Abbreviated for readability: two of the ten categories (pain and lookup), each trimmed to its first resource. Every object shown is complete.

[
  {
    "name": "pain",
    "display_name": "Pain",
    "aliases": {
      "employee": "Pain Level",
      "employer": "Pain",
      "provider": "Pain"
    },
    "description": "Subjective pain intensity and pain-oriented screening tools.",
    "version": "0.1.0",
    "last_updated": "2026-04-17",
    "resources": [
      {
        "name": "orebro",
        "display_name": "Orebro Musculoskeletal Pain Screening",
        "aliases": {
          "employee": "Pain Screening Questionnaire",
          "employer": "Musculoskeletal Pain Screening",
          "provider": "Orebro"
        },
        "description": "Orebro Musculoskeletal Pain Screening Questionnaire (OMPSQ): multi-item screening that returns a total score and a risk profile.",
        "version": "1.1.0",
        "last_updated": "2026-10-11",
        "operations": [
          {
            "name": "score",
            "display_name": "Score",
            "aliases": {},
            "description": "Submit responses to the instrument and receive its score (and profile, where the instrument supports classification).\n\nWith `?audience=`, an optional `assist_context` sets the persona and instructions for the audience-facing summary and per-item messages; on-demand references are not accepted. Both texts pass the outbound identifier scan.",
            "version": "1.1.0",
            "last_updated": "2026-10-11",
            "http_method": "POST"
          }
        ]
      }
    ]
  },
  {
    "name": "lookup",
    "display_name": "Lookup",
    "aliases": {
      "employee": "Reference Lookup",
      "employer": "Reference Data",
      "provider": "Code & Reference Lookup"
    },
    "description": "Reference data a developer searches, fetches and navigates: industry injury rates, federal regulations, medical code sets and workers' comp fee schedules. Every resource offers `search` and `get` with `code` + `label` on each record, so one client component serves them all; code resources add `tree`. Served from the engine's own tables -- no request is passed to a third party.",
    "version": "1.1.0",
    "last_updated": "2026-10-13",
    "resources": [
      {
        "name": "naics",
        "display_name": "NAICS Industry Safety Reference",
        "aliases": {
          "employee": "Industry Injury Rates",
          "employer": "Industry Safety Benchmarks",
          "provider": "NAICS Industry Reference"
        },
        "description": "BLS recordable-injury and illness incidence rates by NAICS code, plus an OSHA-300 calculator that compares an employer's reported case counts against the national rate for their industry.",
        "version": "1.0.0",
        "last_updated": "2026-10-13",
        "operations": [
          {
            "name": "search",
            "display_name": "Search",
            "aliases": {},
            "description": "Type-ahead search by industry name or numeric NAICS prefix. Returns up to N matches ranked by code length, then code. Each hit carries `code` (the NAICS code) and `label` (the industry name).",
            "version": "1.0.0",
            "last_updated": "2026-10-13",
            "http_method": "GET"
          },
          {
            "name": "get",
            "display_name": "Get",
            "aliases": {},
            "description": "Return one industry's full benchmark row by `?code=<naics>`, with the same `code` + `label` a search hit carries. Optional `?ownership=` selects the BLS ownership cohort. Responds 404 if the (code, ownership) pair is unregistered.",
            "version": "1.0.0",
            "last_updated": "2026-10-13",
            "http_method": "GET"
          },
          {
            "name": "calculate",
            "display_name": "Calculate",
            "aliases": {},
            "description": "Compute employer recordable-injury incidence rates from OSHA-300 case counts and exposure hours, and compare them against the looked-up benchmark when `naics_code` is supplied; the echoed `benchmark` carries `code` + `label`. Permissive on input -- partial bodies surface as warnings, not request failures.",
            "version": "1.0.0",
            "last_updated": "2026-10-13",
            "http_method": "POST"
          }
        ]
      }
    ]
  }
]

Response fields

The top-level value is a JSON array. Each element has the same fields as one entry in categories[] from /api/catalog/get:

Field	Type	Always present	Description
name	string	Yes	URL-safe identifier used in paths.
display_name	string	Yes	Canonical label — or the audience alias when ?audience= was set.
aliases	object	Yes	Map from audience name to alias string. May be {}.
description	string	Yes	One-sentence description.
version	string (SemVer)	Yes	Category-level version.
last_updated	string (ISO date, YYYY-MM-DD)	Yes	Last structural change.
resources	array	Yes	Resources in this category.

Resource and operation sub-shapes are identical to those documented in /api/catalog/get.

What this endpoint does not return

• The catalog-root version and last_updated fields.
• top_level_resources — the 17 resources outside any category, such as the composites (cdri, phenotype), the analysis and assist surfaces (recordability, nudge, assist, and others), and the infrastructure / debug resources (health, version, catalog, debug).

If you need either of those, call /api/catalog/get.

Status codes

Code	Meaning	When
200	OK	Array returned.
400	ValidationError	audience was provided but not one of the allowed values. field: "audience".
401	Unauthenticated	Missing or invalid API key.
429	RateLimited	Per-consumer rate limit exceeded.

Examples

The language-specific invocations below assume the call() helper (or its equivalent) from quickstart.md.

1. Canonical request and response

Send:

GET /api/catalog/categories HTTP/1.1
Host: engine.tripod-health.com
apikey: $ENGINE_API_KEY

Receive (200 OK): a top-level array of category objects. See the Success — 200 OK section above for the abridged shape; the live response carries every registered category (ten today) with their nested resources and operations.

2. Calling the endpoint in your language

curl — canonical and audience variants

# Canonical display names
curl -sS "https://engine.tripod-health.com/api/catalog/categories" \
  -H "apikey: $ENGINE_API_KEY"

# Employer-facing labels
curl -sS "https://engine.tripod-health.com/api/catalog/categories?audience=employer" \
  -H "apikey: $ENGINE_API_KEY"

With ?audience=employer, the function category's display_name becomes "Functional Capacity" while pain stays as "Pain" (the canonical matches the employer alias here).

Python (requests)

# Uses the call() helper from quickstart.md.
categories = call("GET", "/api/catalog/categories?audience=employee")
for cat in categories:
    print(cat["display_name"])
    for res in cat["resources"]:
        print(f"  - {res['display_name']}  (/api/{cat['name']}/{res['name']})")

Node.js (native fetch)

// Uses the call() helper from quickstart.md.
const categories = await call("GET", "/api/catalog/categories");
for (const cat of categories) {
  console.log(cat.display_name);
  for (const res of cat.resources) {
    console.log(`  - ${res.display_name}  (/api/${cat.name}/${res.name})`);
  }
}

TypeScript

// Uses the typed call<T>() helper from quickstart.md.
interface CatalogOperation {
  name: string;
  display_name: string;
  aliases: Record<string, string>;
  description: string;
  version: string;
  last_updated: string;
  http_method: "GET" | "POST";
}

interface CatalogResource {
  name: string;
  display_name: string;
  aliases: Record<string, string>;
  description: string;
  version: string;
  last_updated: string;
  operations: CatalogOperation[];
}

interface CatalogCategory extends Omit<CatalogResource, "operations"> {
  resources: CatalogResource[];
}

const categories = await call<CatalogCategory[]>("GET", "/api/catalog/categories");

Go

// Uses the call() helper from quickstart.md. Note: response is an
// ARRAY at the top level, not an object -- decode accordingly.
req, _ := http.NewRequest("GET", baseURL+"/api/catalog/categories", nil)
req.Header.Set("apikey", os.Getenv("ENGINE_API_KEY"))
resp, _ := (&http.Client{Timeout: 30 * time.Second}).Do(req)
defer resp.Body.Close()
var categories []map[string]any
json.NewDecoder(resp.Body).Decode(&categories)
for _, cat := range categories {
    fmt.Println(cat["display_name"])
}

Java

// Uses the call() helper from quickstart.md.
// The response is a JSON array; real callers should deserialize with
// Jackson or Gson rather than the quickstart's minimal extract().
String categories = call("GET", "/api/catalog/categories", null, 3);
System.out.println(categories);

C# (.NET HttpClient)

// Uses the Call() helper from quickstart.md.
var categories = await Call(HttpMethod.Get, "/api/catalog/categories");
foreach (var cat in categories.EnumerateArray())
{
    Console.WriteLine(cat.GetProperty("display_name").GetString());
    foreach (var res in cat.GetProperty("resources").EnumerateArray())
    {
        var resName = res.GetProperty("name").GetString();
        var display = res.GetProperty("display_name").GetString();
        Console.WriteLine($"  - {display}  (/api/{cat.GetProperty("name").GetString()}/{resName})");
    }
}

PowerShell

# Uses the Invoke-Engine helper from quickstart.md.
$categories = Invoke-Engine -Method Get -Path "/api/catalog/categories"
foreach ($cat in $categories) {
    $cat.display_name
    foreach ($res in $cat.resources) {
        "  - $($res.display_name)  (/api/$($cat.name)/$($res.name))"
    }
}

3. Error scenarios

Invalid audience

Send:

curl -sS "https://engine.tripod-health.com/api/catalog/categories?audience=bogus" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (400): same envelope shape as /api/catalog/get with field: "audience".

Intended use

• Rendering a UI that lists categories. Pair with ?audience= to get stakeholder-appropriate labels in one call.
• Looking up the resources inside a category when you know the category but not the resources it contains. Nested resources[] carries everything you need.
• Detecting per-category contract changes. Each category has its own version and last_updated; compare against a cached copy to see which category moved.

Mistaken use

• Do not use this if you also need top-level resources. Composite (cdri), infrastructure (health, version, catalog), and the debug echo are not in this response. Use /api/catalog/get for the full tree.
• Do not use this to look up a single category. When you only need one, /api/catalog/category is lighter and returns the same shape for that one entity.
• Do not parse the response to discover paths. The paths are implicit (/api/<category>/<resource>/<operation>), but /api/catalog/operations returns them pre-assembled, which is what codegen tools should read.
• Do not assume category order is alphabetical. Trinity preserves catalog declaration order; categories appear in the order they were registered, which is stable but not sorted.

Debugging

1. Capture the request ID. On an error, quote the envelope's request_id. A successful response carries none in its body, so capture the X-Request-ID response header (the gateway's trace ID for the call, which support can also look up).
2. 400 ValidationError with field: "audience" — the audience value is unknown. Send one of employee, employer, provider — or drop the parameter entirely.
3. Expected category is missing from the list. That category is not registered in the current deploy. Verify against /api/version/get that you are on the deploy you expect; cross-reference with /api/catalog/get to confirm the category is absent everywhere (not just in this slice).

Rate limits

See rate-limits.md.

Related endpoints

• GET /api/catalog/get — full catalog including top-level resources and root-level version metadata.
• GET /api/catalog/resources — flat resource list, including top-level resources, each carrying its path_prefix.
• GET /api/catalog/operations — flat (method, path, version) tuples. Best surface for codegen.
• GET /api/catalog/category — single category by ?name=.

Change history

Date	Change
2026-04-20	Initial publication.
2026-10-14	Examples recaptured against catalog 0.42.0; counts and resource lists updated. naics now sits in the lookup category with regulations, icd10cm, cpt, and fee_schedule.
2026-10-14	The X-Request-ID response header is the gateway's trace ID for the request and does not match request_id; quote request_id to support.