All Rsources

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

Summary

Flat list of every registered resource, each tagged with the category it belongs to (null for top-level resources) and the path_prefix that concrete operations hang off. This is the endpoint codegen tools should read when they want a flat surface for client generation.

Endpoint

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

Purpose

Three use cases:

1. Codegen. A flat resource list with path_prefix values maps one-to-one onto client code: one class / module per resource, methods per operation. Easier to walk than the nested category tree.
2. Cross-category search. When your UI lets a user search "find an instrument whose name mentions fear", this is the surface to scan. One flat array, no nested traversal.
3. Uniform treatment of categorized and top-level resources. The 17 top-level resources — the composites (cdri, phenotype), the analysis and assist surfaces, the infrastructure resources (health, version, catalog), and the debug endpoint — appear here alongside the categorized resources (instruments, encounters, grading, and the five lookup resources). Top-level resources carry category: null.

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. Abbreviated for readability: three of the 38 entries (an instrument, a lookup resource, and a top-level resource), each complete:

[
  {
    "category": "pain",
    "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"
      }
    ],
    "path_prefix": "/api/pain/orebro"
  },
  {
    "category": "lookup",
    "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"
      }
    ],
    "path_prefix": "/api/lookup/naics"
  },
  {
    "category": null,
    "name": "version",
    "display_name": "Version Info",
    "aliases": {
      "employee": "Version",
      "employer": "API Version",
      "provider": "Version"
    },
    "description": "Build metadata for the deployed engine: package version, catalog version, source-control SHA, and deploy timestamp.",
    "version": "0.1.0",
    "last_updated": "2026-04-20",
    "operations": [
      {
        "name": "get",
        "display_name": "Get",
        "aliases": {},
        "description": "Return the engine's current build metadata as JSON. No request body.",
        "version": "0.1.0",
        "last_updated": "2026-04-20",
        "http_method": "GET"
      }
    ],
    "path_prefix": "/api/version"
  }
]

Response fields

The top-level value is a JSON array. Each element:

Field	Type	Always present	Description
category	string | null	Yes	Category name for category-scoped resources (e.g. "pain", "function"). null for top-level resources (for example cdri, recordability, health, version, catalog).
name	string	Yes	URL-safe resource identifier. Unique within its category; names may repeat across categories, but none currently do.
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 of the resource.
version	string (SemVer)	Yes	Resource-level version.
last_updated	string (ISO date, YYYY-MM-DD)	Yes	Last structural change.
operations	array	Yes	Operations registered on this resource (each with a name and http_method).
path_prefix	string	Yes	URL prefix that every operation hangs off. Concrete operation URLs are <path_prefix>/<operation.name>.

path_prefix — the headline field

path_prefix is the authoritative URL fragment for a resource. It already includes the /api/ prefix and the category segment (or elides it for top-level resources):

category	name	path_prefix	Example operation URL
"pain"	"orebro"	/api/pain/orebro	POST /api/pain/orebro/score
"function"	"oswestry"	/api/function/oswestry	POST /api/function/oswestry/score
"lookup"	"naics"	/api/lookup/naics	GET /api/lookup/naics/search
null	"cdri"	/api/cdri	POST /api/cdri/compute
null	"health"	/api/health	GET /api/health/check
null	"debug"	/api/debug	POST /api/debug/echo

Concatenate path_prefix + "/" + operation.name to get a concrete URL. Do not try to reconstruct the prefix from category + name — top-level resources have category: null and would produce wrong URLs under a naive /api/<category>/<name> pattern.

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/resources HTTP/1.1
Host: engine.tripod-health.com
apikey: $ENGINE_API_KEY

Receive (200 OK): a JSON array of resource entries. The live response today contains 38 entries: 21 categorized resources (14 scored instruments, encounters/document, grading/case, and five lookup resources) followed by 17 top-level resources. First entry, verbatim:

{
  "category": "pain",
  "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"
    }
  ],
  "path_prefix": "/api/pain/orebro"
}

2. Calling the endpoint in your language

curl

# Full resource list
curl -sS "https://engine.tripod-health.com/api/catalog/resources" \
  -H "apikey: $ENGINE_API_KEY"

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

Python (requests) — codegen walk

# Uses the call() helper from quickstart.md.
resources = call("GET", "/api/catalog/resources")
for res in resources:
    for op in res["operations"]:
        url = f"https://engine.tripod-health.com{res['path_prefix']}/{op['name']}"
        print(f"{op['http_method']:4} {url}   ({res['display_name']}: {op['name']})")

Node.js (native fetch) — grouped render

// Uses the call() helper from quickstart.md.
const resources = await call("GET", "/api/catalog/resources");
const byCategory = new Map();
for (const r of resources) {
  const key = r.category ?? "(top-level)";
  byCategory.set(key, [...(byCategory.get(key) ?? []), r]);
}
for (const [category, entries] of byCategory) {
  console.log(`# ${category}`);
  for (const r of entries) console.log(`  ${r.path_prefix}  (${r.display_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 ResourceEntry {
  category: string | null;
  name: string;
  display_name: string;
  aliases: Record<string, string>;
  description: string;
  version: string;
  last_updated: string;
  operations: CatalogOperation[];
  path_prefix: string;
}

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

Go

// Uses the call() helper scaffold from quickstart.md. Since the response
// is an array at the top level, decode into a slice directly.
req, _ := http.NewRequest("GET", baseURL+"/api/catalog/resources", nil)
req.Header.Set("apikey", os.Getenv("ENGINE_API_KEY"))
resp, _ := (&http.Client{Timeout: 30 * time.Second}).Do(req)
defer resp.Body.Close()
var resources []map[string]any
json.NewDecoder(resp.Body).Decode(&resources)
for _, res := range resources {
    for _, o := range res["operations"].([]any) {
        op := o.(map[string]any)
        fmt.Printf("%-4v %v%v/%v\n", op["http_method"], baseURL, res["path_prefix"], op["name"])
    }
}

Java

// Uses the call() helper from quickstart.md.
// Response is a top-level JSON array; deserialize with Jackson or Gson
// for a typed traversal.
String resources = call("GET", "/api/catalog/resources", null, 3);
System.out.println(resources);

C# (.NET HttpClient)

// Uses the Call() helper from quickstart.md.
var resources = await Call(HttpMethod.Get, "/api/catalog/resources");
foreach (var res in resources.EnumerateArray())
{
    var pathPrefix = res.GetProperty("path_prefix").GetString();
    foreach (var op in res.GetProperty("operations").EnumerateArray())
    {
        var verb = op.GetProperty("http_method").GetString();
        var name = op.GetProperty("name").GetString();
        Console.WriteLine($"{verb,-4} {pathPrefix}/{name}");
    }
}

PowerShell

# Uses the Invoke-Engine helper from quickstart.md.
$resources = Invoke-Engine -Method Get -Path "/api/catalog/resources"
foreach ($res in $resources) {
    foreach ($op in $res.operations) {
        "{0,-4} {1}/{2}" -f $op.http_method, $res.path_prefix, $op.name
    }
}

3. Error scenarios

Invalid audience

Same envelope shape as /api/catalog/get; field: "audience" with the offending value echoed in message.

Intended use

• Generating a typed client. One class per resource, one method per operation. path_prefix is the URL template; http_method is the verb; operations[].name is the method name.
• Building a "list every endpoint" UI. Every instrument, every composite, every infrastructure endpoint appears in the flat array.
• Searching by name or description across the whole catalog. A linear scan on this response finds a resource in a single pass.

Mistaken use

• Do not reconstruct URLs from category + name manually. Top-level resources (category: null) do not follow the /api/<category>/<name> shape — use path_prefix directly.
• Do not assume array order has semantic meaning. Resources appear in catalog declaration order: category-scoped resources in category order, then top-level resources. The order is stable for a given deploy but it is not, for example, alphabetical or by popularity. Sort client-side if your UI needs a specific ordering.
• Do not use this when you only need operations, not full resource metadata. /api/catalog/operations returns a much smaller response — just (category, resource, operation, method, path, version) tuples.
• Do not use this to look up one resource. /api/catalog/resource returns the full resource entry for a single ?name=, with less data to walk.

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" — send a valid audience or omit the parameter.
3. category: null on a resource you expected to be categorized. Not a bug — the 17 top-level resources (cdri, phenotype, recordability, health, version, catalog, debug, and others) intentionally sit outside any category. Use path_prefix for the URL and stop trying to derive it from category.
4. A resource's path_prefix does not match the URL that worked last week. The catalog is the source of truth for current URLs; compare version or call /api/version/get to see whether a deploy has moved the catalog.

Rate limits

See rate-limits.md.

Related endpoints

• GET /api/catalog/get — full catalog tree (categories nested with resources + top-level resources).
• GET /api/catalog/categories — category tree only (no top-level resources).
• GET /api/catalog/operations — flat (method, path, version) tuples. Smaller response if you only want paths.
• GET /api/catalog/resource — single resource 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.