# Rubrics ## Create a rubric `client.rubrics.create(RubricCreateParamsbody, RequestOptionsoptions?): RubricResponse` **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. ### Parameters - `body: RubricCreateParams` - `title: string` The rubric title - `criteria?: Array` Initial criteria to create with the rubric - `title: string` The Criteria text - `annotations?: Record` Free-form metadata for the Criteria - `weight?: number` Weight multiplier for scoring - `tags?: Array` The tags associated with the entity ### Returns - `RubricResponse` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `tags: Array | null` The tags associated with the entity - `title: string` - `version: number` - `archived_at?: string` - `criteria?: Array` Full criteria on get, summary (title + weight) on list - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `RubricCriteriaSummaryResponse` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight?: number` - `object?: "rubric"` - `"rubric"` - `updated_at?: string` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const rubricResponse = await client.rubrics.create({ title: 'x' }); console.log(rubricResponse.id); ``` #### 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 `client.rubrics.list(RubricListParamsquery?, RequestOptionsoptions?): CursorPage` **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. ### Parameters - `query: RubricListParams` - `ending_before?: string` - `limit?: number` - `sort_by?: string` - `sort_order?: SortOrder` - `"asc"` - `"desc"` - `starting_after?: string` - `tags?: Array` Filter by tags - `title?: string` Filter by title (case-insensitive) ### Returns - `RubricResponse` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `tags: Array | null` The tags associated with the entity - `title: string` - `version: number` - `archived_at?: string` - `criteria?: Array` Full criteria on get, summary (title + weight) on list - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `RubricCriteriaSummaryResponse` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight?: number` - `object?: "rubric"` - `"rubric"` - `updated_at?: string` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const rubricResponse of client.rubrics.list()) { console.log(rubricResponse.id); } ``` #### 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 `client.rubrics.retrieve(stringrubricID, RequestOptionsoptions?): RubricResponse` **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. ### Parameters - `rubricID: string` ### Returns - `RubricResponse` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `tags: Array | null` The tags associated with the entity - `title: string` - `version: number` - `archived_at?: string` - `criteria?: Array` Full criteria on get, summary (title + weight) on list - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `RubricCriteriaSummaryResponse` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight?: number` - `object?: "rubric"` - `"rubric"` - `updated_at?: string` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const rubricResponse = await client.rubrics.retrieve('rubric_id'); console.log(rubricResponse.id); ``` #### 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 `client.rubrics.update(stringrubricID, RubricUpdateParamsparams, RequestOptionsoptions?): RubricResponse` **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. ### Parameters - `rubricID: string` - `params: RubricUpdateParams` - `rubric: PartialRubricRequestBase | RestoreRequest` - `PartialRubricRequestBase` - `tags?: Array` The tags associated with the entity - `title?: string` The rubric title - `RestoreRequest` - `restore: true` Set to true to restore the entity from the database. - `true` ### Returns - `RubricResponse` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `tags: Array | null` The tags associated with the entity - `title: string` - `version: number` - `archived_at?: string` - `criteria?: Array` Full criteria on get, summary (title + weight) on list - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `RubricCriteriaSummaryResponse` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight?: number` - `object?: "rubric"` - `"rubric"` - `updated_at?: string` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const rubricResponse = await client.rubrics.update('rubric_id', { rubric: {} }); console.log(rubricResponse.id); ``` #### 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 `client.rubrics.archive(stringrubricID, RequestOptionsoptions?): RubricArchiveResponse` **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. ### Parameters - `rubricID: string` ### Returns - `RubricArchiveResponse` - `id: string` - `deleted: boolean` - `object?: "rubric"` - `"rubric"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const response = await client.rubrics.archive('rubric_id'); console.log(response.id); ``` #### Response ```json { "id": "id", "deleted": true, "object": "rubric" } ``` ## Domain Types ### Restore Request - `RestoreRequest` - `restore: true` Set to true to restore the entity from the database. - `true` ### Rubric Response - `RubricResponse` - `id: string` - `created_at: string` - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `tags: Array | null` The tags associated with the entity - `title: string` - `version: number` - `archived_at?: string` - `criteria?: Array` Full criteria on get, summary (title + weight) on list - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `RubricCriteriaSummaryResponse` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight?: number` - `object?: "rubric"` - `"rubric"` - `updated_at?: string` ### Rubric Archive Response - `RubricArchiveResponse` - `id: string` - `deleted: boolean` - `object?: "rubric"` - `"rubric"` # Criteria ## Add a criterion to a rubric `client.rubrics.criteria.create(stringrubricID, CriterionCreateParamsbody, RequestOptionsoptions?): RubricCriteriaResponse` **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. ### Parameters - `rubricID: string` - `body: CriterionCreateParams` - `title: string` The Criteria text - `annotations?: Record` Free-form metadata for the Criteria - `weight?: number` Weight multiplier for scoring ### Returns - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const rubricCriteriaResponse = await client.rubrics.criteria.create('rubric_id', { title: 'x' }); console.log(rubricCriteriaResponse.id); ``` #### 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 `client.rubrics.criteria.update(stringrubricCriteriaID, CriterionUpdateParamsparams, RequestOptionsoptions?): RubricCriteriaResponse` **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. ### Parameters - `rubricCriteriaID: string` - `params: CriterionUpdateParams` - `rubric_id: string` Path param - `annotations?: Record` Body param: Free-form metadata for the Criteria - `title?: string` Body param: The Criteria text - `weight?: number` Body param: Weight multiplier for scoring ### Returns - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const rubricCriteriaResponse = await client.rubrics.criteria.update('rubric_criteria_id', { rubric_id: 'rubric_id', }); console.log(rubricCriteriaResponse.id); ``` #### 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 `client.rubrics.criteria.listVersions(stringrubricCriteriaID, CriterionListVersionsParamsparams, RequestOptionsoptions?): CriterionListVersionsResponse` **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. ### Parameters - `rubricCriteriaID: string` - `params: CriterionListVersionsParams` - `rubric_id: string` Path param - `ending_before?: string` Query param - `limit?: number` Query param - `sort_by?: string` Query param - `sort_order?: SortOrder` Query param - `"asc"` - `"desc"` - `starting_after?: string` Query param ### Returns - `CriterionListVersionsResponse` - `has_more: boolean` Whether there are more items left to be fetched. - `items: Array` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `total: number` The total of items that match the query. This is greater than or equal to the number of items returned. - `limit?: number` The maximum number of items to return. - `object?: "list"` - `"list"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const response = await client.rubrics.criteria.listVersions('rubric_criteria_id', { rubric_id: 'rubric_id', }); console.log(response.has_more); ``` #### 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` - `title: string` The Criteria text - `annotations?: Record` Free-form metadata for the Criteria - `weight?: number` Weight multiplier for scoring ### Rubric Criteria Response - `RubricCriteriaResponse` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` ### Rubric Criteria Summary Response - `RubricCriteriaSummaryResponse` Slim criteria projection for list endpoints (title + weight only). - `title: string` - `weight?: number` ### Criterion List Versions Response - `CriterionListVersionsResponse` - `has_more: boolean` Whether there are more items left to be fetched. - `items: Array` - `id: string` - `created_at: string` - `rubric_id: string` - `title: string` - `version: number` - `annotations?: Record` - `object?: "rubric_criteria"` - `"rubric_criteria"` - `weight?: number` - `total: number` The total of items that match the query. This is greater than or equal to the number of items returned. - `limit?: number` The maximum number of items to return. - `object?: "list"` - `"list"`