Scale AI Chat Threads API

openapi: 3.2.0
info:
  title: EGP API V4 Chat Threads 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: ChatThreads
paths:
  /v4/applications/{application_variant_id}/threads:
    post:
      tags:
      - ChatThreads
      summary: Create New Application Thread
      operationId: POST-V4-/applications/{application_variant_id}/threads
      parameters:
      - name: application_variant_id
        in: path
        required: true
        schema:
          type: string
          title: Application Variant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatThreadRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/applications/create-new-application-thread
    get:
      tags:
      - ChatThreads
      summary: List Application Threads
      operationId: GET-V4-/applications/{application_variant_id}/threads
      parameters:
      - name: application_variant_id
        in: path
        required: true
        schema:
          type: string
          title: Application Variant Id
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          description: Include archived threads in the response.
          default: true
          title: Include Archived
        description: Include archived threads in the response.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatThreadResponse'
                title: Response Get-V4-/Applications/{Application Variant Id}/Threads
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/applications/list-application-threads
  /v4/threads/{thread_id}/messages/{application_interaction_id}/feedback:
    put:
      tags:
      - ChatThreads
      summary: Add Feedback To Thread Entry
      operationId: PUT-V4-/threads/{thread_id}/messages/{application_interaction_id}/feedback
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
          title: Thread Id
      - name: application_interaction_id
        in: path
        required: true
        schema:
          title: Application Interaction Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatThreadFeedbackRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadFeedbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chatthreads/add-feedback-to-thread-entry
    delete:
      tags:
      - ChatThreads
      summary: Delete Interaction Feedback
      operationId: DELETE-V4-/threads/{thread_id}/messages/{application_interaction_id}/feedback
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
          title: Thread Id
      - name: application_interaction_id
        in: path
        required: true
        schema:
          title: Application Interaction Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chatthreads/delete-interaction-feedback
  /v4/threads/{thread_id}:
    delete:
      tags:
      - ChatThreads
      summary: Delete Chat Thread
      operationId: DELETE-V4-/threads/{thread_id}
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
          title: Thread Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chatthreads/delete-chat-thread
    patch:
      tags:
      - ChatThreads
      summary: Patch Chat Thread
      operationId: PATCH-V4-/threads/{thread_id}
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
          title: Thread Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChatThreadRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chatthreads/patch-chat-thread
  /v4/threads/{thread_id}/messages:
    get:
      tags:
      - ChatThreads
      summary: Get Thread Messages
      operationId: GET-V4-/threads/{thread_id}/messages
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
          title: Thread Id
      - name: fetch_by_account
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Fetch the thread by account instead of user
          default: false
          title: Fetch By Account
        description: Fetch the thread by account instead of user
      - name: fetch_spans
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Fetch spans for each message
          default: false
          title: Fetch Spans
        description: Fetch spans for each message
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatThreadHistory'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chatthreads/get-thread-messages
  /v4/threads/{thread_id}/messages/{application_interaction_id}:
    patch:
      tags:
      - ChatThreads
      summary: Patch Chat Thread Entry
      operationId: PATCH-V4-/threads/{thread_id}/messages/{application_interaction_id}
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: string
          title: Thread Id
      - name: application_interaction_id
        in: path
        required: true
        schema:
          title: Application Interaction Id
          type: string
      - name: fetch_by_account
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Fetch the thread by account instead of user
          default: false
          title: Fetch By Account
        description: Fetch the thread by account instead of user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChatThreadEntryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationInteractionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chatthreads/patch-chat-thread-entry
components:
  schemas:
    ApplicationTraceSpanResponse:
      properties:
        id:
          type: string
          title: Id
          description: Identifies the application step
        application_interaction_id:
          title: Application Interaction Id
          description: The interaction ID this span belongs to
          type: string
        application_variant_id:
          title: Application Variant Id
          description: The id of the application variant this span belongs to
          type: string
        node_id:
          type: string
          title: Node Id
          description: The id of the node in the application_variant config that emitted this insight
        operation_type:
          $ref: '#/components/schemas/ApplicationOperationType'
          description: Type of the operation, e.g. RERANKING
        operation_status:
          $ref: '#/components/schemas/ApplicationOperationStatus'
          description: The outcome of the operation
        operation_input:
          title: Operation Input
          description: The JSON representation of the input that this step received
          additionalProperties: true
          type: object
        operation_output:
          title: Operation Output
          description: The JSON representation of the output that this step emitted
          additionalProperties: true
          type: object
        operation_expected:
          title: Operation Expected
          description: The JSON representation of the expected output for this step
          additionalProperties: true
          type: object
        operation_metadata:
          title: Operation Metadata
          description: The JSON representation of the metadata insights emitted through the execution. This can differ based on different types of operations
          additionalProperties: true
          type: object
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
          description: The start time of the step
        end_timestamp:
          title: End Timestamp
          description: The end time of the step, nullable, since it can be set to done at a later point in time.
          type: string
          format: date-time
        duration_ms:
          type: integer
          title: Duration Ms
          description: How much time the step took in milliseconds(ms)
        trace_id:
          title: Trace Id
          description: The root-level ID where this span belongs to
          type: string
        parent_id:
          title: Parent Id
          description: Who is the parent span of this current span, null if span is root parent.
          type: string
        group_id:
          title: Group Id
          description: The ID of the group this span belongs to
          type: string
        account_id:
          type: string
          title: Account Id
          description: The ID of the account that owns the given entity.
        created_by_user_id:
          type: string
          title: Created By User Id
          description: The user who originally created the entity.
        created_by_identity_type:
          $ref: '#/components/schemas/IdentifierTypeEnum'
          description: The type of identity that created the entity.
      type: object
      required:
      - id
      - node_id
      - operation_type
      - operation_status
      - start_timestamp
      - duration_ms
      title: ApplicationTraceSpanResponse
    ChatThreadRequest:
      properties:
        title:
          type: string
          title: Title
        application_variant_id:
          type: string
          title: Application Variant Id
          can_patch: false
        thread_metadata:
          title: Thread Metadata
          additionalProperties: true
          type: object
        account_id:
          type: string
          title: Account Id
          description: The ID of the account that owns the given entity.
          can_patch: false
      type: object
      required:
      - title
      - application_variant_id
      - account_id
      title: ChatThreadRequest
    ChatThreadHistory:
      properties:
        thread:
          $ref: '#/components/schemas/ChatThreadResponse'
        messages:
          items:
            $ref: '#/components/schemas/ApplicationInteractionWithFeedback'
          type: array
          title: Messages
        application_spec_id:
          type: string
          title: Application Spec Id
          description: The ID of the application spec that the thread belongs to.
      type: object
      required:
      - thread
      - messages
      - application_spec_id
      title: ChatThreadHistory
    ApplicationInteractionSource:
      type: string
      enum:
      - EXTERNAL_AI
      - EVALUATION
      - SGP_CHAT
      - AGENTS_SERVICE
      title: ApplicationInteractionSource
    UpdateChatThreadEntryRequest:
      properties:
        output_text:
          title: Output Text
          description: ' The output text generated by the application.'
          type: string
      type: object
      title: UpdateChatThreadEntryRequest
    ChatThreadResponse:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        application_variant_id:
          type: string
          title: Application Variant Id
          can_patch: false
        thread_metadata:
          title: Thread Metadata
          additionalProperties: true
          type: object
        account_id:
          type: string
          title: Account Id
          description: The ID of the account that owns the given entity.
          can_patch: false
        created_by_user_id:
          type: string
          title: Created By User Id
          description: The user who originally created the entity.
        created_by_identity_type:
          $ref: '#/components/schemas/IdentifierTypeEnum'
          description: The type of identity that created the entity.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the entity was created in ISO format.
        archived_at:
          title: Archived At
          description: The date and time when the entity was archived in ISO format.
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: The date and time when the entity was last updated in ISO format.
      type: object
      required:
      - id
      - title
      - application_variant_id
      - account_id
      - created_by_user_id
      - created_by_identity_type
      - created_at
      - updated_at
      title: ChatThreadResponse
    ChatThreadFeedbackRequest:
      properties:
        chat_thread_id:
          title: Chat Thread Id
          can_patch: false
          type: string
        application_interaction_id:
          type: string
          title: Application Interaction Id
          can_patch: false
        sentiment:
          $ref: '#/components/schemas/FeedbackSentiment'
        description:
          title: Description
          type: string
      type: object
      required:
      - chat_thread_id
      - application_interaction_id
      - sentiment
      - description
      title: ChatThreadFeedbackRequest
    ApplicationInteractionWithFeedback:
      properties:
        entry:
          $ref: '#/components/schemas/ApplicationInteractionResponse'
        spans:
          title: Spans
          items:
            $ref: '#/components/schemas/ApplicationTraceSpanResponse'
          type: array
        feedback:
          $ref: '#/components/schemas/ChatThreadFeedbackResponse'
      type: object
      required:
      - entry
      title: ApplicationInteractionWithFeedback
    ChatThreadFeedbackResponse:
      properties:
        id:
          type: string
          title: Id
        chat_thread_id:
          title: Chat Thread Id
          can_patch: false
          type: string
        application_interaction_id:
          type: string
          title: Application Interaction Id
          can_patch: false
        sentiment:
          $ref: '#/components/schemas/FeedbackSentiment'
        description:
          title: Description
          type: string
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the entity was created in ISO format.
      type: object
      required:
      - id
      - chat_thread_id
      - application_interaction_id
      - sentiment
      - description
      - created_at
      title: ChatThreadFeedbackResponse
    ApplicationOperationType:
      type: string
      enum:
      - TEXT_INPUT
      - TEXT_OUTPUT
      - COMPLETION_INPUT
      - COMPLETION
      - KB_RETRIEVAL
      - KB_INPUT
      - RERANKING
      - EXTERNAL_ENDPOINT
      - PROMPT_ENGINEERING
      - DOCUMENT_INPUT
      - MAP_REDUCE
      - DOCUMENT_SEARCH
      - DOCUMENT_PROMPT
      - CUSTOM
      - CODE_EXECUTION
      - DATA_MANIPULATION
      - EVALUATION
      - FILE_RETRIEVAL
      - KB_ADD_CHUNK
      - KB_MANAGEMENT
      - GUARDRAIL
      - OUTPUT_GUARDRAIL
      - TRACER
      - AGENT_TRACER
      - AGENT_WORKFLOW
      - STANDALONE
      title: ApplicationOperationType
    FeedbackSentiment:
      type: string
      enum:
      - positive
      - negative
      title: FeedbackSentiment
    ApplicationOperationStatus:
      type: string
      enum:
      - SUCCESS
      - ERROR
      - CANCELED
      title: ApplicationOperationStatus
    IdentifierTypeEnum:
      type: string
      enum:
      - user
      - service_account
      title: IdentifierTypeEnum
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UpdateChatThreadRequest:
      properties:
        title:
          title: Title
          description: The title of the chat thread.
          type: string
        archived_at:
          title: Archived At
          description: Date when the chat thread is archived, or None to un-archive.
          type: string
        thread_metadata:
          title: Thread Metadata
          description: The metadata associated with the thread
          can_patch: true
          additionalProperties: true
          type: object
      type: object
      title: UpdateChatThreadRequest
    ApplicationInteractionResponse:
      properties:
        id:
          type: string
          title: Id
        input:
          additionalProperties: true
          type: object
          title: Input
        output:
          additionalProperties: true
          type: object
          title: Output
        aggregated:
          type: boolean
          title: Aggregated
          description: Boolean of whether this interaction has been uploaded to s3 bucket yet, default is false
          can_patch: false
        application_spec_id:
          type: string
          title: Application Spec Id
        application_variant_id:
          type: string
          title: Application Variant Id
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
        duration_ms:
          type: integer
          title: Duration Ms
          description: How much time the step took in milliseconds(ms)
        operation_status:
          $ref: '#/components/schemas/ApplicationOperationStatus'
          description: The outcome of the operation
        operation_metadata:
          title: Operation Metadata
          description: The JSON representation of the metadata insights emitted through the execution. This can differ based on different types of operations
          additionalProperties: true
          type: object
        models:
          title: Models
          description: The models used for this interaction
          items:
            type: string
          type: array
        chat_thread_id:
          title: Chat Thread Id
          can_patch: false
          type: string
        interaction_source:
          $ref: '#/components/schemas/ApplicationInteractionSource'
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the entity was created in ISO format.
      type: object
      required:
      - id
      - input
      - output
      - aggregated
      - application_spec_id
      - application_variant_id
      - start_timestamp
      - duration_ms
      - operation_status
      - created_at
      title: ApplicationInteractionResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  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/v4/openapi.json (404 when assembled)