openapi: 3.0.3
info:
  title: remediation.proto Audio Rerank API
  version: version not set
servers:
- url: https://api.together.xyz/v1
security:
- bearerAuth: []
tags:
- name: Rerank
paths:
  /rerank:
    post:
      tags:
      - Rerank
      summary: Create a rerank request
      description: Rerank a list of documents by relevance to a query. Returns a relevance score and ordering index for each document.
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "# Docs for v1 can be found by changing the above selector ^\nfrom together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\ndocuments = [\n    {\n        \"title\": \"Llama\",\n        \"text\": \"The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era.\"\n    },\n    {\n        \"title\": \"Panda\",\n        \"text\": \"The giant panda (Ailuropoda melanoleuca), also known as the panda bear or simply panda, is a bear species endemic to China.\"\n    },\n    {\n        \"title\": \"Guanaco\",\n        \"text\": \"The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations.\"\n    },\n    {\n        \"title\": \"Wild Bactrian camel\",\n        \"text\": \"The wild Bactrian camel (Camelus ferus) is an endangered species of camel endemic to Northwest China and southwestern Mongolia.\"\n    }\n]\n\nresponse = client.rerank.create(\n    model=\"Salesforce/Llama-Rank-v1\",\n    query=\"What animals can I find near Peru?\",\n    documents=documents,\n)\n\nfor result in response.results:\n    print(f\"Rank: {result.index + 1}\")\n    print(f\"Title: {documents[result.index]['title']}\")\n    print(f\"Text: {documents[result.index]['text']}\")\n"
      - lang: Python
        label: Together AI SDK (v1)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\ndocuments = [\n    {\n        \"title\": \"Llama\",\n        \"text\": \"The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era.\"\n    },\n    {\n        \"title\": \"Panda\",\n        \"text\": \"The giant panda (Ailuropoda melanoleuca), also known as the panda bear or simply panda, is a bear species endemic to China.\"\n    },\n    {\n        \"title\": \"Guanaco\",\n        \"text\": \"The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations.\"\n    },\n    {\n        \"title\": \"Wild Bactrian camel\",\n        \"text\": \"The wild Bactrian camel (Camelus ferus) is an endangered species of camel endemic to Northwest China and southwestern Mongolia.\"\n    }\n]\n\nresponse = client.rerank.create(\n    model=\"Salesforce/Llama-Rank-v1\",\n    query=\"What animals can I find near Peru?\",\n    documents=documents,\n)\n\nfor result in response.results:\n    print(f\"Rank: {result.index + 1}\")\n    print(f\"Title: {documents[result.index]['title']}\")\n    print(f\"Text: {documents[result.index]['text']}\")\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst documents = [{\n  \"title\": \"Llama\",\n  \"text\": \"The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era.\"\n},\n{\n  \"title\": \"Panda\",\n  \"text\": \"The giant panda (Ailuropoda melanoleuca), also known as the panda bear or simply panda, is a bear species endemic to China.\"\n},\n{\n  \"title\": \"Guanaco\",\n  \"text\": \"The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations.\"\n},\n{\n  \"title\": \"Wild Bactrian camel\",\n  \"text\": \"The wild Bactrian camel (Camelus ferus) is an endangered species of camel endemic to Northwest China and southwestern Mongolia.\"\n}];\n\nconst response = await client.rerank.create({\n  model: \"Salesforce/Llama-Rank-v1\",\n  query: \"What animals can I find near Peru?\",\n  documents,\n});\n\nfor (const result of response.results) {\n  console.log(`Rank: ${result.index + 1}`);\n  console.log(`Title: ${documents[result.index].title}`);\n  console.log(`Text: ${documents[result.index].text}`);\n}\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst documents = [{\n  \"title\": \"Llama\",\n  \"text\": \"The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era.\"\n},\n{\n  \"title\": \"Panda\",\n  \"text\": \"The giant panda (Ailuropoda melanoleuca), also known as the panda bear or simply panda, is a bear species endemic to China.\"\n},\n{\n  \"title\": \"Guanaco\",\n  \"text\": \"The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations.\"\n},\n{\n  \"title\": \"Wild Bactrian camel\",\n  \"text\": \"The wild Bactrian camel (Camelus ferus) is an endangered species of camel endemic to Northwest China and southwestern Mongolia.\"\n}];\n\nconst response = await client.rerank.create({\n  model: \"Salesforce/Llama-Rank-v1\",\n  query: \"What animals can I find near Peru?\",\n  documents,\n});\n\nfor (const result of response.results) {\n  console.log(`Rank: ${result.index + 1}`);\n  console.log(`Title: ${documents[result.index].title}`);\n  console.log(`Text: ${documents[result.index].text}`);\n}\n"
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.together.ai/v1/rerank\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"model\": \"Salesforce/Llama-Rank-v1\",\n       \"query\": \"What animals can I find near Peru?\",\n       \"documents\": [{\n          \"title\": \"Llama\",\n          \"text\": \"The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era.\"\n        },\n        {\n          \"title\": \"Panda\",\n          \"text\": \"The giant panda (Ailuropoda melanoleuca), also known as the panda bear or simply panda, is a bear species endemic to China.\"\n        },\n        {\n          \"title\": \"Guanaco\",\n          \"text\": \"The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations.\"\n        },\n        {\n          \"title\": \"Wild Bactrian camel\",\n          \"text\": \"The wild Bactrian camel (Camelus ferus) is an endangered species of camel endemic to Northwest China and southwestern Mongolia.\"\n        }]\n     }'\n"
      operationId: rerank
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerankRequest'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerankResponse'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '429':
          description: RateLimit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '503':
          description: Overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '504':
          description: Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      deprecated: false
components:
  schemas:
    ErrorData:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              nullable: false
            type:
              type: string
              nullable: false
            param:
              type: string
              nullable: true
              default: null
            code:
              type: string
              nullable: true
              default: null
          required:
          - type
          - message
    RerankResponse:
      type: object
      required:
      - object
      - model
      - results
      properties:
        object:
          description: The object type, which is always `rerank`.
          const: rerank
        id:
          type: string
          description: Request ID
          example: 9dfa1a09-5ebc-4a40-970f-586cb8f4ae47
        model:
          type: string
          description: The model to be used for the rerank request.
          example: salesforce/turboranker-0.8-3778-6328
        results:
          type: array
          items:
            type: object
            required:
            - index
            - relevance_score
            - document
            properties:
              index:
                type: integer
              relevance_score:
                type: number
              document:
                type: object
                properties:
                  text:
                    type: string
                    nullable: true
          example:
          - index: 0
            relevance_score: 0.29980177813003117
            document:
              text: '{"title":"Llama","text":"The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era."}'
          - index: 2
            relevance_score: 0.2752447527354349
            document:
              text: '{"title":"Guanaco","text":"The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations."}'
        usage:
          $ref: '#/components/schemas/UsageData'
          example:
            prompt_tokens: 1837
            completion_tokens: 0
            total_tokens: 1837
    RerankRequest:
      type: object
      properties:
        model:
          type: string
          description: 'The model to be used for the rerank request.<br> <br> [See all of Together AI''s rerank models](https://docs.together.ai/docs/serverless-models#rerank-models)

            '
          example: Salesforce/Llama-Rank-V1
          anyOf:
          - type: string
            enum:
            - Salesforce/Llama-Rank-v1
          - type: string
        query:
          type: string
          description: The search query to be used for ranking.
          example: What animals can I find near Peru?
        documents:
          description: List of documents, which can be either strings or objects.
          oneOf:
          - type: array
            items:
              type: object
              additionalProperties: true
          - type: array
            items:
              type: string
              example: Our solar system orbits the Milky Way galaxy at about 515,000 mph
          example:
          - title: Llama
            text: The llama is a domesticated South American camelid, widely used as a meat and pack animal by Andean cultures since the pre-Columbian era.
          - title: Panda
            text: The giant panda (Ailuropoda melanoleuca), also known as the panda bear or simply panda, is a bear species endemic to China.
          - title: Guanaco
            text: The guanaco is a camelid native to South America, closely related to the llama. Guanacos are one of two wild South American camelids; the other species is the vicuña, which lives at higher elevations.
          - title: Wild Bactrian camel
            text: The wild Bactrian camel (Camelus ferus) is an endangered species of camel endemic to Northwest China and southwestern Mongolia.
        top_n:
          type: integer
          description: The number of top results to return.
          example: 2
        return_documents:
          type: boolean
          description: Whether to return supplied documents with the response.
          example: true
        rank_fields:
          type: array
          items:
            type: string
          description: List of keys in the JSON Object document to rank by. Defaults to use all supplied keys for ranking.
          example:
          - title
          - text
      required:
      - model
      - query
      - documents
      additionalProperties: false
    UsageData:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
      nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-bearer-format: bearer
      x-default: default