Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/No-Country-simulation/G9-LATAM-Team-58/llms.txt

Use this file to discover all available pages before exploring further.

The /contents/{id}/related endpoint finds content items that are semantically close to a given item — not by tag overlap or shared category, but by actual vector proximity. The API retrieves the queried item’s stored embedding from Oracle, then runs VECTOR_DISTANCE(COSINE) against every other row in the contents table, returning the top limit results ordered from most to least similar. Because the comparison is vector-to-vector (no inference service call at query time), this endpoint is fast and depends only on the database being available.

​
Endpoint

GET /contents/{id}/related

​
Path Parameters

​
id
string
required
The unique identifier of the content item to find related content for (e.g. "usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44", "devto-4821"). Returns 404 NOT_FOUND if no item with this ID exists in the corpus.

​
Query Parameters

​
limit
integer
default:"5"
Maximum number of related items to return. Maps directly to FETCH FIRST :limit ROWS ONLY in the Oracle native query.

​
How It Works

The service executes two queries against Oracle:
  1. Fetch the source embedding — VECTOR_SERIALIZE(embedding) for the requested id.
  2. Find neighbours — VECTOR_DISTANCE(COSINE) between the serialised source vector and every other row’s embedding column, excluding the source row itself (WHERE id <> :baseId). Results are ordered ascending by distance (descending similarity) and capped at limit.
Oracle query: 
SELECT id, title, category,
       1 - VECTOR_DISTANCE(embedding, TO_VECTOR(:sourceEmbedding, 384, FLOAT32), COSINE) AS similarity
FROM contents
WHERE id <> :baseId
ORDER BY VECTOR_DISTANCE(embedding, TO_VECTOR(:sourceEmbedding, 384, FLOAT32), COSINE)
FETCH FIRST :limit ROWS ONLY
The similarity value is 1 - VECTOR_DISTANCE(…, COSINE): 1.0 means an identical vector, values near 0 indicate no meaningful relationship.

​
Response — 200 OK

RelatedContentResponse
​
id
string
The ID of the queried content item (echoed from the path parameter).
​
title
string
The title of the queried content item.
​
related
object[]
Ordered list of related content items, from most similar to least similar.
Items seeded into the corpus before the inference service was set up may have no embedding stored (embedding IS NULL). These items will never appear in related results because VECTOR_DISTANCE requires a non-null vector to compare against. If the queried item itself has no stored embedding, the endpoint will still respond — but the neighbour set will be empty or contain only items that do have embeddings.

​
Error Codes

HTTP Statuserror fieldCause
404NOT_FOUNDNo content item exists with the given id
503INTERNAL_ERRORThe database is not configured (app.database.enabled=true is required)
Error response envelope: 
{
  "error": "NOT_FOUND",
  "message": "Content not found: usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44",
  "timestamp": "2024-11-18T14:22:03.441Z"
}

​
Examples

​
Fetch related content

curl 'http://localhost:8080/contents/usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44/related?limit=3'

{
  "id": "usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44",
  "title": "Intro to Spring Boot",
  "related": [
    {
      "id": "so-78412",
      "title": "Cómo paginar con Spring Data JPA",
      "category": "Backend",
      "similarity": 0.8117
    },
    {
      "id": "devto-9034",
      "title": "Spring Boot Auto-configuration Explained",
      "category": "Backend",
      "similarity": 0.7943
    },
    {
      "id": "so-55190",
      "title": "Índices vectoriales en Oracle",
      "category": "Bases de datos",
      "similarity": 0.6812
    }
  ]
}

​
Default limit (5 results)

curl 'http://localhost:8080/contents/devto-4821/related'

​
404 — item not found

curl 'http://localhost:8080/contents/nonexistent-id/related'

{
  "error": "NOT_FOUND",
  "message": "Content not found: nonexistent-id"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us