Scale AI Span Assessment API

openapi: 3.2.0
info:
  title: EGP API V5 Span Assessment 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: Span Assessment
paths:
  /v5/span-assessments:
    post:
      tags:
      - Span Assessment
      summary: Create span assessment
      description: 'Attach a new assessment to a span within a trace.


        A span assessment records feedback on a single span''s output. Its

        assessment_type selects one of comment, rating (an integer 1-5), approval

        (approved or rejected), rubric (key-value rule pairs), metadata (arbitrary

        JSON), or overwrite (a corrected span output), and exactly the content field

        matching that type must be supplied; a free-text comment may additionally

        accompany any type. trace_id is required, while span_id is optional and, when

        omitted, the assessment is attached to the trace''s root span. The call returns

        404 if the given span_id and trace_id do not identify an existing span, or if

        no root span is found for the trace. At most one user per span may hold an

        overwrite assessment, so creating an overwrite for a span another user has

        already overwritten returns 409. Use the list endpoint to read a span''s or

        trace''s existing assessments.'
      operationId: POST-V5-/v5/span-assessments
      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/SpanAssessmentCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanAssessment'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/span-assessment/create-span-assessment
    get:
      tags:
      - Span Assessment
      summary: List span or trace assessments
      description: 'Return the assessments attached to a given span or trace.


        Results are scoped to the caller''s account. Exactly one of span_id or

        trace_id must be supplied as a query parameter, and a request providing

        neither returns 400. Filtering by trace_id returns assessments across every

        span of that trace, whereas span_id returns only that span''s assessments; an

        optional assessment_type narrows the results to a single type. Use the

        get-by-id endpoint when you already have a specific assessment id.'
      operationId: GET-V5-/v5/span-assessments
      parameters:
      - name: span_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by span ID. Either span_id or trace_id must be provided as a query parameter.
          title: Span Id
        description: Filter by span ID. Either span_id or trace_id must be provided as a query parameter.
      - name: trace_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by trace ID. Either span_id or trace_id must be provided as a query parameter.
          title: Trace Id
        description: Filter by trace ID. Either span_id or trace_id must be provided as a query parameter.
      - name: assessment_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AssessmentType'
          - type: 'null'
          description: Filter by assessment type
          title: Assessment Type
        description: Filter by assessment type
      - 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/APIList_SpanAssessment_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/span-assessment/list-span-or-trace-assessments
  /v5/span-assessments/{span_assessment_id}:
    get:
      tags:
      - Span Assessment
      summary: Get span assessment by ID
      description: 'Retrieve a single span assessment by its identifier.


        Returns the assessment''s type and content fields, the span and trace it is

        attached to, and the identity that created it. Returns 404 if no assessment

        with that id exists for the caller''s account. Use the list endpoint instead

        when you have a span or trace id rather than an assessment id.'
      operationId: GET-V5-/v5/span-assessments/span_assessment_id
      parameters:
      - name: span_assessment_id
        in: path
        required: true
        schema:
          type: string
          title: Span Assessment Id
      - 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/SpanAssessment'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/span-assessment/get-span-assessment-by-id
    delete:
      tags:
      - Span Assessment
      summary: Permanently delete span assessment
      description: 'Permanently delete a span assessment by its identifier.


        This is a hard delete: the assessment row is removed rather than archived, so

        it cannot be restored afterward. The response echoes the deleted assessment''s

        id. Returns 404 if no assessment with that id exists for the caller''s account.'
      operationId: DELETE-V5-/v5/span-assessments/span_assessment_id
      parameters:
      - name: span_assessment_id
        in: path
        required: true
        schema:
          type: string
          title: Span Assessment Id
      - 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_SpanAssessment_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/span-assessment/permanently-delete-span-assessment
    patch:
      tags:
      - Span Assessment
      summary: Update span assessment
      description: 'Update the content of an existing span assessment.


        Only the assessment''s original creator may update it; a request from any

        other identity returns 403. Supplied fields overwrite the stored values and

        the merged result is re-validated against the assessment''s type, so the

        content must stay consistent with assessment_type (the matching content field

        present and no conflicting fields set) or the call returns 422. The span and

        trace an assessment is attached to cannot be changed through this endpoint.

        Returns 404 if no assessment with that id exists for the caller''s account.'
      operationId: PATCH-V5-/v5/span-assessments/span_assessment_id
      parameters:
      - name: span_assessment_id
        in: path
        required: true
        schema:
          type: string
          title: Span Assessment 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/SpanAssessmentUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanAssessment'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/span-assessment/update-span-assessment
components:
  schemas:
    SpanAssessmentCreateRequest:
      properties:
        comment:
          title: Comment
          description: Raw text feedback
          type: string
        rating:
          title: Rating
          description: Numerical rating (1-5)
          type: integer
          maximum: 5
          minimum: 1
        approval:
          $ref: '#/components/schemas/ApprovalStatus'
          description: Approval status (approved/rejected)
        rubric:
          title: Rubric
          description: Rule key-value pairs for rubric evaluation
          additionalProperties:
            type: string
          type: object
        metadata:
          title: Metadata
          description: Arbitrary JSON object for additional data
          additionalProperties: true
          type: object
        overwrite:
          title: Overwrite
          description: User corrections to span output
          additionalProperties: true
          type: object
        assessment_type:
          $ref: '#/components/schemas/AssessmentType'
          description: Type of assessment
        span_id:
          title: Span Id
          description: The ID of the span this assessment is attached to. If omitted, the assessment is attached to the root span of the trace.
          type: string
        trace_id:
          type: string
          title: Trace Id
          description: The ID of the trace this assessment is attached to
      additionalProperties: false
      type: object
      required:
      - assessment_type
      - trace_id
      title: SpanAssessmentCreateRequest
      description: Request model for creating span assessment
    ApprovalStatus:
      type: string
      enum:
      - approved
      - rejected
      title: ApprovalStatus
      description: Status options for approval assessments
    APIList_SpanAssessment_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/SpanAssessment'
          type: array
          title: Items
      type: object
      required:
      - items
    SpanAssessment:
      properties:
        object:
          type: string
          const: span.assessment
          title: Object
          default: span.assessment
        comment:
          title: Comment
          description: Raw text feedback
          type: string
        rating:
          title: Rating
          description: Numerical rating (1-5)
          type: integer
          maximum: 5
          minimum: 1
        approval:
          $ref: '#/components/schemas/ApprovalStatus'
          description: Approval status (approved/rejected)
        rubric:
          title: Rubric
          description: Rule key-value pairs for rubric evaluation
          additionalProperties:
            type: string
          type: object
        metadata:
          title: Metadata
          description: Arbitrary JSON object for additional data
          additionalProperties: true
          type: object
        overwrite:
          title: Overwrite
          description: User corrections to span output
          additionalProperties: true
          type: object
        assessment_id:
          type: string
          title: Assessment Id
          description: Unique identifier for the assessment
        trace_id:
          type: string
          title: Trace Id
          description: The trace this assessment is attached to
        span_id:
          type: string
          title: Span Id
          description: The span this assessment is attached to
        created_by:
          type: string
          title: Created By
          description: User who submitted the assessment
        assessment_type:
          $ref: '#/components/schemas/AssessmentType'
          description: Type of assessment
        account_id:
          title: Account Id
          description: Account this assessment belongs to
          type: string
        created_at:
          title: Created At
          description: When this assessment was created
          type: string
          format: date-time
        updated_at:
          title: Updated At
          description: When this assessment was last updated
          type: string
          format: date-time
      additionalProperties: true
      type: object
      required:
      - assessment_id
      - trace_id
      - span_id
      - created_by
      - assessment_type
      description: Response model for span assessment
    SpanAssessmentUpdateRequest:
      properties:
        comment:
          title: Comment
          description: Raw text feedback
          type: string
        rating:
          title: Rating
          description: Numerical rating (1-5)
          type: integer
          maximum: 5
          minimum: 1
        approval:
          $ref: '#/components/schemas/ApprovalStatus'
          description: Approval status (approved/rejected)
        rubric:
          title: Rubric
          description: Rule key-value pairs for rubric evaluation
          additionalProperties:
            type: string
          type: object
        metadata:
          title: Metadata
          description: Arbitrary JSON object for additional data
          additionalProperties: true
          type: object
        overwrite:
          title: Overwrite
          description: User corrections to span output
          additionalProperties: true
          type: object
        assessment_type:
          $ref: '#/components/schemas/AssessmentType'
          description: Type of assessment
      additionalProperties: false
      type: object
      title: SpanAssessmentUpdateRequest
      description: Request model for updating span assessment
    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
    DeleteResponse_SpanAssessment_:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: span.assessment
          title: Object
          default: span.assessment
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - id
      - deleted
    AssessmentType:
      type: string
      enum:
      - comment
      - rating
      - approval
      - rubric
      - metadata
      - overwrite
      title: AssessmentType
      description: Types of assessments that can be provided
  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)