Vector-Based Related Content
Finds related content from a corpus based on text similarity to a reference item. Supports TF-IDF cosine, Jaccard, and combined algorithms with category boosting and tag overlap.
POST /api/related-content
Why use this API?
Power your content discovery with intelligent similarity matching. This API uses proven vector-based algorithms to find semantically related content from your corpus, complete with detailed scoring breakdowns so you understand exactly why items match.
What it does
The Vector-Based Related Content API analyzes text similarity between a reference item and a corpus of content items. It employs multiple algorithms to compute similarity scores and returns ranked results with detailed breakdowns.
Key Features
- Multiple Algorithms — Choose from TF-IDF cosine similarity, Jaccard index, or a combined approach
- Category Boosting — Prioritize matches from the same category for more relevant results
- Tag Overlap Scoring — Factor in shared tags for improved relevance
- Detailed Breakdown — Get per-algorithm scores to understand match quality
Code Examples
curl -X POST https://api.atomicapis.dev/api/related-content \
-H "X-RapidAPI-Proxy-Secret: YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"referenceItem": {
"id": "article-001",
"title": "Getting Started with Machine Learning",
"text": "Machine learning is a subset of artificial intelligence...",
"category": "technology",
"tags": ["ai", "ml", "tutorial"]
},
"corpus": [
{
"id": "article-002",
"title": "Deep Learning Fundamentals",
"text": "Deep learning uses neural networks with multiple layers...",
"category": "technology",
"tags": ["ai", "deep-learning", "neural-networks"]
},
{
"id": "article-003",
"title": "Introduction to Python",
"text": "Python is a versatile programming language...",
"category": "programming",
"tags": ["python", "programming", "beginner"]
}
],
"algorithm": "tfidf",
"similarityThreshold": 0.1,
"maxResults": 20,
"categoryBoost": 0.1,
"includeScoreBreakdown": false
}'
const response = await fetch('https://api.atomicapis.dev/api/related-content', {
method: 'POST',
headers: {
'X-RapidAPI-Proxy-Secret': 'YOUR_SECRET',
'Content-Type': 'application/json'
},
body: JSON.stringify({
referenceItem: {
id: 'article-001',
title: 'Getting Started with Machine Learning',
text: 'Machine learning is a subset of artificial intelligence...',
category: 'technology',
tags: ['ai', 'ml', 'tutorial']
},
corpus: [
{
id: 'article-002',
title: 'Deep Learning Fundamentals',
text: 'Deep learning uses neural networks with multiple layers...',
category: 'technology',
tags: ['ai', 'deep-learning', 'neural-networks']
},
{
id: 'article-003',
title: 'Introduction to Python',
text: 'Python is a versatile programming language...',
category: 'programming',
tags: ['python', 'programming', 'beginner']
}
],
algorithm: 'tfidf',
similarityThreshold: 0.1,
maxResults: 20,
categoryBoost: 0.1,
includeScoreBreakdown: false
})
});
const data = await response.json();
console.log(data.relatedItems);
import requests
response = requests.post(
'https://api.atomicapis.dev/api/related-content',
headers={
'X-RapidAPI-Proxy-Secret': 'YOUR_SECRET',
'Content-Type': 'application/json'
},
json={
'referenceItem': {
'id': 'article-001',
'title': 'Getting Started with Machine Learning',
'text': 'Machine learning is a subset of artificial intelligence...',
'category': 'technology',
'tags': ['ai', 'ml', 'tutorial']
},
'corpus': [
{
'id': 'article-002',
'title': 'Deep Learning Fundamentals',
'text': 'Deep learning uses neural networks with multiple layers...',
'category': 'technology',
'tags': ['ai', 'deep-learning', 'neural-networks']
},
{
'id': 'article-003',
'title': 'Introduction to Python',
'text': 'Python is a versatile programming language...',
'category': 'programming',
'tags': ['python', 'programming', 'beginner']
}
],
'algorithm': 'tfidf',
'similarityThreshold': 0.1,
'maxResults': 20,
'categoryBoost': 0.1,
'includeScoreBreakdown': False
}
)
data = response.json()
print(data['relatedItems'])
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
var requestBody = new
{
referenceItem = new
{
id = "article-001",
title = "Getting Started with Machine Learning",
text = "Machine learning is a subset of artificial intelligence...",
category = "technology",
tags = new[] { "ai", "ml", "tutorial" }
},
corpus = new[]
{
new
{
id = "article-002",
title = "Deep Learning Fundamentals",
text = "Deep learning uses neural networks with multiple layers...",
category = "technology",
tags = new[] { "ai", "deep-learning", "neural-networks" }
},
new
{
id = "article-003",
title = "Introduction to Python",
text = "Python is a versatile programming language...",
category = "programming",
tags = new[] { "python", "programming", "beginner" }
}
},
algorithm = "tfidf",
similarityThreshold = 0.1,
maxResults = 20,
categoryBoost = 0.1,
includeScoreBreakdown = false
};
var json = JsonSerializer.Serialize(requestBody);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
"https://api.atomicapis.dev/api/related-content", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
referenceItem |
object | Yes | The reference content item to find similar items for |
referenceItem.id |
string | Yes | Unique identifier for the reference item |
referenceItem.title |
string | No | Title of the reference item |
referenceItem.text |
string | Yes | Full text content for similarity analysis |
referenceItem.category |
string | No | Category for boosting same-category matches |
referenceItem.tags |
string[] | No | Tags for tag overlap scoring |
referenceItem.metadata |
object | No | Key-value metadata to pass through on matched items |
corpus |
array | Yes | Array of content items to search against |
algorithm |
string | No | Similarity algorithm: tfidf, jaccard, or combined. Default: tfidf |
similarityThreshold |
number | No | Minimum similarity score threshold (0-1). Default: 0.1 |
maxResults |
number | No | Maximum number of results to return (1-100). Default: 20 |
categoryBoost |
number | No | Score boost for same-category items (0-1). Default: 0.1 |
includeScoreBreakdown |
boolean | No | Include detailed score breakdown per item. Default: false |
Response Format
{
"referenceId": "article-001",
"corpusSize": 2,
"relatedCount": 2,
"relatedItems": [
{
"id": "article-002",
"score": 0.847293,
"title": "Deep Learning Fundamentals",
"category": "technology",
"tags": ["ai", "deep-learning", "neural-networks"],
"sharedTerms": ["learning", "neural", "network"],
"sharedTagCount": 1,
"breakdown": null,
"metadata": null
},
{
"id": "article-003",
"score": 0.234158,
"title": "Introduction to Python",
"category": "programming",
"tags": ["python", "programming", "beginner"],
"sharedTerms": ["programming"],
"sharedTagCount": 0,
"breakdown": null,
"metadata": null
}
],
"processingTimeMs": 12.34
}
Response Fields
| Field | Type | Description |
|---|---|---|
referenceId |
string | ID of the reference item used for matching |
corpusSize |
number | Total number of items in the corpus |
relatedCount |
number | Number of related items returned |
relatedItems |
array | Array of related items sorted by relevance |
relatedItems[].id |
string | ID of the matched item |
relatedItems[].score |
number | Overall similarity score (0-1) |
relatedItems[].title |
string | null | Title of the matched item |
relatedItems[].category |
string | null | Category of the matched item |
relatedItems[].tags |
string[] | null | Tags of the matched item |
relatedItems[].sharedTerms |
array | Terms shared between reference and matched item |
relatedItems[].sharedTagCount |
number | Number of shared tags |
relatedItems[].breakdown |
object | null | Score breakdown (only if includeScoreBreakdown is true) |
relatedItems[].breakdown.tfidfScore |
number | TF-IDF cosine similarity component score |
relatedItems[].breakdown.jaccardScore |
number | Jaccard similarity component score |
relatedItems[].breakdown.categoryBonus |
number | Category match bonus applied |
relatedItems[].breakdown.tagBonus |
number | Tag overlap bonus applied |
relatedItems[].metadata |
object | null | Pass-through metadata from the corpus item |
processingTimeMs |
number | Processing time in milliseconds |
Use Cases
Content Recommendations
Power "related articles" or "you might also like" sections on your blog, news site, or content platform with intelligent suggestions.
Related Articles
Automatically suggest related research papers, documentation pages, or knowledge base articles based on content similarity.
Product Suggestions
Recommend similar products based on descriptions, categories, and tags to increase cross-selling opportunities.
Build Constraints
Pure Computation
This API performs all calculations in-memory without external dependencies. No database or ML models required—just efficient vector math.
Configurable Threshold
Set a minimum similarity score threshold via options.minScore to filter out low-quality matches.
Max Results Limit
Control the number of returned results with the maxResults parameter. Default is 10, maximum is 100.
Score Breakdown
Every match includes a detailed breakdown (when includeScoreBreakdown is true) showing individual component scores for transparency.
Error Codes
| Code | Status | Description |
|---|---|---|
400 |
Bad Request | Invalid request body or missing required parameters |
401 |
Unauthorized | Missing or invalid API key |
413 |
Payload Too Large | Corpus exceeds maximum size limit (10MB) |
422 |
Unprocessable Entity | Invalid algorithm specified or malformed content items |
429 |
Too Many Requests | Rate limit exceeded |
500 |
Server Error | Internal processing error |
Ready to get started?
Start finding related content with intelligent similarity matching. Get your API key and make your first request in minutes.
MCP Integration MCP Ready
What is MCP?
Model Context Protocol (MCP) allows AI assistants like Claude to call this API as a native tool during conversation. Instead of writing HTTP requests, the AI invokes the tool directly — no API keys or boilerplate needed on the client side.
Tool Details
RelatedContentTools
FindRelatedContent()
Description
Finds related content items using vector similarity matching