Skip to main content

​
Overview

The Plugin API enables you to extend Invenicum’s functionality through the plugin marketplace. Plugins are STAC-based extensions that can add custom UI components, data processing capabilities, and integrations to your workflow.

​
Plugin Model

{
  "id": "string",
  "name": "string",
  "author": "string",
  "version": "string",
  "description": "string",
  "slot": "dashboard_top",
  "ui": {},
  "authorAvatar": "string",
  "downloadCount": 0,
  "hasUpdate": false,
  "latestVersion": "string",
  "isMine": false,
  "isActive": true,
  "isPublic": false
}

​
Fields

  • id: Unique identifier for the plugin
  • name: Display name of the plugin
  • author: GitHub username of the plugin author
  • version: Current installed version (semver)
  • description: Plugin description
  • slot: UI slot where the plugin renders (e.g., dashboard_top, asset_detail)
  • ui: STAC UI definition object
  • authorAvatar: URL to author’s avatar image
  • downloadCount: Number of times the plugin has been downloaded
  • hasUpdate: Whether a newer version is available
  • latestVersion: Latest available version in the marketplace
  • isMine: Whether the current user authored this plugin
  • isActive: Whether the plugin is currently enabled
  • isPublic: Whether the plugin is published to the marketplace

​
Endpoints

​
Get Community Plugins

GET /plugins/community
Retrieves all available plugins from the marketplace, including both GitHub-hosted and database-stored plugins. Authentication: Required Response 
[
  {
    "id": "plugin-123",
    "name": "Asset Validator",
    "author": "octocat",
    "version": "1.2.0",
    "description": "Validates asset metadata before publishing",
    "slot": "asset_detail",
    "downloadCount": 1247,
    "isOfficial": false,
    "isPublic": true
  }
]

​
Get Installed Plugins

GET /plugins/installed
Returns all plugins installed by the authenticated user. Authentication: Required Response 
[
  {
    "id": "plugin-456",
    "name": "Custom Dashboard Widget",
    "version": "2.0.1",
    "isActive": true,
    "hasUpdate": false,
    "slot": "dashboard_top"
  }
]

​
Preview Plugin STAC

GET /plugins/preview-stac
Downloads and parses the STAC definition from a plugin URL before installation. Authentication: Required Query Parameters
  • url (required): GitHub raw content URL to the plugin’s STAC file
Example Request 
GET /plugins/preview-stac?url=https://raw.githubusercontent.com/user/repo/main/plugin.stac.json
Response 
{
  "name": "Sample Plugin",
  "version": "1.0.0",
  "description": "A sample plugin",
  "ui": {
    "type": "container",
    "children": [...]
  }
}

​
Install Plugin

POST /plugins/install
Installs a plugin from the marketplace to the user’s account. Authentication: Required Request Body 
{
  "id": "plugin-123",
  "name": "Asset Validator",
  "author": "octocat",
  "version": "1.2.0",
  "download_url": "https://raw.githubusercontent.com/octocat/plugin/main/plugin.stac.json",
  "isOfficial": false
}
Response 
{
  "success": true,
  "message": "Plugin installed successfully"
}

​
Uninstall Plugin

DELETE /plugins/uninstall/:pluginId
Removes a plugin from the user’s installed plugins. Authentication: Required Path Parameters
  • pluginId: The ID of the plugin to uninstall
Example Request 
DELETE /plugins/uninstall/plugin-456
Response 
{
  "success": true
}

​
Toggle Plugin Status

PUT /plugins/user/toggle
Enables or disables an installed plugin without uninstalling it. Authentication: Required Request Body 
{
  "pluginId": "plugin-456",
  "isActive": false
}
Response 
{
  "success": true,
  "isActive": false
}

​
Create Plugin

POST /plugins
Creates a new plugin. The author is automatically assigned from the authenticated user’s token. Authentication: Required Request Body 
{
  "name": "My New Plugin",
  "version": "1.0.0",
  "description": "A custom plugin for data processing",
  "slot": "dashboard_top",
  "ui": {
    "type": "container",
    "children": []
  },
  "isPublic": true
}
Response 
{
  "id": "plugin-789",
  "name": "My New Plugin",
  "author": "your-github-username",
  "version": "1.0.0",
  "createdAt": "2026-03-07T10:30:00Z"
}

​
Update Plugin

PUT /plugins/:id
Updates an existing plugin. Depending on permissions, this may create a pull request or commit directly. Authentication: Required Path Parameters
  • id: The plugin ID to update
Request Body 
{
  "name": "My Updated Plugin",
  "version": "1.1.0",
  "description": "Updated description",
  "ui": {...}
}
Response 
{
  "id": "plugin-789",
  "version": "1.1.0",
  "updatedAt": "2026-03-07T12:00:00Z",
  "pullRequestUrl": "https://github.com/user/repo/pull/42"
}

​
Delete Plugin

DELETE /plugins/:pluginId
Deletes a plugin from the global database and optionally from GitHub. Authentication: Required Path Parameters
  • pluginId: The plugin ID to delete
Query Parameters
  • deleteFromGitHub (boolean): Whether to also delete the plugin repository from GitHub
Example Request 
DELETE /plugins/plugin-789?deleteFromGitHub=true
Response 
{
  "success": true,
  "message": "Plugin deleted from database and GitHub"
}

​
SDK Methods

The Plugin SDK is built on top of the STAC framework and provides runtime parsing and execution.

​
Initialize SDK

await pluginService.initSdk(userName: 'github-username');
Initializes the STAC SDK with Invenicum-specific action parsers. This should be called once at application startup. Parameters
  • userName (optional): GitHub username for personalization

​
Download Plugin STAC

final stacData = await pluginService.downloadPluginStac(
  'https://raw.githubusercontent.com/user/repo/main/plugin.stac.json'
);
Fetches and parses a STAC definition from a remote URL.

​
Install Plugin

await pluginService.installPlugin({
  'id': 'plugin-123',
  'name': 'Asset Validator',
  'author': 'octocat',
  'version': '1.2.0',
  'download_url': 'https://...',
  'isOfficial': false
});

​
STAC Plugin Format

Plugins use the STAC (Structured Template and Action Components) format for UI definitions. Example Plugin Structure 
{
  "name": "Data Quality Checker",
  "version": "1.0.0",
  "description": "Validates asset metadata quality",
  "slot": "asset_detail",
  "ui": {
    "type": "container",
    "layout": "vertical",
    "children": [
      {
        "type": "text",
        "content": "Quality Score: {{asset.qualityScore}}"
      },
      {
        "type": "button",
        "label": "Run Check",
        "action": {
          "method": "runQualityCheck",
          "params": {
            "assetId": "{{asset.id}}"
          }
        }
      }
    ]
  }
}

​
Authentication

All plugin endpoints require a valid Bearer token in the Authorization header: 
Authorization: Bearer <your-token>

​
Error Responses

{
  "success": false,
  "message": "Plugin not found",
  "error": "PLUGIN_NOT_FOUND"
}

​
Common Error Codes

  • PLUGIN_NOT_FOUND: The requested plugin does not exist
  • ALREADY_INSTALLED: Plugin is already installed
  • INVALID_STAC: The STAC definition is malformed
  • PERMISSION_DENIED: User does not have permission to modify this plugin
  • VERSION_CONFLICT: The plugin version conflicts with an existing installation

Build docs developers (and LLMs) love

Get started for freeTalk to us