POST Data Processing < 50ms

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
API Key Required

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
  }'

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

200 OK - Success Response
{
  "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.

blogs news media

Related Articles

Automatically suggest related research papers, documentation pages, or knowledge base articles based on content similarity.

docs wiki kb

Product Suggestions

Recommend similar products based on descriptions, categories, and tags to increase cross-selling opportunities.

ecommerce retail marketplace

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

Tool Class
RelatedContentTools
Method
FindRelatedContent()

Description

Finds related content items using vector similarity matching