# Rubrics ## Create a rubric `rubrics.create(RubricCreateParams**kwargs) -> 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 - `title: str` The rubric title - `criteria: Optional[Iterable[RubricCriteriaInputParam]]` Initial criteria to create with the rubric - `title: str` The Criteria text - `annotations: Optional[Dict[str, object]]` Free-form metadata for the Criteria - `weight: Optional[float]` Weight multiplier for scoring - `tags: Optional[Sequence[str]]` The tags associated with the entity ### Returns - `class RubricResponse: …` - `id: str` - `created_at: datetime` - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `tags: Optional[List[str]]` The tags associated with the entity - `title: str` - `version: int` - `archived_at: Optional[datetime]` - `criteria: Optional[List[Criterion]]` Full criteria on get, summary (title + weight) on list - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `class RubricCriteriaSummaryResponse: …` Slim criteria projection for list endpoints (title + weight only). - `title: str` - `weight: Optional[float]` - `object: Optional[Literal["rubric"]]` - `"rubric"` - `updated_at: Optional[datetime]` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) rubric_response = client.rubrics.create( title="x", ) print(rubric_response.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 `rubrics.list(RubricListParams**kwargs) -> SyncCursorPage[RubricResponse]` **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 - `ending_before: Optional[str]` - `limit: Optional[int]` - `sort_by: Optional[str]` - `sort_order: Optional[SortOrder]` - `"asc"` - `"desc"` - `starting_after: Optional[str]` - `tags: Optional[Sequence[str]]` Filter by tags - `title: Optional[str]` Filter by title (case-insensitive) ### Returns - `class RubricResponse: …` - `id: str` - `created_at: datetime` - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `tags: Optional[List[str]]` The tags associated with the entity - `title: str` - `version: int` - `archived_at: Optional[datetime]` - `criteria: Optional[List[Criterion]]` Full criteria on get, summary (title + weight) on list - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `class RubricCriteriaSummaryResponse: …` Slim criteria projection for list endpoints (title + weight only). - `title: str` - `weight: Optional[float]` - `object: Optional[Literal["rubric"]]` - `"rubric"` - `updated_at: Optional[datetime]` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) page = client.rubrics.list() page = page.items[0] print(page.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 `rubrics.retrieve(strrubric_id) -> 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 - `rubric_id: str` ### Returns - `class RubricResponse: …` - `id: str` - `created_at: datetime` - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `tags: Optional[List[str]]` The tags associated with the entity - `title: str` - `version: int` - `archived_at: Optional[datetime]` - `criteria: Optional[List[Criterion]]` Full criteria on get, summary (title + weight) on list - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `class RubricCriteriaSummaryResponse: …` Slim criteria projection for list endpoints (title + weight only). - `title: str` - `weight: Optional[float]` - `object: Optional[Literal["rubric"]]` - `"rubric"` - `updated_at: Optional[datetime]` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) rubric_response = client.rubrics.retrieve( "rubric_id", ) print(rubric_response.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 `rubrics.update(strrubric_id, RubricUpdateParams**kwargs) -> 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 - `rubric_id: str` - `rubric: Rubric` - `class RubricPartialRubricRequestBase: …` - `tags: Optional[Sequence[str]]` The tags associated with the entity - `title: Optional[str]` The rubric title - `class RestoreRequest: …` - `restore: Literal[true]` Set to true to restore the entity from the database. - `true` ### Returns - `class RubricResponse: …` - `id: str` - `created_at: datetime` - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `tags: Optional[List[str]]` The tags associated with the entity - `title: str` - `version: int` - `archived_at: Optional[datetime]` - `criteria: Optional[List[Criterion]]` Full criteria on get, summary (title + weight) on list - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `class RubricCriteriaSummaryResponse: …` Slim criteria projection for list endpoints (title + weight only). - `title: str` - `weight: Optional[float]` - `object: Optional[Literal["rubric"]]` - `"rubric"` - `updated_at: Optional[datetime]` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) rubric_response = client.rubrics.update( rubric_id="rubric_id", rubric={}, ) print(rubric_response.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 `rubrics.archive(strrubric_id) -> 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 - `rubric_id: str` ### Returns - `class RubricArchiveResponse: …` - `id: str` - `deleted: bool` - `object: Optional[Literal["rubric"]]` - `"rubric"` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) response = client.rubrics.archive( "rubric_id", ) print(response.id) ``` #### Response ```json { "id": "id", "deleted": true, "object": "rubric" } ``` ## Domain Types ### Restore Request - `class RestoreRequest: …` - `restore: Literal[true]` Set to true to restore the entity from the database. - `true` ### Rubric Response - `class RubricResponse: …` - `id: str` - `created_at: datetime` - `created_by: Identity` The identity that created the entity. - `id: str` - `type: Literal["user", "service_account"]` - `"user"` - `"service_account"` - `object: Optional[Literal["identity"]]` - `"identity"` - `tags: Optional[List[str]]` The tags associated with the entity - `title: str` - `version: int` - `archived_at: Optional[datetime]` - `criteria: Optional[List[Criterion]]` Full criteria on get, summary (title + weight) on list - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `class RubricCriteriaSummaryResponse: …` Slim criteria projection for list endpoints (title + weight only). - `title: str` - `weight: Optional[float]` - `object: Optional[Literal["rubric"]]` - `"rubric"` - `updated_at: Optional[datetime]` ### Rubric Archive Response - `class RubricArchiveResponse: …` - `id: str` - `deleted: bool` - `object: Optional[Literal["rubric"]]` - `"rubric"` # Criteria ## Add a criterion to a rubric `rubrics.criteria.create(strrubric_id, CriterionCreateParams**kwargs) -> 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 - `rubric_id: str` - `title: str` The Criteria text - `annotations: Optional[Dict[str, object]]` Free-form metadata for the Criteria - `weight: Optional[float]` Weight multiplier for scoring ### Returns - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) rubric_criteria_response = client.rubrics.criteria.create( rubric_id="rubric_id", title="x", ) print(rubric_criteria_response.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 `rubrics.criteria.update(strrubric_criteria_id, CriterionUpdateParams**kwargs) -> 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 - `rubric_id: str` - `rubric_criteria_id: str` - `annotations: Optional[Dict[str, object]]` Free-form metadata for the Criteria - `title: Optional[str]` The Criteria text - `weight: Optional[float]` Weight multiplier for scoring ### Returns - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) rubric_criteria_response = client.rubrics.criteria.update( rubric_criteria_id="rubric_criteria_id", rubric_id="rubric_id", ) print(rubric_criteria_response.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 `rubrics.criteria.list_versions(strrubric_criteria_id, CriterionListVersionsParams**kwargs) -> 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 - `rubric_id: str` - `rubric_criteria_id: str` - `ending_before: Optional[str]` - `limit: Optional[int]` - `sort_by: Optional[str]` - `sort_order: Optional[SortOrder]` - `"asc"` - `"desc"` - `starting_after: Optional[str]` ### Returns - `class CriterionListVersionsResponse: …` - `has_more: bool` Whether there are more items left to be fetched. - `items: List[RubricCriteriaResponse]` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `total: int` The total of items that match the query. This is greater than or equal to the number of items returned. - `limit: Optional[int]` The maximum number of items to return. - `object: Optional[Literal["list"]]` - `"list"` ### Example ```python import os from scale_gp_beta import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) response = client.rubrics.criteria.list_versions( rubric_criteria_id="rubric_criteria_id", rubric_id="rubric_id", ) print(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 - `class RubricCriteriaInput: …` - `title: str` The Criteria text - `annotations: Optional[Dict[str, object]]` Free-form metadata for the Criteria - `weight: Optional[float]` Weight multiplier for scoring ### Rubric Criteria Response - `class RubricCriteriaResponse: …` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` ### Rubric Criteria Summary Response - `class RubricCriteriaSummaryResponse: …` Slim criteria projection for list endpoints (title + weight only). - `title: str` - `weight: Optional[float]` ### Criterion List Versions Response - `class CriterionListVersionsResponse: …` - `has_more: bool` Whether there are more items left to be fetched. - `items: List[RubricCriteriaResponse]` - `id: str` - `created_at: datetime` - `rubric_id: str` - `title: str` - `version: int` - `annotations: Optional[Dict[str, object]]` - `object: Optional[Literal["rubric_criteria"]]` - `"rubric_criteria"` - `weight: Optional[float]` - `total: int` The total of items that match the query. This is greater than or equal to the number of items returned. - `limit: Optional[int]` The maximum number of items to return. - `object: Optional[Literal["list"]]` - `"list"`