Single Grade Item

Status: beta Category: grading Added: 2026-06-22 Last reviewed: 2026-07-01

Summary

Grades a care team for a single case on one priority only, returning the same per-member, role-filtered shape as /grading/case/composite with each member's priorities array narrowed to the one priority you called. Use it when you need a single priority's view — for example a timeliness-only tile — without grading or transferring the rest.

The request body, signal bundle, role archetypes, and response fields are identical to the composite endpoint. This page documents only what differs: the URL, the priority set, and the filtered response. Read grading-case-composite.md for the full contract.

Endpoint

Field	Value
Method	POST
Path	/api/grading/case/{priority_key}
Full URL	https://engine.tripod-health.com/api/grading/case/{priority_key}
Authentication	API key (required)
Request body	application/json
Response body	application/json
Idempotent	No
Rate-limited	Yes

Priorities

{priority_key} must be exactly one of the seven priority keys:

Priority key	Grades
clinical_effectiveness	Accuracy of clinical decision-making and risk-adjusted outcomes.
care_quality	How well care was delivered against standards.
timeliness	Speed of the team's own actions (excludes external wait time).
patient_experience	Patient-perceived quality and engagement.
employer_experience	Client satisfaction with case management and resolution.
resource_utilization	Clinical appropriateness of resource use.
case_handling	Operational coordination and communication closure.

Any other final path segment does not exist and returns 404 at the gateway.

Authentication

Identical to the composite endpoint — a valid API key in the apikey header. See authentication.

Request

The body is exactly the same shape as /grading/case/composite: case_id, care_team, optional context, the signals bundle, and the optional priorities lever. You may send the same body to either endpoint.

The priorities lever is still accepted on a single-priority call, but with only one priority graded it has no effect on that priority's own score. Send it for parity with composite calls; it does not change a single-priority result.

The de-identification requirement applies unchanged.

Response

Success — 200 OK

Same top-level shape as the composite, except each member's priorities array contains at most the one priority you called. A member whose role is not graded on that priority comes back with an empty priorities array and not_scored_reason: "insufficient_signal".

The example below is a real production capture of POST /api/grading/case/timeliness for a single frontline member with full timeline signals.

{
  "members": [
    {
      "clinician_user_id_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "role": "frontline",
      "score": 1,
      "coverage": 1,
      "not_scored_reason": null,
      "priorities": [
        {
          "key": "timeliness",
          "score": 1,
          "coverage": 1,
          "not_scored_reason": null,
          "kpis": [
            { "key": "decision_latency", "score": 1, "covered": true, "role_weight": 0.6, "rationale": "Decision in 11.0h active after info available: 1.00." },
            { "key": "documentation_timeliness", "score": 1, "covered": true, "role_weight": 0.58, "rationale": "1 note(s) signed promptly: 1.00." },
            { "key": "intervention_timing", "score": 1, "covered": true, "role_weight": 0.58, "rationale": "Intervention 10.0h active after decision: 1.00." },
            { "key": "responsiveness_consistency", "score": 1, "covered": true, "role_weight": 0.64, "rationale": "4 response measures, spread 0.00: 1.00." },
            { "key": "time_to_first_response", "score": 1, "covered": true, "role_weight": 1, "rationale": "First response in 2.0h active (target 4.0h): 1.00." }
          ]
        }
      ]
    }
  ],
  "matrix_version": "2026-06-22-first-pass",
  "catalog_version": "0.14.0",
  "request_id": "docs-grading-case-timeliness",
  "timestamp": "2026-06-22T22:23:00.000000+00:00"
}

Response fields

Identical to /grading/case/composite. Note that on a single-priority call, members[].score reflects only the one priority graded, and members[].coverage is measured over that priority alone.

Status codes

Same as the composite endpoint, with one note: an unknown {priority_key} segment returns 404, because only the seven listed priorities (and composite) are routed.

Examples

curl

curl -sS -X POST "https://engine.tripod-health.com/api/grading/case/timeliness" \
  -H "apikey: $ENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: docs-grading-case-timeliness" \
  -d '{
    "case_id": "opaque-case-token",
    "care_team": [
      { "clinician_user_id_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "role": "frontline" }
    ],
    "signals": {
      "timeline": [
        { "kind": "case_opened",   "actor_hash": null, "at": "2026-06-01T00:00:00Z", "ref": null },
        { "kind": "first_contact", "actor_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "at": "2026-06-01T02:00:00Z", "ref": "fc1" }
      ]
    }
  }'

Python (requests)

# Uses the call() helper from quickstart.md. Same body as the composite call;
# only the path segment changes.
result = call("POST", "/api/grading/case/case_handling", body)
for member in result["members"]:
    handling = next((p for p in member["priorities"] if p["key"] == "case_handling"), None)
    print(f"{member['role']}: {handling['score'] if handling else 'n/a'}")

Intended use

• Render a single-priority view (one dashboard tile, one report column) without computing the full grade.
• Poll one priority that is still maturing — for example re-call case_handling as coordination loops close — without recomputing the rest.

Mistaken use

• Need more than one priority? Call /grading/case/composite once instead of making several single-priority calls — it grades all seven in a single request.
• Do not expect a priority a role does not own. A member graded on a priority their role is not responsible for returns an empty priorities array; this is correct, not an error.
• The remaining composite mistaken-use notes (correlation ID in the header not the body, no raw identifiers, null is not a zero) apply here too.

Debugging

Identical to the composite debugging checklist. Additionally, if you get a 404, confirm the final path segment is exactly one of the seven priority keys listed above.

Rate limits

Per-consumer limits are enforced at the gateway; see rate limits.

Related

• grading-case-composite.md — grade all seven priorities at once (the full contract).
• conventions.md — cross-cutting request/response rules.
• errors.md — error envelope and taxonomy.

Change history

Date	Change
2026-06-22	Initial publication (beta).
2026-07-01	Renamed path from /api/case_outcome/{priority} to /api/grading/case/{priority_key}. Contract unchanged.