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.

List endpoints let you group nodes into named, ordered collections. Lists support per-node ratings and integer position values so members can be arranged in any order. Pass a list ID as ?listId=<id> in the graph view URL to restrict the graph to only that list’s nodes — useful for curating reading lists, film selections, or any thematic subset of your library.

​
GET /api/lists

Retrieve all lists ordered by creation date ascending. Node members are not included in this response; use GET /api/lists/:id to fetch a list with its nodes.

​
Response

Returns a JSON array of List objects. 
curl http://localhost:3000/api/lists

[
  {
    "id": "ab3x",
    "name": "Filosofía Política",
    "description": "Lecturas sobre teoría del estado y poder.",
    "createdAt": "2024-01-10T09:00:00.000Z",
    "updatedAt": "2024-01-10T09:00:00.000Z"
  }
]

​
POST /api/lists

Create a new list. List IDs are 4-character lowercase alphanumeric strings (e.g., ab3x) generated automatically, with a retry loop to guarantee uniqueness. If name is omitted the generated ID is used as the list name.

​
Request body

​
name
string
Display name for the list. Maximum 200 characters. Whitespace is trimmed. Defaults to the generated ID if omitted.
​
description
string
Optional longer description. Maximum 2000 characters.

​
Response

Returns 201 Created with the created List object. 
curl -X POST http://localhost:3000/api/lists \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Filosofía Política",
    "description": "Lecturas sobre teoría del estado y poder."
  }'

{
  "id": "ab3x",
  "name": "Filosofía Política",
  "description": "Lecturas sobre teoría del estado y poder.",
  "createdAt": "2024-01-10T09:00:00.000Z",
  "updatedAt": "2024-01-10T09:00:00.000Z"
}

​
GET /api/lists/:id

Fetch a single list along with all of its member nodes, ordered by position ascending.

​
Path parameters

​
id
string
required
The 4-character list ID.

​
Response

Returns a ListWithNodes object: all List fields plus a nodes array. Each element in nodes is a full Node object with two additional list-specific fields:
​
nodes[].position
number
Zero-based integer index of the node within the list.
​
nodes[].listRating
number | null
Optional integer rating assigned to this node within the list context. null if no rating has been set.
curl http://localhost:3000/api/lists/ab3x

{
  "id": "ab3x",
  "name": "Filosofía Política",
  "description": "Lecturas sobre teoría del estado y poder.",
  "createdAt": "2024-01-10T09:00:00.000Z",
  "updatedAt": "2024-01-10T09:00:00.000Z",
  "nodes": [
    {
      "id": "uuid-of-marx",
      "title": "El Capital",
      "type": "libro",
      "position": 0,
      "listRating": 9,
      "..."
    }
  ]
}
Returns 404 if the list does not exist.

​
PUT /api/lists/:id

Update the name and/or description of an existing list.

​
Path parameters

​
id
string
required
The 4-character list ID.

​
Request body

​
name
string
New display name. Maximum 200 characters, trimmed. Cannot be an empty string.
​
description
string
New description. Maximum 2000 characters. Pass null to clear.

​
Response

Returns the updated List object, or 404 if the list does not exist. 
curl -X PUT http://localhost:3000/api/lists/ab3x \
  -H "Content-Type: application/json" \
  -d '{ "name": "Teoría Política Clásica" }'

​
DELETE /api/lists/:id

Delete a list and all of its membership records. The nodes themselves are not deleted — they remain in the database and graph.

​
Path parameters

​
id
string
required
The 4-character list ID.

​
Response

Returns { "success": true } on success, or 404 if the list does not exist. 
curl -X DELETE http://localhost:3000/api/lists/ab3x

{ "success": true }

​
POST /api/lists/:id/nodes

Add a node to a list. The node is appended at the end: its position is set to the current maximum position in the list plus one (starting from 0 for the first member).

​
Path parameters

​
id
string
required
The 4-character list ID.

​
Request body

​
nodeId
string
required
UUID of the node to add.

​
Response

Returns 201 Created with the new list-node membership entry. Returns 409 Conflict if the node is already a member of the list. Returns 404 if the list or the node does not exist. 
curl -X POST http://localhost:3000/api/lists/ab3x/nodes \
  -H "Content-Type: application/json" \
  -d '{ "nodeId": "uuid-of-marx" }'

{
  "id": "membership-uuid",
  "listId": "ab3x",
  "nodeId": "uuid-of-marx",
  "position": 0,
  "createdAt": "2024-01-15T10:00:00.000Z"
}

​
DELETE /api/lists/:id/nodes/:nodeId

Remove a node from a list. The node itself is not deleted from the database — only the list membership is removed.

​
Path parameters

​
id
string
required
The 4-character list ID.
​
nodeId
string
required
UUID of the node to remove.

​
Response

Returns { "success": true } on success, or 404 if the membership does not exist. 
curl -X DELETE http://localhost:3000/api/lists/ab3x/nodes/uuid-of-marx

{ "success": true }

​
PUT /api/lists/:id/nodes/:nodeId/rating

Set or clear the rating for a specific node within a list. Ratings are scoped to the list — the same node can have different ratings in different lists.

​
Path parameters

​
id
string
required
The 4-character list ID.
​
nodeId
string
required
UUID of the node to rate.

​
Request body

​
rating
number | null
required
Integer rating to assign. Pass null to clear an existing rating.

​
Response

Returns { "success": true } on success, or 404 if the node is not a member of the list. 
curl -X PUT http://localhost:3000/api/lists/ab3x/nodes/uuid-of-marx/rating \
  -H "Content-Type: application/json" \
  -d '{ "rating": 9 }'

# Clear a rating
curl -X PUT http://localhost:3000/api/lists/ab3x/nodes/uuid-of-marx/rating \
  -H "Content-Type: application/json" \
  -d '{ "rating": null }'

​
PUT /api/lists/:id/nodes/reorder

Reorder all nodes in a list by supplying the complete ordered array of node IDs. Each node’s position is set to its index in the supplied array.
Send the full list of node IDs in every call — partial arrays will leave omitted nodes with their old positions rather than removing them.

​
Path parameters

​
id
string
required
The 4-character list ID.

​
Request body

​
nodeIds
string[]
required
Fully ordered array of node UUIDs. The node at index 0 receives position: 0, index 1 receives position: 1, and so on.

​
Response

Returns { "success": true } on success, or 404 if the list does not exist. 
curl -X PUT http://localhost:3000/api/lists/ab3x/nodes/reorder \
  -H "Content-Type: application/json" \
  -d '{
    "nodeIds": [
      "uuid-of-marx",
      "uuid-of-hegel",
      "uuid-of-kant"
    ]
  }'

{ "success": true }

​
TypeScript interfaces

The List and ListWithNodes types returned by these endpoints are defined in @babel-plus/shared: 
export interface List {
  id: string          // 4-character alphanumeric, e.g. "ab3x"
  name: string
  description: string | null
  createdAt: string
  updatedAt: string
}

export interface ListWithNodes extends List {
  nodes: (Node & {
    position: number        // zero-based integer order within the list
    listRating: number | null
  })[]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us