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.

Smart Add is the fastest way to grow your knowledge graph. Describe a book, film, article, or any other content item in plain text and BaBel+ will classify it, extract structured metadata, and automatically connect it to semantically related nodes already in your graph — all in a single HTTP request. No form filling, no manual tagging, no relation wiring.

​
Endpoint

POST /api/ai/smart-add

​
Request

​
Body parameters

​
text
string
required
Free-text description of the content you want to add. The server trims leading/trailing whitespace and enforces a hard maximum of 10 000 characters. Write naturally — the model handles the rest.
​
typeHint
string
Optional node type override. Must be one of: libro, pelicula, articulo, video, curso, videojuego. When provided, the model is explicitly instructed to use this type and will not attempt to infer it from the text. Mirrors the Auto / type selector dropdown in the QuickAdd UI component.

​
Example request

curl -X POST http://localhost:3000/api/ai/smart-add \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Being and Time by Martin Heidegger, 1927. A foundational work of existential phenomenology that analyzes the structure of human existence (Dasein) and its relation to time and being.",
    "typeHint": "libro"
  }'

​
Response

​
201 Created

Returns the persisted node and every relation that was successfully resolved against the database. Relation targets are matched case-insensitively against existing node titles; only matches that are actually found in the database appear in the relations array.
​
node
Node object
The fully persisted node record, including its generated UUID and timestamps.
​
relations
CreatedRelation[]
Array of relation records inserted into the database. Empty if no existing nodes matched the model’s suggestions.

​
Example response

{
  "node": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Being and Time",
    "type": "libro",
    "description": "Foundational work of existential phenomenology analyzing the structure of human existence.",
    "status": "pendiente",
    "priority": "media",
    "tags": "[\"filosofia\",\"fenomenologia\",\"existencialismo\",\"heidegger\"]",
    "author": "Martin Heidegger",
    "year": 1927,
    "link": null,
    "localFile": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "relations": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "sourceId": "550e8400-e29b-41d4-a716-446655440000",
      "targetId": "existing-node-id",
      "type": "trata_sobre",
      "weight": 1.0,
      "targetTitle": "Fenomenología del Espíritu"
    }
  ]
}

​
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, bad API key, rate limit).
500 Internal Server ErrorThe model returns a response that cannot be parsed as valid JSON.

​
typeHint behavior

When typeHint is provided the server prepends the following instruction to the model prompt before all other classification rules:
“IMPORTANTE: El usuario seleccionó manualmente el tipo <typeHint>. DEBES usar exactamente ese type, no intentes inferirlo.”
This hard override ensures the model respects your intent even when the text is ambiguous. For example, a short-form essay could be classified as either articulo or libro — passing typeHint: "articulo" resolves the ambiguity deterministically.
Leave typeHint empty (or omit it entirely) to let the model infer the best type from your description. The six supported types are libro, pelicula, articulo, video, curso, and videojuego.

​
Idempotency

Smart Add always creates a new node. It does not check whether a node with the same title already exists. Calling the endpoint twice with identical text will produce two separate nodes in the database. If you need to check for duplicates before committing, call POST /api/ai/classify first, inspect the suggested title, and confirm there is no existing node with that name before proceeding.

​
UI integration

The QuickAdd React component in the client uses this endpoint directly. It renders a type selector (populated from the shared NODE_TYPES constant) and a free-text input. On submit it calls api.ai.smartAdd(text, typeHint), displays a terminal-style confirmation block with the created node title and the list of connected relations, and calls onAdded() to refresh the graph. If a listId prop is passed, the new node is also appended to that list automatically. Access QuickAdd from the sidebar panel or the quick-add button on the graph canvas.

Build docs developers (and LLMs) love

Get started for freeTalk to us