Nodes API

Nodes are the core data structure in DreamSolve, representing hierarchical entities such as Projects, Tasks, and other organizational elements.

Base URL

https://dreamsolve.ai/api/v1

Authentication

All endpoints require authentication via the x-api-key header. See the API Overview for details.

---

List Nodes

Retrieve all nodes for the authenticated user.

GET /api/v1/nodes

Query Parameters

Parameter	Type	Description
project_id	string	Filter tasks by project ID
parent_task_id	string	Filter subtasks by parent task ID

Response

[
  {
    "id": "123",
    "type": "Project",
    "name": "My Project",
    "description": "Project description",
    "status": "active",
    "parentId": null,
    "containerId": null,
    "organizationId": "org_456",
    "children": [],
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

---

Get Node by ID

Retrieve a specific node by its ID.

GET /api/v1/nodes/:id

Path Parameters

Parameter	Type	Description
id	string	The node ID

Response

{
  "id": "123",
  "type": "Task",
  "name": "My Task",
  "description": "Task description",
  "status": "pending",
  "parentId": "456",
  "containerId": "789",
  "organizationId": "org_456",
  "children": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

---

Create Node

Create a new node.

POST /api/v1/nodes

Request Body

{
  "type": "Task",
  "name": "New Task",
  "description": "Task description",
  "status": "pending",
  "parentId": "456"
}

Field	Type	Required	Description
type	string	Yes	Node type (Project, Task, etc.)
name	string	Yes	Node name
description	string	No	Node description
status	string	No	Node status
parentId	string	No	Parent node ID

Response

{
  "id": "789",
  "type": "Task",
  "name": "New Task",
  "description": "Task description",
  "status": "pending",
  "parentId": "456",
  "created_at": "2024-01-15T10:00:00Z"
}

Status Code: 201 Created

---

Update Node

Update an existing node.

PUT /api/v1/nodes/:id

Path Parameters

Parameter	Type	Description
id	string	The node ID

Request Body

{
  "name": "Updated Task Name",
  "status": "completed"
}

Response

{
  "id": "789",
  "type": "Task",
  "name": "Updated Task Name",
  "status": "completed",
  "updated_at": "2024-01-15T12:00:00Z"
}

---

Delete Node

Delete a node and all its children.

DELETE /api/v1/nodes/:id

Path Parameters

Parameter	Type	Description
id	string	The node ID

Response

{
  "message": "node deleted successfully"
}

---

Create Nodes from Plan

Create multiple nodes from a text plan using AI parsing.

POST /api/v1/nodes/create-from-plan

Request Body

{
  "nodeId": "123",
  "plan": "1. Research competitors\n2. Design mockups\n3. Implement features",
  "nodeType": "Task"
}

Field	Type	Required	Description
nodeId	string	Yes	Parent node ID
plan	string	Yes	Text plan to parse
nodeType	string	No	Type for created nodes (defaults to parent type)

Response

{
  "success": true,
  "createdNodes": [
    { "id": "124", "name": "Research competitors" },
    { "id": "125", "name": "Design mockups" },
    { "id": "126", "name": "Implement features" }
  ],
  "summary": "Created 3 tasks from plan"
}

Status Code: 201 Created

---

Node Files

Manage files associated with a node.

List Node Files

GET /api/v1/nodes/:nodeId/files

Response

{
  "files": [
    {
      "id": "file_123",
      "name": "document.pdf",
      "description": "Project documentation",
      "provider_type": "google_drive",
      "mime_type": "application/pdf",
      "scan_status": null,
      "is_readable": true
    }
  ]
}

Create File Association

POST /api/v1/nodes/:nodeId/files

Request Body

{
  "name": "document.pdf",
  "description": "Project documentation",
  "provider_type": "google_drive",
  "file_id": "gdrive_abc123",
  "mime_type": "application/pdf"
}

Field	Type	Required	Description
name	string	Yes	File name
description	string	No	File description
provider_type	string	Yes	One of: google_drive, public_url, internal
file_id	string	Conditional	Required for internal provider type
provider_data	object	No	Provider-specific metadata
file_url	string	No	URL for public_url type
mime_type	string	No	MIME type of the file
file_size	number	No	File size in bytes

Response

{
  "file": {
    "id": "file_124",
    "name": "document.pdf",
    "provider_type": "google_drive"
  }
}

Status Code: 201 Created

---

Node Types

DreamSolve supports various node types:

Type	Description
Project	Top-level container for work
Task	Actionable work item
Subtask	Child task under a Task
Agent	AI agent configuration
Team	Team or group container
Resource	Resource or reference material

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Node not found or access denied
500	Internal Server Error