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 /map endpoint returns the entire corpus as a flat list of 2D scatter plot points, ready to render a visual knowledge map. Each point carries a UMAP-projected (x, y) coordinate pair computed at ingestion time by the inference service’s /predict endpoint, along with the item’s ID, title, and category. The map gives users a spatial overview of how topics cluster — items close together in the 2D plane share similar semantic content. Because the coordinates are stored at ingestion time and returned verbatim, this endpoint makes no inference call and performs a single SELECT against Oracle.

​
Endpoint

GET /map

​
Query Parameters

This endpoint accepts no query parameters. All items with non-null coordinates are returned in a single response.

​
How Coordinates Are Generated

At ingestion time, the inference service’s /predict endpoint runs umap_reducer.transform(embedding) on the item’s 384-dimensional embedding to produce a 2D (x, y) coordinate. These values are written to the x and y columns of the contents table and are never recomputed. The map endpoint reads them back with: 
SELECT id, title, category, x, y
FROM contents
WHERE x IS NOT NULL AND y IS NOT NULL
Items that were seeded into the corpus before the inference service was available have x = NULL and y = NULL in the database and are excluded from this query entirely.

​
Response — 200 OK

Returns a JSON array of MapPoint objects. There is no wrapper envelope.
​
id
string
The content item’s unique identifier (e.g. "devto-4821", "so-55190").
​
title
string
The content item’s title.
​
category
string
The content item’s category label (stored in Spanish, e.g. "Backend", "Bases de datos"). One of the 8 corpus categories.
​
x
number
UMAP x coordinate. A floating-point value with no fixed range — scale depends on the UMAP model’s output space.
​
y
number
UMAP y coordinate. A floating-point value with no fixed range — scale depends on the UMAP model’s output space.
The map endpoint returns all items in the corpus in a single response with no pagination. For small to medium corpora this is intentional — the full dataset is needed to render a meaningful scatter plot. For very large corpora, the payload size may become significant; plan for this at the client layer (e.g. virtualise the canvas renderer, not the data fetch).
Items without stored coordinates (seeded before the inference service was configured) are excluded by the WHERE x IS NOT NULL AND y IS NOT NULL clause in Oracle and will not appear in the response. If a known item is missing from the map, its embedding and UMAP coordinates were never computed. Re-ingesting the item through POST /content will generate coordinates.

​
Error Codes

HTTP Statuserror fieldCause
503INTERNAL_ERRORThe database is not configured (app.database.enabled=true is required)
Error response envelope: 
{
  "error": "INTERNAL_ERROR",
  "message": "Base de datos no configurada. Use app.database.enabled=true",
  "timestamp": "2024-11-18T14:22:03.441Z"
}

​
Examples

​
Fetch all map points

curl http://localhost:8080/map

[
  {
    "id": "devto-4821",
    "title": "Intro to Spring Boot",
    "category": "Backend",
    "x": 2.14,
    "y": -0.87
  },
  {
    "id": "so-55190",
    "title": "Índices vectoriales en Oracle",
    "category": "Bases de datos",
    "x": 4.21,
    "y": -1.07
  },
  {
    "id": "so-78412",
    "title": "Cómo paginar con Spring Data JPA",
    "category": "Backend",
    "x": 2.09,
    "y": -0.74
  }
]

​
503 — database not configured

curl http://localhost:8080/map

{
  "error": "INTERNAL_ERROR",
  "message": "Base de datos no configurada. Use app.database.enabled=true"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us