Scale AI Chunks API

openapi: 3.2.0
info:
  title: EGP API V4 Chunks 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: Chunks
paths:
  /v4/chunks/rank:
    post:
      tags:
      - Chunks
      summary: Rank Chunks
      description: '### Description

        Sorts a list of text chunks by similarity against a given query string.


        ### Details

        Use this API endpoint to rank which text chunks provide the most relevant responses to a given a query string.


        This is useful for stuffing chunks into a prompt where order may matter or for filtering out less relevant chunks according to the ranking strategy. For example, this API may be useful when doing retrieval augment generation (RAG). Sometimes vector store similarity search does not always return the best ranking of text chunks, since this is heavily dependent on embedding generation. This API endpoint can act as a post-processing step to re-sort the given chunks using more complex strategies that may outperform vector search, and then filter only the top-k most relevant chunks to stuff into the prompt for RAG.


        ### Restrictions and Limits

        Ranking can be a very intensive and slow process depending on methodology where duration scales with number of chunks. For best performance, we recommend ranking less than 640 chunks at a time, and you may see a decrease in performance as the number of chunks ranked increases.'
      operationId: POST-V4-/v2/chunks/rank
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChunksRankRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChunksRankResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-source: https://docs.gp.scale.com/reference/v4/chunks/rank-chunks
components:
  schemas:
    ChunkV2:
      properties:
        chunk_id:
          type: string
          title: Chunk Id
          description: The unique ID of the chunk with embedding
        text:
          type: string
          title: Text
          description: The text associated with the chunk
        embedding:
          title: Embedding
          description: The vector embedding of the text associated with the chunk
          items:
            type: number
          type: array
        metadata:
          title: Metadata
          description: Any additional key value pairs of information stored by you on the chunk with embedding
          default: {}
          additionalProperties: true
          type: object
        user_supplied_metadata:
          title: User Supplied Metadata
          description: Any additional key value pairs of information returned from the custom chunking.
          default: {}
          additionalProperties: true
          type: object
        attachment_url:
          title: Attachment Url
          description: Original attachment URL from which this chunk got its data from
          type: string
        title:
          title: Title
          description: Title for this chunk, for example the file name
          type: string
        score:
          type: number
          title: Score
          description: A number between 0 and 1 representing how similar a chunk's embedding is to the query embedding. Higher numbers mean that this chunk with embedding is more similar.
      type: object
      required:
      - chunk_id
      - text
      - score
      title: ChunkV2
    AzureAIFoundryRankStrategy:
      properties:
        method:
          type: string
          const: azure_ai_foundry
          title: Method
          description: Use a model from Azure AI Foundry for ranking.
          default: azure_ai_foundry
        params:
          $ref: '#/components/schemas/AzureAIFoundryRankParams'
          description: The parameters needed for ranking.
      type: object
      required:
      - params
      title: AzureAIFoundryRankStrategy
    CrossEncoderRankStrategy:
      properties:
        method:
          type: string
          const: cross_encoder
          title: Method
          description: The name of the rank strategy. Must be `cross_encoder`.
          default: cross_encoder
        params:
          $ref: '#/components/schemas/CrossEncoderRankParams'
          description: The parameters needed for ranking.
          default:
            cross_encoder_model: cross-encoder/ms-marco-MiniLM-L-12-v2
      type: object
      title: CrossEncoderRankStrategy
    ModelRankParams:
      properties:
        model_deployment_id:
          type: string
          title: Model Deployment Id
          description: The model deployment id of a custom model to use for reranking
        base_model_name:
          title: Base Model Name
          description: The name of a base model to use for reranking
          type: string
        model_params:
          title: Model Params
          additionalProperties: true
          type: object
      type: object
      title: ModelRankParams
    CrossEncoderRankParams:
      properties:
        cross_encoder_model:
          anyOf:
          - type: string
            enum:
            - cross-encoder/ms-marco-MiniLM-L-12-v2
            - cross-encoder/mmarco-mMiniLMv2-L12-H384-v1
            - Qwen/Qwen3-Reranker-0.6B
            - Qwen/Qwen3-Reranker-4B
            - Qwen/Qwen3-Reranker-8B
          - type: string
          title: Cross Encoder Model
          description: Cross encoder model to use when ranking. Supports [cross-encoder/ms-marco-MiniLM-L-12-v2](https://huggingface.co/cross-encoder/ms-marco-MiniLM-L-12-v2), [cross-encoder/mmarco-mMiniLMv2-L12-H384-v1](https://huggingface.co/cross-encoder/mmarco-mMiniLMv2-L12-H384-v1), [Qwen/Qwen3-Reranker-0.6B](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B), [Qwen/Qwen3-Reranker-4B](https://huggingface.co/Qwen/Qwen3-Reranker-4B), and [Qwen/Qwen3-Reranker-8B](https://huggingface.co/Qwen/Qwen3-Reranker-8B).
          default: cross-encoder/ms-marco-MiniLM-L-12-v2
      type: object
      title: CrossEncoderRankParams
    RougeRankStrategy:
      properties:
        method:
          type: string
          const: rouge
          title: Method
          description: The name of the rank strategy.
          default: rouge
        params:
          $ref: '#/components/schemas/RougeRankParams'
          description: The parameters needed for ranking.
          default:
            metric: rouge2
            score: recall
      type: object
      title: RougeRankStrategy
    RankStrategy:
      oneOf:
      - $ref: '#/components/schemas/CrossEncoderRankStrategy'
      - $ref: '#/components/schemas/RougeRankStrategy'
      - $ref: '#/components/schemas/ModelRankStrategy'
      - $ref: '#/components/schemas/AzureAIFoundryRankStrategy'
      title: RankStrategy
      discriminator:
        propertyName: method
        mapping:
          azure_ai_foundry: '#/components/schemas/AzureAIFoundryRankStrategy'
          cross_encoder: '#/components/schemas/CrossEncoderRankStrategy'
          model: '#/components/schemas/ModelRankStrategy'
          rouge: '#/components/schemas/RougeRankStrategy'
    ModelRankStrategy:
      properties:
        method:
          type: string
          const: model
          title: Method
          description: Use a model from Models API for ranking.
          default: model
        params:
          $ref: '#/components/schemas/ModelRankParams'
          description: The parameters needed for ranking.
          default:
            model_params: {}
      type: object
      title: ModelRankStrategy
    AzureAIFoundryRankParams:
      properties:
        endpoint_url:
          type: string
          title: Endpoint Url
          description: 'Azure AI Foundry model endpoint to use for reranking. Example url: https://cohere-rerank-v3-multilingual-xyz.eastus.models.ai.azure.com/v2/rerank'
        endpoint_api_key:
          type: string
          title: Endpoint Api Key
          description: Azure AI Foundry Endpoint API key to use for reranking.
      type: object
      required:
      - endpoint_url
      - endpoint_api_key
      title: AzureAIFoundryRankParams
    ChunksRankResponse:
      properties:
        relevant_chunks:
          items:
            $ref: '#/components/schemas/ChunkV2'
          type: array
          title: Relevant Chunks
          description: List of chunks ranked by the requested rank strategy
      type: object
      required:
      - relevant_chunks
      title: ChunksRankResponse
    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:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RougeRankParams:
      properties:
        metric:
          type: string
          title: Metric
          description: Rouge type, can be n-gram based (e.g. rouge1, rouge2) or longest common subsequence (rougeL or rougeLsum)
          default: rouge2
        score:
          type: string
          enum:
          - precision
          - recall
          - fmeasure
          title: Score
          description: Metric to use from Rouge score
          default: recall
      type: object
      title: RougeRankParams
    ChunksRankRequest:
      properties:
        query:
          type: string
          title: Query
          description: Natural language query to re-rank chunks against. If a vector store query was originally used to retrieve these chunks, please use the same query for this ranking
        relevant_chunks:
          items:
            $ref: '#/components/schemas/ChunkV2'
          type: array
          title: Relevant Chunks
          description: List of chunks to rank
        rank_strategy:
          $ref: '#/components/schemas/RankStrategy'
          description: 'The ranking strategy to use.


            Rank strategies determine how the ranking is done, They consist of the ranking method name and additional params needed to compute the ranking.


            Use the built-in `cross_encoder` or `rouge` strategies or create a custom one with the Models API.'
        top_k:
          title: Top K
          description: Number of chunks to return. Must be greater than 0 if specified. If not specified, all chunks will be returned.
          type: integer
          exclusiveMinimum: 0
        account_id:
          title: Account Id
          description: Account to rank chunks with. If you have access to more than one account, you must specify an account_id
          type: string
      type: object
      required:
      - query
      - relevant_chunks
      - rank_strategy
      title: ChunksRankRequest
  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)