Claim-Cost Categories

Status: beta Category: claimcost Added: 2026-07-06 Last reviewed: 2026-07-06

Summary

Return the two input vocabularies the claim-cost classifier accepts: the list of valid injury values and the list of valid bodyPart values. Call this to validate a value before you classify, or to populate a dropdown, so a /api/claimcost/classify call never fails on an unrecognized category.

The lists are sourced live from the trained model, so they always match exactly what classify will accept — a retrain that changes the vocabulary changes this response with it.

Endpoint

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

Purpose

classify matches its injury and bodyPart inputs against fixed vocabularies and returns 400 for anything it does not recognize. This endpoint is how you discover those vocabularies without guessing: fetch the lists once, cache them, and validate or drive UI selection against them. It exists to prevent wasted classify calls, so it is priced at the credit floor.

Authentication

Send a valid API key in the apikey header. A missing or unknown key returns 401 Unauthenticated at the gateway before the request reaches the engine. See authentication.

Request

Headers

Header	Required	Description
apikey	Yes	Consumer API key.
X-Request-ID	No	Optional client-generated correlation ID. If omitted, one is generated and echoed in the X-Request-ID response header.

Path parameters

None.

Query parameters

None.

Body

None — GET endpoint.

Response

Success — 200 OK

{
  "model": "claimcost",
  "version": "0.2.0",
  "injuries": [
    "ABRASION",
    "CARPAL TUNNEL SYNDROME",
    "CONTUSION",
    "FRACTURE",
    "LACERATION",
    "STRAIN OR TEAR"
  ],
  "bodyParts": [
    "ANKLE",
    "KNEE",
    "LOW BACK AREA",
    "MULTIPLE BODY PARTS",
    "SHOULDER(S)",
    "WRIST"
  ]
}

The injuries and bodyParts arrays above are abbreviated for readability. The live response returns the complete vocabularies (over one hundred injury values and dozens of body-part values), sorted alphabetically.

Response fields

Field	Type	Always present	Description
model	string	Yes	The model these vocabularies belong to (claimcost).
version	string	Yes	The model version the lists were sourced from. Reported by the model; expect it to advance as the model is retrained.
injuries	array of string	Yes	Every accepted injury value, sorted alphabetically. Values are uppercase as stored, but classify accepts any casing.
bodyParts	array of string	Yes	Every accepted bodyPart value, sorted alphabetically. Values are uppercase as stored, but classify accepts any casing.

Match your input against these values by word, case-insensitively. The values are returned uppercase, but classify case-folds its inputs, so you may send "low back area" or "LOW BACK AREA" — the words must match, the casing need not.

Status codes

Code	Meaning	When
200	OK	Vocabularies returned.
401	Unauthenticated	Missing or invalid API key.
402	PaymentRequired	Insufficient credits or an exhausted budget. See credits.md.
429	RateLimited	Per-consumer rate limit exceeded. See Retry-After.
500	InternalError	Unexpected server-side failure. Include request_id when reporting.
502	UpstreamError	The model service was unreachable or returned an unexpected shape.
503	ServiceUnavailable	A required dependency is temporarily unhealthy.
504	UpstreamTimeout	The model call exceeded the engine's budget.

Error envelope

All non-2xx responses use the uniform envelope:

{
  "timestamp": "2026-07-06T17:32:10.812Z",
  "error": "UpstreamError",
  "message": "claim-cost model service failed: ...",
  "request_id": "8f2c3b1d-5e4a-4a9c-9b1e-2a7f1d3e4c5b"
}

See errors.md for the full code list.

What a call costs

A successful call costs 1 credit — the credit floor. It is intentionally the cheapest call in the catalog: it exists to prevent wasted classify calls, so it must not discourage use. The exact amount is returned in the X-Credits-Used header. See credits.md.

Examples

curl

curl -sS "https://engine.tripod-health.com/api/claimcost/categories" \
  -H "apikey: $ENGINE_API_KEY"

Python (requests)

# Uses the call() helper from quickstart.md.
cats = call("GET", "/api/claimcost/categories")
valid_injuries = {v.upper() for v in cats["injuries"]}
assert "STRAIN OR TEAR" in valid_injuries

Node.js (native fetch)

// Uses the call() helper from quickstart.md.
const cats = await call("GET", "/api/claimcost/categories");
const validBodyParts = new Set(cats.bodyParts.map((v) => v.toUpperCase()));
console.log(validBodyParts.has("LOW BACK AREA"));

Intended use

• Input validation before a classify call, to turn an unknown category into a client-side error instead of a billed 400.
• Populating a dropdown or autocomplete so a user can only pick a value the model recognizes.
• Detecting a vocabulary change after a retrain — compare the returned lists against your cached copy.

Mistaken use

• Do not hard-code the lists and stop calling this. The vocabularies can change on a retrain (the version field tells you when). Cache with a refresh, do not freeze.
• Do not classify from this endpoint. It only lists accepted values; the classification is /api/claimcost/classify.

Debugging

1. Capture the request_id from the response body or X-Request-ID header.
2. 502 UpstreamError. The model service is unreachable or returned an unexpected shape. Retry with backoff; if it persists, check model-services-health.md and quote the request_id in a ticket.
3. 402 PaymentRequired. Out of credits or budget; see credits.md.

Rate limits

Per-consumer limits are enforced at the gateway; see rate-limits.md. Responses include the standard RateLimit-* headers.

Related

• claimcost-classify.md — the classification itself; validate inputs against this endpoint's lists first.
• credits.md — fixed-cost billing and the X-Credits-* headers.
• conventions.md — request IDs and timestamps.
• errors.md — error envelope and code list.

Change history

Date	Change
2026-07-06	Initial publication (beta).