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.
The request accepts the following parameters:
| Parameter | Type | Required | Description |
|---|
model | string | Yes | The model ID to use for reranking. Use morph-rerank-v1. |
query | string | Yes | The search query to compare documents against. |
documents | array | No* | An array of document strings to be reranked. Required if embedding_ids is not provided. |
embedding_ids | array | No* | An array of embedding IDs to rerank. Required if documents is not provided. Remote content storage must be enabled. |
top_n | integer | No | Number of top results to return. Default is all documents. |
* 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
}'
{
"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
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.
