POST
/
v1
/
rerank

​
Overview

Morph’s Rerank API improves search quality by reordering candidate results based on their relevance to a query. Unlike the Apply and Embedding endpoints, the Rerank API uses a custom endpoint specifically designed for reranking tasks.

Morph does not store file content by default.

​
API Endpoint

POST https://api.morphllm.com/v1/rerank

​
Model Versions

The current version is morph-rerank-v2.

​
Example Request

async function rerankResults(
  query: string, 
  documents: string[], 
  topN: number = 5
) {
  const response = await fetch('https://api.morphllm.com/v1/rerank', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-morph-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'morph-rerank-v2',
      query: query,
      documents: documents,
      top_n: topN
    })
  });
  
  return await response.json();
}

Note that the top_n request parameter is optional and will default to the length of the documents field. Result documents will be sorted by relevance, and the index property can be used to determine original order.

​
Input Format

The request accepts the following parameters:

ParameterTypeRequiredDescription
modelstringYesThe model ID to use for reranking. Use morph-rerank-v1.
querystringYesThe search query to compare documents against.
documentsarrayNo*An array of document strings to be reranked. Required if embedding_ids is not provided.
embedding_idsarrayNo*An array of embedding IDs to rerank. Required if documents is not provided. Remote content storage must be enabled.
top_nintegerNoNumber of top results to return. Default is all documents.
return_documentsbooleanNoWhether to include document texts in response. Default is true.

* Either documents or embedding_ids must be provided.

​
Using Document Content

import requests

def rerank_results(query, documents, top_n=5):
    response = requests.post(
        "https://api.morphllm.com/v1/rerank",
        headers={
            "Authorization": f"Bearer your-morph-api-key",
            "Content-Type": "application/json"
        },
        json={
            "model": "morph-rerank-v1",
            "query": query,
            "documents": documents,
            "top_n": top_n
        }
    )
    
    return response.json()

# Example usage with code documentation
query = "How to implement JWT authentication in Express"
documents = [
    """const jwt = require('jsonwebtoken');
const express = require('express');

function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  
  if (token == null) return res.sendStatus(401);
  
  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {
    if (err) return res.sendStatus(403);
    req.user = user;
    next();
  });
}""",
    """const express = require('express');
const app = express();
const port = 3000;

app.use(express.json());

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});""",
    """const jwt = require('jsonwebtoken');

const user = { id: 123, username: 'john_doe' };
const accessToken = jwt.sign(user, process.env.ACCESS_TOKEN_SECRET, { expiresIn: '15m' });
const refreshToken = jwt.sign(user, process.env.REFRESH_TOKEN_SECRET);

console.log('Access Token:', accessToken);""",
    """const express = require('express');
const router = express.Router();

router.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]);
});

router.post('/users', (req, res) => {
  const { name } = req.body;
  res.json({ id: 3, name });
});

module.exports = router;""",
    """const passport = require('passport');
const GoogleStrategy = require('passport-google-oauth20').Strategy;

passport.use(new GoogleStrategy({
  clientID: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  callbackURL: "/auth/google/callback"
}, (accessToken, refreshToken, profile, done) => {
  return done(null, profile);
}));""",
    """const express = require('express');
const passport = require('passport');
const JwtStrategy = require('passport-jwt').Strategy;
const ExtractJwt = require('passport-jwt').ExtractJwt;

passport.use(new JwtStrategy({
  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
  secretOrKey: process.env.JWT_SECRET
}, (payload, done) => {
  User.findById(payload.sub, (err, user) => {
    if (err) return done(err, false);
    if (user) return done(null, user);
    return done(null, false);
  });
}));"""
]

results = rerank_results(query, documents, top_n=3)
print(results)

​
Using Embedding IDs

When you have previously generated embeddings and enabled remote content storage, you can rerank using embedding IDs:

async function rerankWithEmbeddingIds(query, embeddingIds, topN = 5) {
  const response = await fetch('https://api.morphllm.com/v1/rerank', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-morph-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'morph-rerank-v2', // Use the latest model version
      query: query,
      embedding_ids: embeddingIds,
      top_n: topN
    })
  });
  
  return await response.json();
}

// Example with embedding IDs
const query = "React state management patterns";
const embeddingIds = [
  "emb_123456789",
  "emb_987654321",
  "emb_456789123",
  "emb_789123456",
  "emb_321654987"
];

rerankWithEmbeddingIds(query, embeddingIds, 3)
  .then(results => console.log(results));

​
cURL Examples

​
With Document Content

curl --request POST \
  --url https://api.morphllm.com/v1/rerank \
  --header 'Authorization: Bearer your-morph-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "morph-rerank-v2", 
    "query": "How to implement JWT authentication in Express",
    "documents": [
      "const jwt = require(\"jsonwebtoken\");\nconst express = require(\"express\");\n\nfunction authenticateToken(req, res, next) {\n  const authHeader = req.headers[\"authorization\"];\n  const token = authHeader && authHeader.split(\" \")[1];\n  \n  if (token == null) return res.sendStatus(401);\n  \n  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {\n    if (err) return res.sendStatus(403);\n    req.user = user;\n    next();\n  });\n}",
      "const express = require(\"express\");\nconst app = express();\nconst port = 3000;\n\napp.use(express.json());\n\napp.get(\"/\", (req, res) => {\n  res.send(\"Hello World!\");\n});\n\napp.listen(port, () => {\n  console.log(`App listening at http://localhost:${port}`);\n});",
      "const jwt = require(\"jsonwebtoken\");\n\nconst user = { id: 123, username: \"john_doe\" };\nconst accessToken = jwt.sign(user, process.env.ACCESS_TOKEN_SECRET, { expiresIn: \"15m\" });\nconst refreshToken = jwt.sign(user, process.env.REFRESH_TOKEN_SECRET);\n\nconsole.log(\"Access Token:\", accessToken);",
      "const express = require(\"express\");\nconst router = express.Router();\n\nrouter.get(\"/users\", (req, res) => {\n  res.json([{ id: 1, name: \"John\" }, { id: 2, name: \"Jane\" }]);\n});\n\nrouter.post(\"/users\", (req, res) => {\n  const { name } = req.body;\n  res.json({ id: 3, name });\n});\n\nmodule.exports = router;",
      "const passport = require(\"passport\");\nconst GoogleStrategy = require(\"passport-google-oauth20\").Strategy;\n\npassport.use(new GoogleStrategy({\n  clientID: process.env.GOOGLE_CLIENT_ID,\n  clientSecret: process.env.GOOGLE_CLIENT_SECRET,\n  callbackURL: \"/auth/google/callback\"\n}, (accessToken, refreshToken, profile, done) => {\n  return done(null, profile);\n}));",
      "const express = require(\"express\");\nconst passport = require(\"passport\");\nconst JwtStrategy = require(\"passport-jwt\").Strategy;\nconst ExtractJwt = require(\"passport-jwt\").ExtractJwt;\n\npassport.use(new JwtStrategy({\n  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),\n  secretOrKey: process.env.JWT_SECRET\n}, (payload, done) => {\n  User.findById(payload.sub, (err, user) => {\n    if (err) return done(err, false);\n    if (user) return done(null, user);\n    return done(null, false);\n  });\n}));"
    ],
    "top_n": 3
  }'

​
With Embedding IDs

curl --request POST \
  --url https://api.morphllm.com/v1/rerank \
  --header 'Authorization: Bearer your-morph-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "morph-rerank-v2",
    "query": "React state management patterns",
    "embedding_ids": [
      "emb_123456789",
      "emb_987654321", 
      "emb_456789123",
      "emb_789123456",
      "emb_321654987"
    ],
    "top_n": 3
  }'

​
Response Format

{
  "id": "rerank-26b29083d49a4c1e82032a95549a8633",
  "model": "morph-rerank-v2",
  "usage": {
    "total_tokens": 21
  },
  "results": [
    {
      "index": 0,
      "document": {
        "text": "const jwt = require('jsonwebtoken');\nconst express = require('express');\n\nfunction authenticateToken(req, res, next) {\n  const authHeader = req.headers['authorization'];\n  const token = authHeader && authHeader.split(' ')[1];\n  \n  if (token == null) return res.sendStatus(401);\n  \n  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {\n    if (err) return res.sendStatus(403);\n    req.user = user;\n    next();\n  });\n}"
      },
      "relevance_score": 0.92
    },
    {
      "index": 5,
      "document": {
        "text": "const express = require('express');\nconst passport = require('passport');\nconst JwtStrategy = require('passport-jwt').Strategy;\nconst ExtractJwt = require('passport-jwt').ExtractJwt;\n\npassport.use(new JwtStrategy({\n  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),\n  secretOrKey: process.env.JWT_SECRET\n}, (payload, done) => {\n  User.findById(payload.sub, (err, user) => {\n    if (err) return done(err, false);\n    if (user) return done(null, user);\n    return done(null, false);\n  });\n}));"
      },
      "relevance_score": 0.87
    },
    {
      "index": 2,
      "document": {
        "text": "const jwt = require('jsonwebtoken');\n\nconst user = { id: 123, username: 'john_doe' };\nconst accessToken = jwt.sign(user, process.env.ACCESS_TOKEN_SECRET, { expiresIn: '15m' });\nconst refreshToken = jwt.sign(user, process.env.REFRESH_TOKEN_SECRET);\n\nconsole.log('Access Token:', accessToken);"
      },
      "relevance_score": 0.75
    }
  ]
}

When using embedding IDs, the response will include the document content if available and if return_documents is set to true.

​
Remote Content Storage

To use embedding IDs for reranking, you must enable remote content storage in your account settings. This allows Morph to retrieve the content associated with each embedding ID for reranking purposes. Without remote content storage enabled, you’ll need to pass in the document content directly.

Benefits of using embedding IDs:

  • Reduced payload size for large document collections
  • Improved security as content is stored in your account’s secure storage
  • Ability to rerank content that was previously embedded

​
Integration with Search Systems

The Rerank API is typically used as a second-pass ranking system in a multi-stage retrieval pipeline:

import { OpenAI } from 'openai';
import fetch from 'node-fetch';

// Initialize OpenAI client for embeddings
const openaiClient = new OpenAI({
  apiKey: 'your-morph-api-key',
  baseURL: 'https://api.morphllm.com/v1'
});
// Example search pipeline
async function semanticSearch(query, codebase) {
  // 1. Generate embedding for the query
  const embeddingResponse = await openaiClient.embeddings.create({
    model: "morph-embedding-v2",
    input: query
  });
  const queryEmbedding = embeddingResponse.data[0].embedding;
  
  // 2. Retrieve initial candidates using vector similarity
  // (Simplified example - in practice, you would use a vector database)
  const candidateDocuments = retrieveSimilarDocuments(queryEmbedding, codebase);
  
  // 3. Rerank candidates for more accurate results
// Example search pipeline with embedding IDs
async function semanticSearchWithEmbeddingIds(query, embeddingIds) {
  // Rerank candidates for more accurate results
  const rerankedResults = await fetch('https://api.morphllm.com/v1/rerank', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-morph-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'morph-rerank-v2',
      query: query,
      embedding_ids: embeddingIds,
      top_n: 5
    })
  }).then(res => res.json());
  
  return rerankedResults;
}

// Helper function to simulate vector similarity search
function retrieveSimilarDocuments(queryEmbedding, codebase) {
  // In practice, this would be a call to a vector database
  return codebase.slice(0, 20); // Return first 20 documents as candidates
}

This two-stage approach combines the efficiency of initial retrieval methods with the accuracy of deep neural reranking models.