Boards API

The Boards API lets external plugins push nodes, edges, and insights onto boards. The code plugin, VS Code extension, and custom integrations use it. The connect plugin uses a different interface for document grounding.

Note

This is the API reference for building integrations. To use an existing plugin, see the plugins guide.

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

Authentication

All plugin endpoints require two headers:

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

Get credentials in the UI: the board hub's Bindings card → the binding's credentials dialog → Generate new secret. Each call issues a fresh credential shown once; existing credentials keep working until revoked.

Or programmatically:

POST /code-plugin/workspaces/:workspaceId/bindings/:bindingId/credentials/generate

This request requires a user session, not plugin headers. The GET …/credentials sibling returns the same addressing fields with the secret masked — it never issues.

Endpoints

Push elements

Push nodes and edges. Use merge to upsert, or replace to clear the board first.

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 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 for incremental updates.

GET /code-plugin/elements?boardSlug=system-overview

List boards

Discover parent and child boards in the workspace.

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. 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. This lightweight response omits instructions and references.

GET /code-plugin/insight-skills

Get the full template:

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

Push insights

Push plugin analysis results.

POST /code-plugin/insights

{
  "boardSlug": "system-overview",
  "rootBoardSlug": "root",
  "insightSkillSlug": "security-analysis",
  "title": "Security Analysis",
  "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 the integration:

• Code Plugin 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 is gitignored.

What's next