Boards API

The Boards API lets external plugins push structured architecture data — nodes, edges, and insights — directly to your workboards. It's how the ContextDX plugins (Cdx Code and Cdx Work), the VS Code extension, and custom integrations feed architecture into your boards.

Note

This is the API reference for building integrations. If you just want to use an existing plugin, see the ContextDX Plugins.

Base URL: https://<your-instance>/code-plugin (cloud default: https://api.contextdx.com/code-plugin)

Authentication

All plugin endpoints require two headers:

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

Get credentials from the UI: Sources → your Code Plugin source → Binding → Copy Credentials.

Or programmatically:

GET /code-plugin/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 /code-plugin/push

{
  "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 /code-plugin/archetypes

{
  "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 /code-plugin/elements?boardSlug=system-overview

List Boards

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

GET /code-plugin/boards

{
  "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 /code-plugin/boards

{
  "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 /code-plugin/insight-skills

Get full template with instructions for execution:

GET /code-plugin/insight-skills/:slug

Push Insights

Push analysis results from a plugin to a board.

POST /code-plugin/insights

{
  "boardSlug": "system-overview",
  "rootBoardSlug": "root",
  "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-CodePlugin-Token + X-CodePlugin-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

Warning

Never hardcode credentials. Store X-CodePlugin-Token and X-CodePlugin-Secret in environment variables or a config file that's gitignored.

What's Next