Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DrDigett/Babel/llms.txt

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

The classify endpoint runs the full AI classification pipeline — sending your text to llama-3.1-8b-instant, extracting structured metadata, and suggesting semantic relations to existing nodes — but does not write anything to the database. Use it to preview what BaBel+ would create before committing, to validate that the model interprets your description correctly, or as the first step in a custom two-phase UI flow where the user reviews and confirms before anything is persisted.

​
Endpoint

POST /api/ai/classify

​
Request

​
Body parameters

​
text
string
required
Free-text description of the content to classify. The server trims whitespace and enforces a maximum of 10 000 characters. The same validation rules apply as for Smart Add.
​
typeHint
string
Optional type override. One of: libro, pelicula, articulo, video, curso, videojuego. When provided, the model is instructed to use this type instead of inferring it from the text.

​
Example request

curl -X POST http://localhost:3000/api/ai/classify \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Discipline and Punish by Michel Foucault (1975). An analysis of how modern institutions use surveillance and normalization to exercise power over populations."
  }'

​
Response

​
200 OK

Returns the AI-suggested node and relations. The structure is identical to the Smart Add response but nothing has been persisted — no node row is inserted, no relation row is inserted.
​
node
ClassifiedNode object
The model’s suggested node. Note that id, localFile, createdAt, and updatedAt are not present in this response because no database record has been created yet.
​
relations
SuggestedRelation[]
Array of relation suggestions from the model. The model receives the full list of existing nodes from the database when generating these suggestions, so targetTitle values are grounded in real node titles. However, unlike Smart Add, the classify endpoint does not perform a server-side lookup to resolve targetTitle values to node UUIDs — that resolution only happens during Smart Add. When you later create the node manually, you will need to resolve each targetTitle to an actual node ID yourself.

​
Example response

{
  "node": {
    "title": "Discipline and Punish",
    "type": "libro",
    "description": "Analysis of how modern institutions use surveillance and normalization to exercise power.",
    "status": "pendiente",
    "priority": "media",
    "tags": ["foucault", "poder", "vigilancia", "instituciones", "filosofia-politica"],
    "author": "Michel Foucault",
    "year": 1975,
    "link": null
  },
  "relations": [
    {
      "targetTitle": "Vigilar y Castigar",
      "type": "similar_a",
      "weight": 0.7
    },
    {
      "targetTitle": "Biopolitica",
      "type": "trata_sobre",
      "weight": 1.0
    }
  ]
}

​
Error responses

StatusCondition
400 Bad Requesttext is missing, empty, or not a string. Body: { "error": "text is required" }
400 Bad Requesttext exceeds 10 000 characters. Body: { "error": "text too long (max 10000)" }
500 Internal Server ErrorThe Groq API call fails (network error, invalid API key, rate limit).
500 Internal Server ErrorThe model returns a response that cannot be parsed as valid JSON.

​
Classify vs Smart Add

POST /api/ai/classifyPOST /api/ai/smart-add
Calls the AI model✅✅
Writes node to database❌✅
Writes relations to database❌✅
Resolves targetTitle to node UUIDs❌✅
Response status200 OK201 Created
Classify is a read-only dry run. Smart Add calls the same classifyAndSuggest function internally and then proceeds to persist the results. If you want the behaviour of classify followed by a persist step, use classify first, show the preview to the user, and then create the node and relations yourself via the standard POST /api/nodes and POST /api/relations endpoints when the user confirms.

​
Building a confirmation UI

1

Call classify with the user's text

Send POST /api/ai/classify with the free-text input. Display the returned node fields (title, type, description, tags, author, year) as an editable form so the user can correct any mistakes before committing.
2

Display suggested relations

Render the relations array to the user. For each suggested targetTitle, look it up in your local node cache to show a link to the existing node. Let the user deselect relations they do not want.
3

Persist on confirmation

When the user confirms, POST /api/nodes with the (possibly edited) node data to create the node. Then POST /api/relations for each relation the user approved, resolving targetTitle to the target node’s id first.
This flow gives you full control over what gets written to the database. It is more work than Smart Add but avoids duplicates and lets users catch mis-classifications before they become graph noise.

Smart Add

Skip the preview step and let BaBel+ classify, create, and connect your node in one call with POST /api/ai/smart-add.

Build docs developers (and LLMs) love

Get started for freeTalk to us