Scale AI Rubrics API

openapi: 3.2.0
info:
  title: EGP API V5 Rubrics API
  description: This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
- url: https://api.egp.scale.com
security: []
tags:
- name: Rubrics
paths:
  /v5/rubrics/{rubric_id}/criteria:
    post:
      tags:
      - Rubrics
      summary: Add a criterion to a rubric
      description: '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.'
      operationId: POST-V5-/v5/rubrics/rubric_id/criteria
      parameters:
      - name: rubric_id
        in: path
        required: true
        schema:
          title: Rubric Id
          type: string
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RubricCriteriaInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RubricCriteriaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/add-a-criterion-to-a-rubric
  /v5/rubrics/{rubric_id}:
    delete:
      tags:
      - Rubrics
      summary: Archive a rubric
      description: '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.'
      operationId: DELETE-V5-/v5/rubrics/rubric_id
      parameters:
      - name: rubric_id
        in: path
        required: true
        schema:
          title: Rubric Id
          type: string
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse_RubricResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/archive-a-rubric
    get:
      tags:
      - Rubrics
      summary: Get a rubric
      description: '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.'
      operationId: GET-V5-/v5/rubrics/rubric_id
      parameters:
      - name: rubric_id
        in: path
        required: true
        schema:
          title: Rubric Id
          type: string
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RubricResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/get-a-rubric
    patch:
      tags:
      - Rubrics
      summary: Update or restore a rubric
      description: '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.'
      operationId: PATCH-V5-/v5/rubrics/rubric_id
      parameters:
      - name: rubric_id
        in: path
        required: true
        schema:
          title: Rubric Id
          type: string
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RubricUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RubricResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/update-or-restore-a-rubric
  /v5/rubrics:
    post:
      tags:
      - Rubrics
      summary: Create a rubric
      description: '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.'
      operationId: POST-V5-/v5/rubrics
      parameters:
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RubricCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RubricResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/create-a-rubric
    get:
      tags:
      - Rubrics
      summary: List rubrics
      description: '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.'
      operationId: GET-V5-/v5/rubrics
      parameters:
      - name: title
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by title (case-insensitive)
          title: Title
        description: Filter by title (case-insensitive)
      - name: tags
        in: query
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Filter by tags
          title: Tags
        description: Filter by tags
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_RubricResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/list-rubrics
  /v5/rubrics/{rubric_id}/criteria/{rubric_criteria_id}/versions:
    get:
      tags:
      - Rubrics
      summary: List criterion versions
      description: '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.'
      operationId: GET-V5-/v5/rubrics/rubric_id/criteria/rubric_criteria_id/versions
      parameters:
      - name: rubric_id
        in: path
        required: true
        schema:
          title: Rubric Id
          type: string
      - name: rubric_criteria_id
        in: path
        required: true
        schema:
          type: string
          title: Rubric Criteria Id
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_RubricCriteriaResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/list-criterion-versions
  /v5/rubrics/{rubric_id}/criteria/{rubric_criteria_id}:
    patch:
      tags:
      - Rubrics
      summary: Update a criterion
      description: '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.'
      operationId: PATCH-V5-/v5/rubrics/rubric_id/criteria/rubric_criteria_id
      parameters:
      - name: rubric_id
        in: path
        required: true
        schema:
          title: Rubric Id
          type: string
      - name: rubric_criteria_id
        in: path
        required: true
        schema:
          type: string
          title: Rubric Criteria Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RubricCriteriaUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RubricCriteriaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/rubrics/update-a-criterion
components:
  schemas:
    RubricCreateRequest:
      properties:
        tags:
          title: Tags
          description: The tags associated with the entity
          items:
            type: string
          type: array
        title:
          title: Title
          description: The rubric title
          type: string
          minLength: 1
        criteria:
          title: Criteria
          description: Initial criteria to create with the rubric
          items:
            $ref: '#/components/schemas/RubricCriteriaInput'
          type: array
          minItems: 1
      type: object
      required:
      - title
      title: RubricCreateRequest
    PartialRubricRequestBase:
      properties:
        tags:
          title: Tags
          description: The tags associated with the entity
          items:
            type: string
          type: array
        title:
          title: Title
          description: The rubric title
          type: string
          minLength: 1
      additionalProperties: false
      type: object
      title: PartialRubricRequestBase
    IdentityType:
      type: string
      enum:
      - user
      - service_account
      title: IdentityType
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    PaginatedList_RubricResponse_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/RubricResponse'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    RubricCriteriaInput:
      properties:
        title:
          title: Title
          description: The Criteria text
          type: string
          minLength: 1
        weight:
          title: Weight
          description: Weight multiplier for scoring
          type: number
          minimum: 0
        annotations:
          title: Annotations
          description: Free-form metadata for the Criteria
          additionalProperties: true
          type: object
      type: object
      required:
      - title
      title: RubricCriteriaInput
    RubricUpdateRequest:
      anyOf:
      - $ref: '#/components/schemas/PartialRubricRequestBase'
      - $ref: '#/components/schemas/RestoreRequest'
      title: RubricUpdateRequest
    RubricCriteriaUpdateRequest:
      $ref: '#/components/schemas/PartialRubricCriteriaInput'
      title: RubricCriteriaUpdateRequest
    RubricCriteriaSummaryResponse:
      properties:
        title:
          type: string
          title: Title
        weight:
          title: Weight
          type: number
      type: object
      required:
      - title
      title: RubricCriteriaSummaryResponse
      description: Slim criteria projection for list endpoints (title + weight only).
    PaginatedList_RubricCriteriaResponse_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/RubricCriteriaResponse'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    RubricResponse:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: rubric
          title: Object
          default: rubric
        created_by:
          $ref: '#/components/schemas/Identity'
          description: The identity that created the entity.
        tags:
          title: Tags
          description: The tags associated with the entity
          items:
            type: string
          type: array
        version:
          type: integer
          title: Version
        title:
          type: string
          title: Title
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        archived_at:
          title: Archived At
          type: string
          format: date-time
        criteria:
          title: Criteria
          description: Full criteria on get, summary (title + weight) on list
          items:
            anyOf:
            - $ref: '#/components/schemas/RubricCriteriaResponse'
            - $ref: '#/components/schemas/RubricCriteriaSummaryResponse'
          type: array
      type: object
      required:
      - created_by
      - tags
      - id
      - version
      - title
      - created_at
    PartialRubricCriteriaInput:
      properties:
        title:
          title: Title
          description: The Criteria text
          type: string
          minLength: 1
        weight:
          title: Weight
          description: Weight multiplier for scoring
          type: number
          minimum: 0
        annotations:
          title: Annotations
          description: Free-form metadata for the Criteria
          additionalProperties: true
          type: object
      additionalProperties: false
      type: object
      title: PartialRubricCriteriaInput
    RestoreRequest:
      properties:
        restore:
          type: boolean
          const: true
          title: Restore
          description: Set to true to restore the entity from the database.
      additionalProperties: false
      type: object
      required:
      - restore
      title: RestoreRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          title: Error Type
          type: string
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Identity:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: identity
          title: Object
          default: identity
        type:
          $ref: '#/components/schemas/IdentityType'
      type: object
      required:
      - id
      - type
      title: Identity
    RubricCriteriaResponse:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: rubric_criteria
          title: Object
          default: rubric_criteria
        rubric_id:
          title: Rubric Id
          type: string
        version:
          type: integer
          title: Version
        title:
          type: string
          title: Title
        weight:
          title: Weight
          type: number
        annotations:
          title: Annotations
          additionalProperties: true
          type: object
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - rubric_id
      - version
      - title
      - created_at
    DeleteResponse_RubricResponse_:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: rubric
          title: Object
          default: rubric
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - id
      - deleted
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-assembled-from: Per-operation OpenAPI fragments embedded verbatim in docs.gp.scale.com reference pages; source spec https://api.sgp.scale.com/openapi-versions/v5/openapi.json (404 when assembled)