---
title: "Update Scorecard Item"
method: PATCH
path: "/scorecards/{id}/items/{itemId}"
tags: ["Scorecard"]
---

# Update Scorecard Item

`PATCH /scorecards/{id}/items/{itemId}`

Partially updates a scorecard item. Only fields present in the body are modified; omitted fields retain current values. Requires an org-scoped API key.

## Path parameters

- `id` string, required
- `itemId` string, required

## Request body

- UpdateScorecardItemRequest — Partial update payload for a scorecard item. All fields optional; at least one required.
  - `title` string — Replacement title (1-128 characters, trimmed).
  - `weight` integer — Replacement weight (0-100).
  - `position` integer — Replacement position. Reordering siblings is the caller's responsibility; overlapping positions may produce undefined ordering.
  - `expertPrompt` string — Replacement expert-mode prompt (0-8000 characters).
  - `metadata` ScorecardItemMetadata — Type-discriminated metadata for a scorecard item. Numeric items populate numericMetadata.
    - `numericMetadata` NumericScorecardMetadata — Configuration for a numeric scorecard item including score range and per-bucket criteria.
      - `min` integer, nullable — Minimum score value (inclusive).
      - `middle` integer, nullable — Optional middle score anchor. When present, a middleCriteria is required.
      - `max` integer, nullable — Maximum score value (inclusive).
      - `minCriteria` string — Guidance for the evaluator describing what a minimum score looks like.
      - `middleCriteria` string — Guidance for the evaluator describing what the middle score looks like. Required when middle is set.
      - `maxCriteria` string — Guidance for the evaluator describing what a maximum score looks like.

## Response `200`

Scorecard item successfully updated

- ScorecardItemResponse — Single-resource envelope wrapping a ScorecardItem.
  - `data` ScorecardItem, required — A single scoring criterion belonging to a scorecard template.
    - `uuid` string, required — Scorecard item UUID.
    - `scorecardUUID` string, required — UUID of the parent scorecard.
    - `title` string, required — Human-readable title of the item (1-128 characters).
    - `type` 'numeric', required — Scoring type for a scorecard item. Currently only numeric is supported.
    - `position` integer, required — Zero-indexed ordering position among siblings on the parent scorecard.
    - `weight` integer, required — Relative weight of this item within the scorecard (0-100).
    - `version` integer, required — Monotonic version counter incremented on each update.
    - `expertPrompt` string — Optional expert-mode prompt override for this specific item.
    - `metadata` ScorecardItemMetadata — Type-discriminated metadata for a scorecard item. Numeric items populate numericMetadata.
      - `numericMetadata` NumericScorecardMetadata — Configuration for a numeric scorecard item including score range and per-bucket criteria.
        - `min` integer, nullable — Minimum score value (inclusive).
        - `middle` integer, nullable — Optional middle score anchor. When present, a middleCriteria is required.
        - `max` integer, nullable — Maximum score value (inclusive).
        - `minCriteria` string — Guidance for the evaluator describing what a minimum score looks like.
        - `middleCriteria` string — Guidance for the evaluator describing what the middle score looks like. Required when middle is set.
        - `maxCriteria` string — Guidance for the evaluator describing what a maximum score looks like.
    - `createdAt` string, date-time, required — Timestamp when the item was created.
    - `lastUpdatedAt` string, date-time, required — Timestamp of the most recent update.

## Other responses

- `400` — Invalid request body (empty patch, title out of range, weight out of range, etc.)
- `401` — Authentication failed - valid API key required
- `403` — Caller's API key does not have permission to modify this scorecard item
- `404` — Scorecard or item not found in the caller's organization
- `422` — Request body failed schema-level validation (string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.
- `default` — Unexpected error occurred while updating the scorecard item

---

[API](https://skmtc.net/attention/apis/attention-service-v2.md) · [All operations](https://skmtc.net/attention/apis/attention-service-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attention/attention-service-v2/revisions/5de55d3804cf/schema)