Skip to main content

​
Overview

The Mindmap API generates hierarchical mindmap structures from your completed notebook research. The endpoint creates a visual representation of the research content organized into topics, subtopics, and key concepts.

​
Generate Mindmap

POST /research/mindmap/{notebook_id}

Generate a mindmap structure from a notebook’s research content

​
Request

​
notebook_id
string
required
The notebook ID containing completed research to generate a mindmap from

​
Response

​
task_id
string
Unique identifier for the mindmap generation task
​
notebook_id
string
The notebook ID where results will be stored
​
status
string
Current task status: IN_QUEUE
​
message
string
Human-readable status message

​
Example Request

curl -X POST https://api.decipherit.com/research/mindmap/nb_123456

​
Example Response

{
  "task_id": "task_mindmap_xyz789",
  "notebook_id": "nb_123456",
  "status": "IN_QUEUE",
  "message": "Mindmap task submitted and will be processed."
}

​
Error Responses

​
404 Not Found
object
​
500 Internal Server Error
object

​
Check Task Status

Once submitted, use the Get Task Status endpoint to monitor progress: 
curl -X GET https://api.decipherit.com/research/task_mindmap_xyz789

​
Example Completed Task Response

{
  "task_id": "task_mindmap_xyz789",
  "notebook_id": "nb_123456",
  "topic": null,
  "sources": null,
  "status": "COMPLETED",
  "created_at": "2026-03-03T10:30:00Z",
  "result": {
    "mindmap": {
      "id": "root",
      "text": "Quantum Computing",
      "display": {"block": true},
      "nodes": [
        {
          "id": "1",
          "text": "Applications",
          "nodes": [
            {
              "id": "1.1",
              "text": "Cryptography",
              "nodes": []
            },
            {
              "id": "1.2",
              "text": "Drug Discovery",
              "nodes": []
            }
          ]
        },
        {
          "id": "2",
          "text": "Challenges",
          "nodes": [
            {
              "id": "2.1",
              "text": "Error Correction",
              "nodes": []
            },
            {
              "id": "2.2",
              "text": "Qubit Coherence",
              "nodes": []
            }
          ]
        }
      ]
    },
    "title": "Quantum Computing Overview",
    "description": "A comprehensive mindmap of quantum computing applications and challenges"
  },
  "error": null,
  "completed_at": "2026-03-03T10:33:28Z",
  "failed_at": null
}

​
Mindmap Structure

The generated mindmap uses a hierarchical dictionary structure:
​
mindmap
object
Hierarchical mindmap structure
​
title
string
Title of the mindmap
​
description
string
Brief description of the mindmap content

​
Alternative Structure Format

The system also supports a flat node-based structure with parent-child relationships:
​
nodes
array
List of all nodes in the mindmap
​
root_id
string
ID of the root/central node

​
Example Alternative Format

{
  "nodes": [
    {
      "id": "root",
      "label": "Quantum Computing",
      "level": 0,
      "parent_id": null,
      "children_ids": ["1", "2"]
    },
    {
      "id": "1",
      "label": "Applications",
      "level": 1,
      "parent_id": "root",
      "children_ids": ["1.1", "1.2"]
    },
    {
      "id": "1.1",
      "label": "Cryptography",
      "level": 2,
      "parent_id": "1",
      "children_ids": []
    }
  ],
  "root_id": "root",
  "title": "Quantum Computing Overview",
  "description": "A comprehensive mindmap of quantum computing"
}

​
How It Works

  1. Content Analysis: The agent analyzes the notebook’s research content
  2. Hierarchical Organization: Identifies main topics, subtopics, and key concepts
  3. Structure Generation: Creates a hierarchical mindmap with up to 3 levels
  4. Node Creation: Generates concise node labels and relationships
  5. Storage: Results are stored in the notebook for later retrieval

​
Best Practices

  • Complete Research First: Ensure the notebook has completed research before generating a mindmap
  • Async Processing: Mindmap generation is async - use task status polling to monitor progress
  • Error Handling: Implement retry logic for 500 errors
  • Notebook Validation: Always check that the notebook exists before submitting the task
  • Keep Labels Concise: Node labels are automatically kept to 1-3 words for clarity

​
Use Cases

  • Create visual overviews of complex research topics
  • Identify key themes and relationships in research
  • Generate study materials and presentations
  • Organize research findings hierarchically
  • Export to mindmap visualization tools

Build docs developers (and LLMs) love

Get started for freeTalk to us