# Criteria

## Add a criterion to a rubric

**post** `/v5/rubrics/{rubric_id}/criteria`

Add a single criterion to an existing rubric.

Creates a new criterion at version 1 under the given rubric. Criteria are
versioned independently of the rubric they belong to. The request is rejected
if the target rubric is archived.

### Path Parameters

- `rubric_id: string`

### Body Parameters

- `title: string`

  The Criteria text

- `annotations: optional map[unknown]`

  Free-form metadata for the Criteria

- `weight: optional number`

  Weight multiplier for scoring

### Returns

- `RubricCriteriaResponse object { id, created_at, rubric_id, 5 more }`

  - `id: string`

  - `created_at: string`

  - `rubric_id: string`

  - `title: string`

  - `version: number`

  - `annotations: optional map[unknown]`

  - `object: optional "rubric_criteria"`

    - `"rubric_criteria"`

  - `weight: optional number`

### Example

```http
curl https://api.egp.scale.com/v5/rubrics/$RUBRIC_ID/criteria \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "title": "x"
        }'
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "rubric_id": "rubric_id",
  "title": "title",
  "version": 0,
  "annotations": {
    "foo": "bar"
  },
  "object": "rubric_criteria",
  "weight": 0
}
```

## Update a criterion

**patch** `/v5/rubrics/{rubric_id}/criteria/{rubric_criteria_id}`

Apply a partial update to a criterion, creating a new version.

Updates are append-only: rather than overwriting the criterion in place, each
update inserts a new immutable version with an incremented version number, so
every prior state stays available through the versions endpoint. Fields not
supplied are carried forward from the current version. The request is rejected
if the criterion does not belong to the rubric named in the path.

### Path Parameters

- `rubric_id: string`

- `rubric_criteria_id: string`

### Body Parameters

- `annotations: optional map[unknown]`

  Free-form metadata for the Criteria

- `title: optional string`

  The Criteria text

- `weight: optional number`

  Weight multiplier for scoring

### Returns

- `RubricCriteriaResponse object { id, created_at, rubric_id, 5 more }`

  - `id: string`

  - `created_at: string`

  - `rubric_id: string`

  - `title: string`

  - `version: number`

  - `annotations: optional map[unknown]`

  - `object: optional "rubric_criteria"`

    - `"rubric_criteria"`

  - `weight: optional number`

### Example

```http
curl https://api.egp.scale.com/v5/rubrics/$RUBRIC_ID/criteria/$RUBRIC_CRITERIA_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "rubric_id": "rubric_id",
  "title": "title",
  "version": 0,
  "annotations": {
    "foo": "bar"
  },
  "object": "rubric_criteria",
  "weight": 0
}
```

## List criterion versions

**get** `/v5/rubrics/{rubric_id}/criteria/{rubric_criteria_id}/versions`

List the full version history of a single criterion, paginated.

Because criterion updates are append-only, this returns one entry per version,
exposing every prior state of the criterion, ordered by version descending
(newest first) by default. The request is rejected if the criterion does not
belong to the rubric named in the path.

### Path Parameters

- `rubric_id: string`

- `rubric_criteria_id: string`

### Query Parameters

- `ending_before: optional string`

- `limit: optional number`

- `sort_by: optional string`

- `sort_order: optional SortOrder`

  - `"asc"`

  - `"desc"`

- `starting_after: optional string`

### Returns

- `has_more: boolean`

  Whether there are more items left to be fetched.

- `items: array of RubricCriteriaResponse`

  - `id: string`

  - `created_at: string`

  - `rubric_id: string`

  - `title: string`

  - `version: number`

  - `annotations: optional map[unknown]`

  - `object: optional "rubric_criteria"`

    - `"rubric_criteria"`

  - `weight: optional number`

- `total: number`

  The total of items that match the query. This is greater than or equal to the number of items returned.

- `limit: optional number`

  The maximum number of items to return.

- `object: optional "list"`

  - `"list"`

### Example

```http
curl https://api.egp.scale.com/v5/rubrics/$RUBRIC_ID/criteria/$RUBRIC_CRITERIA_ID/versions \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "rubric_id": "rubric_id",
      "title": "title",
      "version": 0,
      "annotations": {
        "foo": "bar"
      },
      "object": "rubric_criteria",
      "weight": 0
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}
```

## Domain Types

### Rubric Criteria Input

- `RubricCriteriaInput object { title, annotations, weight }`

  - `title: string`

    The Criteria text

  - `annotations: optional map[unknown]`

    Free-form metadata for the Criteria

  - `weight: optional number`

    Weight multiplier for scoring

### Rubric Criteria Response

- `RubricCriteriaResponse object { id, created_at, rubric_id, 5 more }`

  - `id: string`

  - `created_at: string`

  - `rubric_id: string`

  - `title: string`

  - `version: number`

  - `annotations: optional map[unknown]`

  - `object: optional "rubric_criteria"`

    - `"rubric_criteria"`

  - `weight: optional number`

### Rubric Criteria Summary Response

- `RubricCriteriaSummaryResponse object { title, weight }`

  Slim criteria projection for list endpoints (title + weight only).

  - `title: string`

  - `weight: optional number`

### Criterion List Versions Response

- `CriterionListVersionsResponse object { has_more, items, total, 2 more }`

  - `has_more: boolean`

    Whether there are more items left to be fetched.

  - `items: array of RubricCriteriaResponse`

    - `id: string`

    - `created_at: string`

    - `rubric_id: string`

    - `title: string`

    - `version: number`

    - `annotations: optional map[unknown]`

    - `object: optional "rubric_criteria"`

      - `"rubric_criteria"`

    - `weight: optional number`

  - `total: number`

    The total of items that match the query. This is greater than or equal to the number of items returned.

  - `limit: optional number`

    The maximum number of items to return.

  - `object: optional "list"`

    - `"list"`