All Catalog Categories

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

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 (composite, NAICS reference, 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 organizes domain instruments under a small number of categories (pain, function, psychosocial, fear_avoidance, rtw_belief, occupational, iatrogenic). 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.
X-Request-ID	No	Optional correlation ID. Echoed in the X-Request-ID response header.

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). Truncated for readability:

[
  {
    "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": "0.1.0",
        "last_updated": "2026-04-17",
        "operations": [
          { "name": "questions", "display_name": "Questions", "aliases": {}, "description": "Return the instrument's items, ordering, and answer choices so the caller can render or present them.", "version": "0.1.0", "last_updated": "2026-04-17", "http_method": "GET" },
          { "name": "score", "display_name": "Score", "aliases": {}, "description": "Submit responses to the instrument and receive its score (and profile, where the instrument supports classification).", "version": "0.1.0", "last_updated": "2026-04-17", "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 composites (cdri, phenotype, screen), the NAICS industry reference (naics), 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
X-Request-ID: docs-catalog-categories-canonical

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 (seven 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 X-Request-ID response header.
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.