Board Builder API

The Board Builder API lets external plugins push structured architecture data — nodes, edges, and insights — directly to your workboards. It's how the Claude Code plugin, VS Code extension, and custom integrations feed architecture into ContextDX.

Base URL: https://your-instance.com/api/board-builder

Authentication

All plugin endpoints require two headers:

X-BoardBuilder-Token: <binding-token>
X-BoardBuilder-Secret: <api-secret>

Get credentials from the UI: Sources → your Board Builder source → Binding → Copy Credentials.

Or programmatically:

GET /api/board-builder/workspaces/:workspaceId/bindings/:bindingId/credentials

This requires a user session (not plugin headers).

Endpoints

Push Elements

Push nodes and edges to a workboard. Supports merge (upsert) or replace (clear then insert) modes.

POST /api/board-builder/push

JSONCopy
{
  "boardSlug": "system-overview",
  "mode": "merge",
  "nodes": [
    {
      "slug": "api-gateway",
      "name": "API Gateway",
      "description": "Main entry point for all client requests",
      "primitiveType": "node",
      "archetypeName": "System",
      "parentNodeSlug": null,
      "tags": ["backend", "critical-path"]
    },
    {
      "slug": "user-service",
      "name": "User Service",
      "description": "Handles authentication and user profiles",
      "primitiveType": "node",
      "archetypeName": "System",
      "parentNodeSlug": null,
      "tags": ["backend"]
    }
  ],
  "edges": [
    {
      "sourceSlug": "api-gateway",
      "targetSlug": "user-service",
      "relation": "calls",
      "detailedDescription": "REST API calls for auth and user lookup"
    }
  ]
}

Node fields:

Edge fields:

Get Archetypes

Retrieve available element archetypes so your plugin uses valid archetypeName values.

GET /api/board-builder/archetypes

JSONCopy
{
  "archetypes": [
    {
      "name": "System",
      "description": "A software system or service",
      "visualPrimitiveType": "node",
      "canContain": ["Container", "Component"]
    }
  ]
}

Get Elements

Retrieve current nodes and edges from a board — useful for incremental updates.

GET /api/board-builder/elements?boardSlug=system-overview

List Boards

Discover all boards in the workspace (parent and child).

GET /api/board-builder/boards

JSONCopy
{
  "boards": [
    {
      "boardSlug": "system-overview",
      "boardName": "System Overview",
      "isChildBoard": false,
      "parentBoardSlug": null,
      "parentNodeSlug": null
    }
  ]
}

Create Child Boards

Create layer boards for drill-down navigation. Idempotent — existing boards are skipped.

POST /api/board-builder/boards

JSONCopy
{
  "boards": [
    {
      "boardSlug": "api-gateway-internals",
      "boardName": "API Gateway Internals",
      "parentBoardSlug": "system-overview",
      "parentNodeSlug": "api-gateway"
    }
  ]
}

Get Insight Skills

List available insight templates (lightweight — no instructions or references).

GET /api/board-builder/insight-skills

Get full template with instructions for execution:

GET /api/board-builder/insight-skills/:slug

Push Insights

Push analysis results from a plugin to a board.

POST /api/board-builder/insights

JSONCopy
{
  "boardSlug": "system-overview",
  "rootBoardSlug": "master",
  "insightSkillSlug": "security-analysis",
  "title": "Security Analysis - April 2026",
  "insights": {
    "elementInsights": [
      {
        "elementSlug": "api-gateway",
        "signal": "risk",
        "priority": "high",
        "title": "No rate limiting configured",
        "description": "API Gateway has no rate limiting, vulnerable to DDoS"
      }
    ],
    "affectedElements": [],
    "paths": [],
    "graphSuggestions": []
  },
  "content": "## Security Analysis\n\nFull markdown report..."
}

Error Codes

Integration Checklist

Verify your integration end-to-end:

• board_builder source created in the workspace Sources catalog
• Source is bound to a target board with the correct branch
• Credentials copied (X-BoardBuilder-Token + X-BoardBuilder-Secret)
• GET /archetypes returns valid archetype list
• POST /push with a test node returns success: true
• Node appears on the board in the UI
• GET /elements?boardSlug=... returns the pushed node

What's Next