Boards API

The Boards API is the HTTP interface external plugins use to push nodes, edges, and insights onto boards. The code plugin and custom integrations call it. The code plugin's /ground grounds documents through a different interface.

Note

This reference is for building an integration. 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

Every plugin endpoint requires two headers:

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

An app's governing binding gets its credential from the code plugin's /login, which writes it to .provenmap/credentials.json. For a reference Code Plugin binding, open the board hub's Bindings card, choose Binding actions → Copy credentials on its row, and then Generate new secret. Each click issues a fresh credential and shows it once. Existing credentials keep working until you revoke them.

To get them programmatically, call:

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

This request needs a user session, not the plugin headers. Its sibling, GET …/credentials, returns the same addressing fields with the secret masked, and never issues a credential.

Endpoints

Push elements

Pushes nodes and edges. Set mode to merge to upsert, or to 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"
    }
  ]
}

{
  "success": true,
  "boardSlug": "system-overview",
  "nodesCreated": 2,
  "nodesUpdated": 0,
  "edgesCreated": 1,
  "edgesUpdated": 0,
  "errors": []
}

{
  "statusCode": 400,
  "message": "Branch mismatch: expected 'main', got 'develop'"
}

Node fields:

Edge fields:

Get archetypes

Returns the valid archetypeName values.

GET /code-plugin/archetypes

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

Get elements

Returns the board's current nodes and edges.

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

List boards

Lists the 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

Creates layer boards for drill-down navigation. The call skips any board that already exists.

POST /code-plugin/boards

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

Get insight skills

Lists the available insight skills, without their instructions and references.

GET /code-plugin/insight-skills

One skill in full:

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

Push insights

Pushes the results of a plugin's analysis as insights.

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..."
}

{
  "success": true,
  "insightId": "ins_abc123",
  "boardSlug": "system-overview",
  "templateSlug": "security-analysis"
}

Error codes

Integration checklist

Before you rely on an integration, check each item:

• A Code Plugin source exists in the workspace Sources catalog
• The source is bound to a target board, on the correct branch
• You've copied the credentials (X-CodePlugin-Token + X-CodePlugin-Secret)
• GET /archetypes returns the archetype list
• POST /push with a test node returns success: true
• The 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 in a gitignored config file.

What's next