Builder API

API endpoints for the Visual Workflow Builder

Overview

The Builder API provides endpoints for creating, managing, and deploying visual workflows. All endpoints (except health and static assets) require JWT authentication.

Base URL

# Development
http://localhost:8001

# Test Infrastructure
http://localhost:9001

# Production
https://builder.yourdomain.com

Authentication

All API endpoints (except /health and static assets) require JWT authentication:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

---

Health Endpoints

GET /api/builder/health

Health check endpoint (no authentication required).

Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Status Codes:

200 · Success

Service is healthy

---

GET /

Serves the React SPA frontend (no authentication required).

Response: HTML content with React application.

---

Workflow Endpoints

POST /api/builder/workflows

Create a new workflow.

name · string · required

Display name for the workflow

description · string

Optional description

nodes · array · required

List of workflow nodes

edges · array · required

List of connections between nodes

Request:

curl -X POST http://localhost:9001/api/builder/workflows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Multi-agent support workflow",
    "nodes": [
      {"id": "start", "type": "start", "position": {"x": 100, "y": 100}},
      {"id": "agent", "type": "agent", "position": {"x": 300, "y": 100}, "data": {"name": "Support", "prompt": "You are helpful"}},
      {"id": "end", "type": "end", "position": {"x": 500, "y": 100}}
    ],
    "edges": [
      {"id": "e1", "source": "start", "target": "agent"},
      {"id": "e2", "source": "agent", "target": "end"}
    ]
  }'

Response:

{
  "id": "wf_abc123def456",
  "name": "Customer Support Agent",
  "description": "Multi-agent support workflow",
  "version": 1,
  "created_at": "2025-12-06T10:00:00Z",
  "updated_at": "2025-12-06T10:00:00Z",
  "created_by": "alice",
  "nodes": [...],
  "edges": [...]
}

Status Codes:

201 · Created

Workflow created successfully

400 · Bad Request

Invalid workflow definition

401 · Unauthorized

Invalid or missing authentication token

---

GET /api/builder/workflows

List all workflows for the authenticated user.

limit · integer · default: "20"

Maximum number of workflows to return

offset · integer · default: "0"

Number of workflows to skip for pagination

tag · string

Filter by tag

Request:

curl "http://localhost:9001/api/builder/workflows?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "id": "wf_abc123def456",
    "name": "Customer Support Agent",
    "description": "Multi-agent support workflow",
    "version": 3,
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-06T10:00:00Z",
    "node_count": 5,
    "tags": ["support", "production"]
  },
  {
    "id": "wf_xyz789",
    "name": "Data Pipeline",
    "description": "ETL workflow",
    "version": 1,
    "created_at": "2025-12-05T09:00:00Z",
    "updated_at": "2025-12-05T09:00:00Z",
    "node_count": 3,
    "tags": ["data"]
  }
]

---

GET /api/builder/workflows/

Get details for a specific workflow.

Path Parameters:

workflow_id · string · required

The workflow ID

Request:

curl http://localhost:9001/api/builder/workflows/wf_abc123def456 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "wf_abc123def456",
  "name": "Customer Support Agent",
  "description": "Multi-agent support workflow",
  "version": 3,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-06T10:00:00Z",
  "created_by": "alice",
  "nodes": [
    {
      "id": "start",
      "type": "start",
      "position": {"x": 100, "y": 100}
    },
    {
      "id": "agent",
      "type": "agent",
      "position": {"x": 300, "y": 100},
      "data": {
        "name": "Support",
        "prompt": "You are a helpful customer support agent..."
      }
    },
    {
      "id": "end",
      "type": "end",
      "position": {"x": 500, "y": 100}
    }
  ],
  "edges": [
    {"id": "e1", "source": "start", "target": "agent"},
    {"id": "e2", "source": "agent", "target": "end"}
  ],
  "metadata": {
    "tags": ["support", "production"],
    "deployed": true,
    "deployed_at": "2025-12-05T14:00:00Z"
  }
}

Status Codes:

200 · Success

Workflow retrieved successfully

404 · Not Found

Workflow does not exist or user lacks access

---

PUT /api/builder/workflows/

Update an existing workflow.

Request:

curl -X PUT http://localhost:9001/api/builder/workflows/wf_abc123def456 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent v2",
    "nodes": [...],
    "edges": [...]
  }'

Response:

{
  "id": "wf_abc123def456",
  "name": "Customer Support Agent v2",
  "version": 4,
  "updated_at": "2025-12-06T11:00:00Z"
}

Status Codes:

200 · Success

Workflow updated successfully

404 · Not Found

Workflow does not exist

---

DELETE /api/builder/workflows/

Delete a workflow.

Request:

curl -X DELETE http://localhost:9001/api/builder/workflows/wf_abc123def456 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "message": "Workflow deleted successfully"
}

Status Codes:

204 · No Content

Workflow deleted successfully

404 · Not Found

Workflow does not exist

---

Validation Endpoints

POST /api/builder/validate

Validate a workflow definition without saving.

nodes · array · required

List of workflow nodes

edges · array · required

List of connections between nodes

Request:

curl -X POST http://localhost:9001/api/builder/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {"id": "start", "type": "start"},
      {"id": "agent", "type": "agent", "data": {"name": "Test"}},
      {"id": "end", "type": "end"}
    ],
    "edges": [
      {"source": "start", "target": "agent"},
      {"source": "agent", "target": "end"}
    ]
  }'

Response (Valid):

{
  "valid": true,
  "errors": [],
  "warnings": []
}

Response (Invalid):

{
  "valid": false,
  "errors": [
    {
      "type": "MISSING_END_NODE",
      "message": "Workflow must have at least one End node",
      "severity": "error"
    },
    {
      "type": "ORPHAN_NODE",
      "message": "Node 'agent_3' is not connected to the workflow",
      "node_id": "agent_3",
      "severity": "error"
    }
  ],
  "warnings": [
    {
      "type": "EMPTY_PROMPT",
      "message": "Agent 'agent_2' has no system prompt configured",
      "node_id": "agent_2",
      "severity": "warning"
    }
  ]
}

Validation Rules:

Rule	Severity	Description
MISSING_START_NODE	error	No Start node found
MULTIPLE_START_NODES	error	More than one Start node
MISSING_END_NODE	error	No End node found
ORPHAN_NODE	error	Node not connected to workflow
UNREACHABLE_END	error	End node not reachable from Start
CYCLE_DETECTED	error	Circular reference without exit
DUPLICATE_NODE_ID	error	Same ID used for multiple nodes
EMPTY_PROMPT	warning	Agent has no system prompt
UNUSED_EDGE	warning	Edge connects invalid nodes

---

Code Generation Endpoints

POST /api/builder/generate

Generate LangGraph Python code from a workflow.

name · string

Name for the generated module

nodes · array · required

List of workflow nodes

edges · array · required

List of connections between nodes

options · object

Code generation options

Request:

curl -X POST http://localhost:9001/api/builder/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CustomerSupport",
    "nodes": [
      {"id": "start", "type": "start"},
      {"id": "agent", "type": "agent", "data": {"name": "Support", "prompt": "You are helpful"}},
      {"id": "end", "type": "end"}
    ],
    "edges": [
      {"source": "start", "target": "agent"},
      {"source": "agent", "target": "end"}
    ],
    "options": {
      "include_types": true,
      "include_docstrings": true
    }
  }'

Response:

{
  "code": "\"\"\"\\nGenerated workflow: CustomerSupport\\n...\\n\"\"\"\\n\\nfrom typing import TypedDict\\nfrom langgraph.graph import StateGraph, START, END\\n\\n\\nclass AgentState(TypedDict):\\n    messages: list\\n\\n\\ndef support(state: AgentState) -> AgentState:\\n    \\\"\\\"\\\"Support agent node.\\\"\\\"\\\"\\n    return state\\n\\n\\nworkflow = StateGraph(AgentState)\\nworkflow.add_node(\\\"support\\\", support)\\nworkflow.add_edge(START, \\\"support\\\")\\nworkflow.add_edge(\\\"support\\\", END)\\n\\napp = workflow.compile()\\n",
  "filename": "customer_support.py",
  "language": "python",
  "dependencies": [
    "langgraph>=1.0.0",
    "langchain-core>=0.3.0"
  ]
}

Generation Options:

Option	Type	Default	Description
include_types	boolean	true	Generate TypedDict state classes
include_docstrings	boolean	true	Add docstrings to functions
include_mcp_tools	boolean	true	Generate MCP tool imports
checkpoint_config	boolean	false	Include checkpointing setup
async_mode	boolean	false	Generate async functions

---

MCP Integration Endpoints

GET /api/builder/tools

List available MCP tools for workflow integration.

Request:

curl http://localhost:9001/api/builder/tools \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "name": "web_search",
    "description": "Search the web for information",
    "parameters": {
      "query": {"type": "string", "required": true},
      "max_results": {"type": "integer", "default": 10}
    }
  },
  {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "parameters": {
      "expression": {"type": "string", "required": true}
    }
  }
]

---

GET /api/builder/resources

List available MCP resources.

Request:

curl http://localhost:9001/api/builder/resources \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "uri": "file:///data/knowledge_base.txt",
    "name": "Knowledge Base",
    "mimeType": "text/plain"
  },
  {
    "uri": "db://customers",
    "name": "Customer Database",
    "mimeType": "application/json"
  }
]

---

Version History Endpoints

GET /api/builder/workflows//versions

List version history for a workflow.

Request:

curl http://localhost:9001/api/builder/workflows/wf_abc123/versions \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "version": 3,
    "created_at": "2025-12-06T10:00:00Z",
    "created_by": "alice",
    "message": "Added billing agent"
  },
  {
    "version": 2,
    "created_at": "2025-12-05T14:00:00Z",
    "created_by": "alice",
    "message": "Updated prompts"
  },
  {
    "version": 1,
    "created_at": "2025-12-01T10:00:00Z",
    "created_by": "alice",
    "message": "Initial version"
  }
]

---

GET /api/builder/workflows//versions/

Get a specific version of a workflow.

Request:

curl http://localhost:9001/api/builder/workflows/wf_abc123/versions/2 \
  -H "Authorization: Bearer $TOKEN"

---

POST /api/builder/workflows//rollback

Rollback to a previous version.

version · integer · required

Version number to rollback to

Request:

curl -X POST http://localhost:9001/api/builder/workflows/wf_abc123/rollback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 2}'

Response:

{
  "id": "wf_abc123",
  "version": 4,
  "message": "Rolled back to version 2"
}

---

Error Responses

All endpoints may return the following errors:

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid workflow definition",
  "details": [
    {"field": "nodes", "error": "must not be empty"}
  ],
  "code": "INVALID_WORKFLOW"
}

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired token",
  "code": "AUTH_INVALID_TOKEN"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "Access denied to this workflow",
  "code": "AUTH_ACCESS_DENIED"
}

404 Not Found

{
  "error": "not_found",
  "message": "Workflow not found",
  "code": "WORKFLOW_NOT_FOUND"
}

422 Unprocessable Entity

{
  "error": "validation_error",
  "message": "Workflow validation failed",
  "details": {
    "valid": false,
    "errors": [...]
  },
  "code": "VALIDATION_FAILED"
}

---

Node Type Reference

Start Node

{
  "id": "start",
  "type": "start",
  "position": {"x": 100, "y": 100}
}

Agent Node

{
  "id": "agent_1",
  "type": "agent",
  "position": {"x": 300, "y": 100},
  "data": {
    "name": "AssistantAgent",
    "prompt": "You are a helpful assistant...",
    "model": "gemini-2.5-flash",
    "tools": ["web_search", "calculator"],
    "temperature": 0.7
  }
}

Router Node

{
  "id": "router_1",
  "type": "router",
  "position": {"x": 500, "y": 100},
  "data": {
    "conditions": [
      {"label": "billing", "pattern": "billing|payment|invoice"},
      {"label": "technical", "pattern": "error|bug|issue"},
      {"label": "default", "pattern": ".*"}
    ]
  }
}

Tool Node

{
  "id": "tool_1",
  "type": "tool",
  "position": {"x": 700, "y": 100},
  "data": {
    "tool_name": "web_search",
    "arguments": {
      "query": "{{state.query}}",
      "max_results": 5
    }
  }
}

Human Node

{
  "id": "human_1",
  "type": "human",
  "position": {"x": 900, "y": 100},
  "data": {
    "prompt": "Please review this response:",
    "timeout": 3600,
    "options": ["approve", "reject", "revise"]
  }
}

End Node

{
  "id": "end",
  "type": "end",
  "position": {"x": 1100, "y": 100},
  "data": {
    "output": "state.messages[-1]"
  }
}

---

SDK Examples

Python

import httpx

class BuilderClient:
    def __init__(self, base_url: str, token: str):
        self.client = httpx.Client(
            base_url=base_url,
            headers={"Authorization": f"Bearer {token}"}
        )

    def create_workflow(self, name: str, nodes: list, edges: list) -> dict:
        response = self.client.post(
            "/api/builder/workflows",
            json={"name": name, "nodes": nodes, "edges": edges}
        )
        response.raise_for_status()
        return response.json()

    def validate(self, nodes: list, edges: list) -> dict:
        response = self.client.post(
            "/api/builder/validate",
            json={"nodes": nodes, "edges": edges}
        )
        return response.json()

    def generate_code(self, name: str, nodes: list, edges: list) -> str:
        response = self.client.post(
            "/api/builder/generate",
            json={"name": name, "nodes": nodes, "edges": edges}
        )
        return response.json()["code"]

# Usage
client = BuilderClient("http://localhost:9001", token)

nodes = [
    {"id": "start", "type": "start"},
    {"id": "agent", "type": "agent", "data": {"name": "Helper", "prompt": "Be helpful"}},
    {"id": "end", "type": "end"}
]
edges = [
    {"source": "start", "target": "agent"},
    {"source": "agent", "target": "end"}
]

# Validate first
result = client.validate(nodes, edges)
if result["valid"]:
    # Create workflow
    workflow = client.create_workflow("My Workflow", nodes, edges)
    print(f"Created: {workflow['id']}")

    # Generate code
    code = client.generate_code("my_workflow", nodes, edges)
    print(code)

JavaScript/TypeScript

class BuilderClient {
  private baseUrl: string;
  private token: string;

  constructor(baseUrl: string, token: string) {
    this.baseUrl = baseUrl;
    this.token = token;
  }

  private async request(path: string, options: RequestInit = {}): Promise<Response> {
    return fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
  }

  async createWorkflow(name: string, nodes: Node[], edges: Edge[]): Promise<Workflow> {
    const response = await this.request('/api/builder/workflows', {
      method: 'POST',
      body: JSON.stringify({ name, nodes, edges })
    });
    return response.json();
  }

  async validate(nodes: Node[], edges: Edge[]): Promise<ValidationResult> {
    const response = await this.request('/api/builder/validate', {
      method: 'POST',
      body: JSON.stringify({ nodes, edges })
    });
    return response.json();
  }

  async generateCode(name: string, nodes: Node[], edges: Edge[]): Promise<string> {
    const response = await this.request('/api/builder/generate', {
      method: 'POST',
      body: JSON.stringify({ name, nodes, edges })
    });
    const data = await response.json();
    return data.code;
  }
}

// Usage
const client = new BuilderClient('http://localhost:9001', token);

const nodes = [
  { id: 'start', type: 'start' },
  { id: 'agent', type: 'agent', data: { name: 'Helper', prompt: 'Be helpful' }},
  { id: 'end', type: 'end' }
];

const edges = [
  { source: 'start', target: 'agent' },
  { source: 'agent', target: 'end' }
];

const result = await client.validate(nodes, edges);
if (result.valid) {
  const code = await client.generateCode('my_workflow', nodes, edges);
  console.log(code);
}

---

Related Documentation

Builder Guide

Learn how to use the builder

Authentication API

Authentication endpoints

LangGraph Concepts

Understand LangGraph fundamentals

MCP Tools

Configure MCP tools

---

Full API access! Use these endpoints to programmatically manage workflows and integrate with your development pipeline.