All Rsources

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

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 composites (cdri, phenotype, screen), the NAICS industry reference (naics), the infrastructure resources (health, version, catalog), and the debug endpoint appear here alongside instruments, each with category: null to mark them.

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

[
  {
    "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": "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" }
    ],
    "path_prefix": "/api/pain/orebro"
  },
  {
    "category": null,
    "name": "cdri",
    "display_name": "Composite Disability Risk Index",
    "aliases": { "employee": "Recovery Outlook", "employer": "Disability Risk Index", "provider": "CDRI" },
    "description": "Composite Disability Risk Index: integrated cross-instrument risk scoring.",
    "version": "0.1.0",
    "last_updated": "2026-04-17",
    "operations": [
      { "name": "compute", "display_name": "Compute", "aliases": {}, "description": "Compute composite scoring.", "version": "0.1.0", "last_updated": "2026-04-17", "http_method": "POST" }
    ],
    "path_prefix": "/api/cdri"
  }
]

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 (cdri, phenotype, screen, naics, health, version, catalog, debug).
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	GET /api/function/oswestry/questions
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
X-Request-ID: docs-catalog-resources-canonical

Receive (200 OK): a JSON array of resource entries. The live response today contains 22 entries (14 scored instruments + 3 composites + 1 NAICS industry reference + 4 infrastructure/debug 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": "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"
    }
  ],
  "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 X-Request-ID response header.
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 — cdri, phenotype, screen, naics, health, version, catalog, and debug intentionally sit at the top level. 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.