Create and Manage Nodes Using the API

You can create and manage Nodes in your Workspace using the Coalesce API. This guide covers how to create new Nodes and update existing ones using API endpoints.

Before You Begin

Before you begin, you'll need:

• Your API token for authentication.
• Your Workspace ID.

Create a Workspace Node

Use this endpoint to create a new Node with Workspace default values.

Endpoint: POST /api/v1/workspaces/{workspaceID}/nodes

Getting the Node Type

You can find the nodeType in two ways:

1. Through the Coalesce App: Go to Build Settings > Node Types, then click View. The nodeTypeID shown is your nodeType.
2. Through the API: Use the List Workspace Nodes endpoint to see existing Nodes and their types.

Request Parameters

• nodeType (required): Can be a standard type or a custom nodeTypeID.
• predecessorNodeIDs (required): Array of Node IDs that should precede this Node. Use an empty array [] if there are no predecessors.

Example: Create a Stage Node

curl -X POST "https://app.coalescesoftware.io/api/v1/workspaces/<YOUR_WORKSPACE_ID>/nodes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeType": "Stage",
    "predecessorNodeIDs": []
  }'

Example: Create a Node with Predecessors

curl -X POST "https://app.coalescesoftware.io/api/v1/workspaces/<YOUR_WORKSPACE_ID>/nodes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeType": "Fact",
    "predecessorNodeIDs": ["node123", "node456"]
  }'

Set Node

Use this endpoint to replace all fields of an existing Node in a Workspace.

Endpoint: PUT /api/v1/workspaces/{workspaceID}/nodes/{nodeID}

warning

This endpoint replaces the entire Node object. You must provide all required fields, not just the ones you want to change.

Required Fields

The complete Node object must include:

• database: Snowflake database name
• description: Node description
• id: Node ID
• locationName: Storage Mapping location
• name: Node name
• nodeType: Node type
• schema: Database schema name
• metadata: Object containing columns, joins, and source mappings

Example: Update a Node

curl -X PUT "https://app.coalescesoftware.io/api/v1/workspaces/YOUR_WORKSPACE_ID/nodes/YOUR_NODE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "YOUR_NODE_ID",
    "name": "STG_CUSTOMERS",
    "description": "Stage table for customer data",
    "database": "ANALYTICS",
    "schema": "STAGING",
    "locationName": "STAGE",
    "nodeType": "Stage",
    "metadata": {
      "columns": [
        {
          "columnID": "col1",
          "name": "CUSTOMER_ID",
          "dataType": "NUMBER",
          "description": "Unique customer identifier",
          "nullable": false
        }
      ]
    }
  }'

Response Handling

Both endpoints return the complete Node object on success (HTTP 200).

---

What's Next?

• Set Node - Update an existing Node in a Workspace.
• Create Workspace Node - Create a new Workspace Node.

---