# Rubrics ## Create a rubric **post** `/v5/rubrics` Create a rubric, optionally with its initial criteria in the same request. The rubric is created for the caller's account at version 1. If the optional `criteria` field is supplied it must contain at least one entry, and each entry is created as a criterion attached to the new rubric; omit it to create an empty rubric and add criteria later via the criteria endpoint. The response returns the created rubric together with the full detail of any criteria created in this call. ### Body Parameters - `title: string` The rubric title - `criteria: optional array of RubricCriteriaInput` Initial criteria to create with the rubric - `title: string` The Criteria text - `annotations: optional map[unknown]` Free-form metadata for the Criteria - `weight: optional number` Weight multiplier for scoring - `tags: optional array of string` The tags associated with the entity ### Returns - `RubricResponse object { id, created_at, created_by, 7 more }` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" or "service_account"` - `"user"` - `"service_account"` - `object: optional "identity"` - `"identity"` - `tags: array of string` The tags associated with the entity - `title: string` - `version: number` - `archived_at: optional string` - `criteria: optional array of RubricCriteriaResponse or RubricCriteriaSummaryResponse` Full criteria on get, summary (title + weight) on list - `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` - `RubricCriteriaSummaryResponse object { title, weight }` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight: optional number` - `object: optional "rubric"` - `"rubric"` - `updated_at: optional string` ### Example ```http curl https://api.egp.scale.com/v5/rubrics \ -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", "created_by": { "id": "id", "type": "user", "object": "identity" }, "tags": [ "string" ], "title": "title", "version": 0, "archived_at": "2019-12-27T18:11:19.117Z", "criteria": [ { "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 } ], "object": "rubric", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## List rubrics **get** `/v5/rubrics` List the current account's rubrics, paginated. Only the latest version of each rubric is returned, and archived rubrics are excluded (this endpoint has no option to include them). The optional `title` filter matches as a case-insensitive substring, and the optional `tags` filter narrows results to rubrics carrying the given tags. Each returned rubric carries only a slim criteria summary (title and weight per criterion) rather than full criteria; use the get-rubric endpoint to retrieve full criteria detail. ### Query Parameters - `ending_before: optional string` - `limit: optional number` - `sort_by: optional string` - `sort_order: optional SortOrder` - `"asc"` - `"desc"` - `starting_after: optional string` - `tags: optional array of string` Filter by tags - `title: optional string` Filter by title (case-insensitive) ### Returns - `has_more: boolean` Whether there are more items left to be fetched. - `items: array of RubricResponse` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" or "service_account"` - `"user"` - `"service_account"` - `object: optional "identity"` - `"identity"` - `tags: array of string` The tags associated with the entity - `title: string` - `version: number` - `archived_at: optional string` - `criteria: optional array of RubricCriteriaResponse or RubricCriteriaSummaryResponse` Full criteria on get, summary (title + weight) on list - `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` - `RubricCriteriaSummaryResponse object { title, weight }` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight: optional number` - `object: optional "rubric"` - `"rubric"` - `updated_at: optional string` - `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 \ -H "x-api-key: $SGP_API_KEY" ``` #### Response ```json { "has_more": true, "items": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "tags": [ "string" ], "title": "title", "version": 0, "archived_at": "2019-12-27T18:11:19.117Z", "criteria": [ { "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 } ], "object": "rubric", "updated_at": "2019-12-27T18:11:19.117Z" } ], "total": 0, "limit": 0, "object": "list" } ``` ## Get a rubric **get** `/v5/rubrics/{rubric_id}` Retrieve a single rubric with the full detail of its current criteria. Returns the latest version of the rubric along with all of its current (latest-version) criteria in full — not the slim title/weight summary returned by the list endpoint. Archived rubrics remain retrievable through this endpoint even though they are hidden from the list endpoint. ### Path Parameters - `rubric_id: string` ### Returns - `RubricResponse object { id, created_at, created_by, 7 more }` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" or "service_account"` - `"user"` - `"service_account"` - `object: optional "identity"` - `"identity"` - `tags: array of string` The tags associated with the entity - `title: string` - `version: number` - `archived_at: optional string` - `criteria: optional array of RubricCriteriaResponse or RubricCriteriaSummaryResponse` Full criteria on get, summary (title + weight) on list - `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` - `RubricCriteriaSummaryResponse object { title, weight }` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight: optional number` - `object: optional "rubric"` - `"rubric"` - `updated_at: optional string` ### Example ```http curl https://api.egp.scale.com/v5/rubrics/$RUBRIC_ID \ -H "x-api-key: $SGP_API_KEY" ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "tags": [ "string" ], "title": "title", "version": 0, "archived_at": "2019-12-27T18:11:19.117Z", "criteria": [ { "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 } ], "object": "rubric", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Update or restore a rubric **patch** `/v5/rubrics/{rubric_id}` Update a rubric's fields, or restore a previously archived rubric. The request body is a discriminated union. Send `{"restore": true}` to restore an archived rubric (clearing its archived state); send any other field set (such as `title` or `tags`) to update those fields, carrying forward any field not supplied. Both paths are append-only and produce a new version of the rubric rather than mutating the existing row. Updating the fields of an archived rubric is rejected — restore it first. Restoring a rubric that is not archived is a no-op that returns it unchanged without creating a new version. ### Path Parameters - `rubric_id: string` ### Body Parameters - `rubric: object { tags, title } or RestoreRequest` - `PartialRubricRequestBase object { tags, title }` - `tags: optional array of string` The tags associated with the entity - `title: optional string` The rubric title - `RestoreRequest object { restore }` - `restore: true` Set to true to restore the entity from the database. - `true` ### Returns - `RubricResponse object { id, created_at, created_by, 7 more }` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" or "service_account"` - `"user"` - `"service_account"` - `object: optional "identity"` - `"identity"` - `tags: array of string` The tags associated with the entity - `title: string` - `version: number` - `archived_at: optional string` - `criteria: optional array of RubricCriteriaResponse or RubricCriteriaSummaryResponse` Full criteria on get, summary (title + weight) on list - `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` - `RubricCriteriaSummaryResponse object { title, weight }` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight: optional number` - `object: optional "rubric"` - `"rubric"` - `updated_at: optional string` ### Example ```http curl https://api.egp.scale.com/v5/rubrics/$RUBRIC_ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "x-api-key: $SGP_API_KEY" \ -d '{ "tags": [ "string" ], "title": "x" }' ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "tags": [ "string" ], "title": "title", "version": 0, "archived_at": "2019-12-27T18:11:19.117Z", "criteria": [ { "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 } ], "object": "rubric", "updated_at": "2019-12-27T18:11:19.117Z" } ``` ## Archive a rubric **delete** `/v5/rubrics/{rubric_id}` Archive a rubric (soft delete). This is a soft delete, not a permanent one: it records an archived timestamp on the rubric while retaining the rubric and its version history, so it can later be brought back via the restore variant of the update endpoint. An archived rubric is hidden from the list endpoint but stays retrievable by id. The rubric's criteria are left untouched — archiving does not cascade to or delete them. Archiving a rubric that is already archived is rejected. ### Path Parameters - `rubric_id: string` ### Returns - `id: string` - `deleted: boolean` - `object: optional "rubric"` - `"rubric"` ### Example ```http curl https://api.egp.scale.com/v5/rubrics/$RUBRIC_ID \ -X DELETE \ -H "x-api-key: $SGP_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "rubric" } ``` ## Domain Types ### Restore Request - `RestoreRequest object { restore }` - `restore: true` Set to true to restore the entity from the database. - `true` ### Rubric Response - `RubricResponse object { id, created_at, created_by, 7 more }` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" or "service_account"` - `"user"` - `"service_account"` - `object: optional "identity"` - `"identity"` - `tags: array of string` The tags associated with the entity - `title: string` - `version: number` - `archived_at: optional string` - `criteria: optional array of RubricCriteriaResponse or RubricCriteriaSummaryResponse` Full criteria on get, summary (title + weight) on list - `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` - `RubricCriteriaSummaryResponse object { title, weight }` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight: optional number` - `object: optional "rubric"` - `"rubric"` - `updated_at: optional string` ### Rubric Archive Response - `RubricArchiveResponse object { id, deleted, object }` - `id: string` - `deleted: boolean` - `object: optional "rubric"` - `"rubric"` # 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"`