---
title: "Create Scorecard Item"
method: POST
path: "/scorecards/{id}/items"
tags: ["Scorecard"]
---

# Create Scorecard Item

`POST /scorecards/{id}/items`

Adds a single item (scoring criterion) to the given scorecard. The new item is appended at the next position. Requires an org-scoped API key.

## Path parameters

- `id` string, required

## Request body

- CreateScorecardItemRequest — Payload for creating a single scorecard item.
  - `title` string, required — Human-readable title of the item (1-128 characters, trimmed).
  - `type` 'numeric', required — Scoring type for a scorecard item. Currently only numeric is supported.
  - `weight` integer, required — Relative weight of this item within the scorecard (0-100).
  - `position` integer — Optional position override. When omitted, the item is appended to the end of the scorecard.
  - `expertPrompt` string — Optional expert-mode prompt override (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 `201`

Scorecard item successfully created

- 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 (missing title, weight out of range, numeric min > max, etc.)
- `401` — Authentication failed - valid API key required
- `403` — Caller's API key does not have permission to add items to this scorecard
- `404` — Parent scorecard not found in the caller's organization
- `422` — Request body failed schema-level validation (missing required field, string shorter than minLength, value outside declared range, etc.). Emitted by the swagger validation layer before handler code runs.
- `default` — Unexpected error occurred while creating 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)