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.

When you submit a piece of technical content to Mindloom, far more happens than a simple database write. The POST /content endpoint orchestrates a four-layer pipeline: it forwards the body text to the inference service, receives a full semantic analysis, persists the result across two distinct database writes, and queries the five nearest semantic neighbors — all within a single HTTP request. By the time the 201 response arrives in your client, the content is classified, embedded, and wired into the knowledge graph.

​
What happens during ingestion

1

Request received by the API

Your client sends a JSON body with exactly two fields — title and body — to POST /content. Both are required; a blank value on either field returns 400 VALIDATION_ERROR before any downstream service is called.
{
  "title": "Índices vectoriales en Oracle",
  "body": "VECTOR_DISTANCE con COSINE compara embeddings normalizados sin recorrer la tabla completa."
}
2

Inference service call — /predict

The API POSTs the body text (and only the body) to the inference service’s /predict endpoint under the key text:
{ "text": "VECTOR_DISTANCE con COSINE compara embeddings normalizados sin recorrer la tabla completa." }
The inference service receives only the body, never the title. If you submit a request with a meaningful title but an empty or trivial body, the classifier makes its decision on near-empty text and the result will be unreliable.
The inference service returns everything the API needs in a single response:
{
  "category": "Bases de datos",
  "probability": 0.91,
  "keywords": ["oracle", "vector", "cosine"],
  "explanation": ["vector", "distance", "oracle"],
  "embedding": [0.021, -0.118, "… 384 floats, L2-normalised, float32"],
  "cluster_id": 3,
  "x": 4.21,
  "y": -1.07
}
3

Two-phase database write

The API writes the content to Oracle ADB in two separate statements — not one. JPA handles all structured fields, but cannot map Oracle’s VECTOR(384, FLOAT32) column type. A second, explicit JDBC UPDATE stores the embedding by passing the float array as a bracket-delimited string into TO_VECTOR(?, 384, FLOAT32):
-- Phase 1 — JPA INSERT (embedding column omitted)
INSERT INTO contents (id, title, body, category, probability, keywords,
                      explanation, cluster_id, x, y, source, language, added_at)
VALUES ('usr-9f3c1e0a-…', 'Índices vectoriales en Oracle', '…',
        'Bases de datos', 0.91, '["oracle","vector","cosine"]',
        '["vector","distance","oracle"]', 3, 4.21, -1.07,
        'user', 'es', TIMESTAMP '2026-07-28 10:32:41');

-- Phase 2 — JDBC UPDATE via TO_VECTOR string conversion
UPDATE contents SET embedding = TO_VECTOR(?, 384, FLOAT32) WHERE id = 'usr-9f3c1e0a-…';
The ? placeholder receives the embedding as a bracket-delimited string produced by VectorUtils.toVectorString() (e.g. [0.021,-0.118,…]), which Oracle’s TO_VECTOR function parses into the native VECTOR column type.
If the JDBC UPDATE is ever omitted (for example, in a custom ingestion path that only calls JPA), the row is inserted without a vector. It will appear in listing endpoints but will be completely invisible to all semantic searches and all related lookups — with no error and no log entry.
4

Related content query

Still within the same transaction, the API immediately uses the newly written embedding to find the five most semantically similar items already in the corpus:
SELECT id, title, category,
       1 - VECTOR_DISTANCE(embedding, TO_VECTOR(:sourceEmbedding, 384, FLOAT32), COSINE) AS similarity
FROM contents
WHERE id <> 'usr-9f3c1e0a-…'
ORDER BY VECTOR_DISTANCE(embedding, TO_VECTOR(:sourceEmbedding, 384, FLOAT32), COSINE)
FETCH FIRST 5 ROWS ONLY;
These become the related array in the response. No second API call is required.
5

201 Created response

The API returns HTTP 201 with the enriched result. The title, body, raw embedding, clusterId, x, and y values are intentionally omitted from the response.
{
  "id": "usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44",
  "category": "Bases de datos",
  "probability": 0.91,
  "keywords": ["oracle", "vector", "cosine"],
  "related": [
    {
      "id": "so-55190",
      "title": "Índices y planes de ejecución",
      "category": "Bases de datos",
      "similarity": 0.7311
    }
  ],
  "explanation": ["vector", "distance", "oracle"]
}

​
Response fields explained

category

One of the 8 fixed taxonomy values, always returned in Spanish. Determined by the inference service classifier.

probability

Classifier confidence for the assigned category, expressed as a float between 0 and 1 (e.g. 0.91 = 91 % confidence).

keywords

Salient terms extracted from the body by the inference service. Used for display and discovery.

explanation

TF-IDF terms from the baseline classifier that drove the category decision. Distinct from keywords — these are the discriminative features, not the most frequent words.

related

Up to 5 semantically nearest items, computed at ingestion time using the new embedding. Free — no extra API call needed.

id

Auto-generated string in the format usr-{UUID}. The usr- prefix identifies content submitted by users, as opposed to seeded corpus items.

​
The 8 content categories

All content is classified into one of these fixed categories. The inference service returns them in Spanish; they are stored and returned as-is throughout the system.

Backend

Frontend

Móvil

Datos e IA

DevOps y Cloud

Bases de datos

Seguridad

Fundamentos

​
Request reference

FieldTypeRequiredConstraints
titlestringYesNon-blank (@NotBlank)
bodystringYesNon-blank (@NotBlank)
The id, category, source ("user"), and language ("es") fields are assigned by the API — they cannot be set by the caller.

​
Key behaviours to remember

Every ingestion issues an INSERT (JPA) followed by an UPDATE (JDBC). This is by design: JPA’s entity model does not include the embedding field because the VECTOR column type is not supported by the JPA provider. The JDBC UPDATE passes the embedding as a bracket-delimited string via VectorUtils.toVectorString() into TO_VECTOR(?, 384, FLOAT32). Any alternative write path that skips the JDBC UPDATE silently produces orphaned rows.
For the full parameter reference, HTTP error codes, and validation rules, see the POST /content API reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us