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.

Nodes are the primary resource in BaBel+. They represent individual content items — books, films, articles, videos, courses, or video games — and carry rich metadata such as status, priority, tags, author, and year. Every other resource (relations, list memberships) references nodes by their UUID id. These endpoints let you create, retrieve, update, and delete nodes programmatically.

​
Node TypeScript interface

The canonical shape of a node as defined in the shared package: 
// packages/shared/src/types.ts

export type NodeType     = 'libro' | 'pelicula' | 'articulo' | 'video' | 'curso' | 'videojuego'
export type NodeStatus   = 'pendiente' | 'en_progreso' | 'terminado' | 'abandonado'
export type NodePriority = 'alta' | 'media' | 'baja'

export interface Node {
  id:          string          // UUID v4, auto-generated
  title:       string
  type:        NodeType
  description: string | null
  status:      NodeStatus
  priority:    NodePriority
  tags:        string | null   // JSON-serialised string[] stored as TEXT
  author:      string | null
  year:        number | null
  link:        string | null
  localFile:   string | null
  rating:      number | null
  createdAt:   string          // ISO 8601
  updatedAt:   string          // ISO 8601
}
tags is stored in the database as a JSON-serialised string (e.g. "[\"filosofia\",\"posmodernismo\"]"). The API returns it in that form; parse it with JSON.parse() on the client if you need an array.

​
GET /api/nodes

List all nodes. Optionally filter by type and/or status using query parameters. Results are returned in insertion order (no guaranteed sort unless combined with client-side sorting).

​
Query parameters

​
type
string
Filter by node type. Must be one of: libro, pelicula, articulo, video, curso, videojuego. Omit to return all types.
​
status
string
Filter by lifecycle status. Must be one of: pendiente, en_progreso, terminado, abandonado. Omit to return all statuses.

​
Response

Returns a JSON array of Node objects. Returns an empty array [] when no nodes match the filter.
​
(array)
Node[]
Array of node objects. See the Node interface above for field definitions.

​
Example

# List all nodes
curl http://localhost:3000/api/nodes

# Filter to pending books only
curl "http://localhost:3000/api/nodes?type=libro&status=pendiente"

[
  {
    "id": "3f2a1b4c-...",
    "title": "Simulacra and Simulation",
    "type": "libro",
    "description": null,
    "status": "pendiente",
    "priority": "media",
    "tags": "[\"filosofia\",\"posmodernismo\",\"simulacro\"]",
    "author": "Jean Baudrillard",
    "year": 1981,
    "link": null,
    "localFile": null,
    "rating": null,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
]

​
GET /api/nodes/:id

Retrieve a single node by its UUID.

​
Path parameters

​
id
string
required
The UUID of the node to retrieve.

​
Response

​
id
string
UUID of the node.
​
title
string
Display title.
​
type
NodeType
Content type: libro, pelicula, articulo, video, curso, or videojuego.
​
description
string | null
Long-form description, or null if not set.
​
status
NodeStatus
Lifecycle status: pendiente, en_progreso, terminado, or abandonado.
​
priority
NodePriority
Priority level: alta, media, or baja.
​
tags
string | null
JSON-serialised array of tag strings, or null.
​
author
string | null
Author or creator name, or null.
​
year
number | null
Publication or release year, or null.
​
link
string | null
External URL, or null.
​
localFile
string | null
Path to a local file, or null.
​
rating
number | null
Numeric rating, or null.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-update timestamp.

​
Errors

StatusBodyCondition
404{ "error": "not found" }No node with the given ID exists

​
Example

curl http://localhost:3000/api/nodes/3f2a1b4c-1234-5678-abcd-ef0123456789

​
POST /api/nodes

Create a new node. The server auto-generates a UUID id and sets both createdAt and updatedAt to the current UTC time. Returns the created node with status 201 Created.

​
Request body

​
title
string
required
Display title of the node. Maximum 500 characters. Whitespace is trimmed automatically.
​
type
NodeType
Content type. If provided, must be one of: libro, pelicula, articulo, video, curso, videojuego.
​
description
string
Long-form description or notes. Maximum 5 000 characters. Silently truncated to 5 000 if longer.
​
status
NodeStatus
Lifecycle status. Default: pendiente. One of: pendiente, en_progreso, terminado, abandonado.
​
priority
NodePriority
Priority level. Default: media. One of: alta, media, baja.
​
tags
string[]
Array of tag strings. Maximum 50 items; extra items are silently dropped.
​
author
string
Author or creator name. Maximum 300 characters.
​
year
number
Publication or release year as an integer. Must be in the range −5 000 to 3 000.
​
link
string
External URL. Maximum 2 000 characters.
​
localFile
string
Path to a local file on the server’s filesystem. Maximum 500 characters.

​
Response

Returns 201 Created with the full Node object, including the generated id, createdAt, and updatedAt fields.

​
Errors

StatusBodyCondition
400{ "error": "title is required" }title is missing, empty, or not a string
400{ "error": "title too long (max 500)" }title exceeds 500 characters
400{ "error": "invalid type, must be one of: ..." }type is not a valid NodeType
400{ "error": "invalid status, must be one of: ..." }status is not a valid NodeStatus
400{ "error": "invalid priority, must be one of: ..." }priority is not a valid NodePriority
400{ "error": "invalid year" }year is not a number or is outside −5 000 – 3 000

​
Example

curl -X POST http://localhost:3000/api/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Simulacra and Simulation",
    "type": "libro",
    "author": "Jean Baudrillard",
    "year": 1981,
    "status": "pendiente",
    "priority": "media",
    "tags": ["filosofia", "posmodernismo", "simulacro"]
  }'

​
PUT /api/nodes/:id

Partially update an existing node. Only fields present in the request body are changed — omitted fields retain their current values. updatedAt is always refreshed to the current UTC time regardless of which fields are updated.

​
Path parameters

​
id
string
required
The UUID of the node to update.

​
Request body

All fields are optional. Include only the fields you want to change. The same constraints from POST /api/nodes apply to each field.
​
title
string
New title. Trimmed and truncated to 500 characters. Cannot be set to an empty string.
​
type
NodeType
New content type. One of: libro, pelicula, articulo, video, curso, videojuego.
​
description
string | null
New description. Pass null to clear. Truncated to 5 000 characters.
​
status
NodeStatus
New lifecycle status. One of: pendiente, en_progreso, terminado, abandonado.
​
priority
NodePriority
New priority. One of: alta, media, baja.
​
tags
string[]
Replacement tag array. Replaces the entire tags value (not merged). Pass an empty array [] to clear.
​
author
string | null
New author. Pass null to clear. Truncated to 300 characters.
​
year
number | null
New year. Pass null to clear. Range −5 000 to 3 000.
​
link
string | null
New URL. Pass null to clear. Truncated to 2 000 characters.
​
localFile
string | null
New local file path. Pass null to clear. Truncated to 500 characters.
​
rating
number | null
New rating. Pass null to clear.

​
Response

Returns 200 OK with the full updated Node object as re-fetched from the database.

​
Errors

StatusBodyCondition
400{ "error": "title cannot be empty" }title is provided but is an empty or blank string
404{ "error": "not found" }No node with the given ID exists

​
Example

# Mark a node as finished and add a rating
curl -X PUT http://localhost:3000/api/nodes/3f2a1b4c-1234-5678-abcd-ef0123456789 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "terminado",
    "rating": 9
  }'
To clear an optional field, pass it explicitly as null. Omitting a field leaves it unchanged.

​
DELETE /api/nodes/:id

Delete a node permanently. The database schema uses ON DELETE CASCADE on both the relations table and the list_nodes junction table, so all relations and list memberships that reference this node are automatically removed in the same operation.

​
Path parameters

​
id
string
required
The UUID of the node to delete.

​
Response

Returns 200 OK with a confirmation object. The endpoint does not return a 404 if the node does not exist — the delete is a no-op and still returns success. 
{ "success": true }

​
Example

curl -X DELETE http://localhost:3000/api/nodes/3f2a1b4c-1234-5678-abcd-ef0123456789
Deletion is irreversible. All relations connecting this node to other nodes, and all list memberships for this node, are cascade-deleted automatically. There is no soft-delete or recycle bin in the current version.

Build docs developers (and LLMs) love

Get started for freeTalk to us