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 POST /content endpoint is the primary ingestion gateway for Mindloom’s knowledge pipeline. When you submit a content item, the API validates the request, forwards the body text to the inference service for classification and embedding, persists the result to the database (including the 384-dimension vector), and runs a cosine-similarity search to surface the most semantically related items already in the corpus — all within a single atomic transaction. The response gives you the assigned category, confidence score, top keywords, explainability terms, and up to five related items, so your UI can render a rich result page without making a second API call.

​
Endpoint

POST /content

​
Request body

​
title
string
required
The title of the content item. Must not be blank. Stored in the database and displayed in listings, but not forwarded to the inference service for classification.
​
body
string
required
The full text of the content item. Must not be blank. This is the only field sent to the inference service — classification, keyword extraction, and embedding are all derived from body.
Only body is forwarded to the inference service. title is stored in the database and returned in listing responses, but it plays no role in category prediction, keyword extraction, or embedding generation.

​
Example request

curl -X POST http://localhost:8080/content \
  -H 'Content-Type: application/json' \
  -d '{"title":"Intro to Spring Boot","body":"Spring Boot makes it easy to create stand-alone REST APIs with Java."}'

​
Response — 201 Created

​
id
string
The generated ID for the newly created content item. Always has the format usr- followed by a UUID (e.g. usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44). Items seeded from external corpora use different prefixes (e.g. so-, devto-).
​
category
string
The category assigned by the classifier. One of the eight supported labels: Backend, Frontend, Bases de datos, DevOps, Arquitectura, Testing, Seguridad, or Mobile.
​
probability
number
The classifier’s confidence score for the assigned category, expressed as a value between 0 and 1 (e.g. 0.91 = 91 % confidence).
​
keywords
string[]
An array of up to five top keywords extracted from the body text using TF-IDF scoring.
​
related
object[]
An array of up to five semantically similar content items already present in the corpus at ingestion time, ranked by cosine similarity to the newly inserted vector. Computed server-side using Oracle VECTOR_DISTANCE; no second call is needed.
​
explanation
string[]
The top terms from the baseline TF-IDF explainable classifier that most influenced the category decision. Distinct from keywords: these reflect the model’s reasoning path, not just term frequency.
related is computed at ingestion time using the vector of the item just inserted. Because the similarity search runs within the same transaction, the new item’s vector is immediately available to the database. Your frontend can populate a “Related Articles” sidebar directly from this field — no follow-up request to GET /contents/{id} or a search endpoint is required.

​
Example response

{
  "id": "usr-9f3c1e0a-42b8-4d17-9a55-7c0e1b2d3f44",
  "category": "Backend",
  "probability": 0.91,
  "keywords": ["spring", "boot", "java", "rest", "api"],
  "related": [
    {
      "id": "so-78412",
      "title": "Cómo paginar con Spring Data JPA",
      "category": "Backend",
      "similarity": 0.8117
    }
  ],
  "explanation": ["spring", "boot", "java"]
}

​
Error responses

All errors follow the ApiError envelope defined in GlobalExceptionHandler. Every error response contains three fields:
FieldTypeDescription
errorstringMachine-readable error code (e.g. VALIDATION_ERROR, INTERNAL_ERROR).
messagestringHuman-readable description of what went wrong, in Spanish.
timestampstringISO 8601 UTC timestamp of when the error was generated (e.g. "2026-07-28T10:32:41.123456Z").
HTTP Statuserror codeWhen it occurs
400 Bad RequestVALIDATION_ERRORtitle or body is missing or blank (@NotBlank constraint). The message identifies the offending field: "El campo 'title' no puede estar vacío".
503 Service UnavailableINTERNAL_ERRORThe database is not configured (scaffold / demo mode). Start the API with app.database.enabled=true to enable ingestion.

​
Example error — 400 Validation Error

{
  "error": "VALIDATION_ERROR",
  "message": "El campo 'body' no puede estar vacío",
  "timestamp": "2026-07-28T10:32:41.123456Z"
}

​
Example error — 503 Service Unavailable

{
  "error": "INTERNAL_ERROR",
  "message": "Base de datos no configurada. Use app.database.enabled=true",
  "timestamp": "2026-07-28T10:32:41.123456Z"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us