Install Plugin from ZIP
Install a plugin from an uploaded ZIP file.
Endpoint
POST /api/plugins/install/zip
Content-Type: multipart/form-dataRequest Body (Form Data)
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | ZIP file containing the plugin |
Example Request
cURL
curl -X POST "http://localhost:7071/api/plugins/install/zip" \
-H "Content-Type: multipart/form-data" \
-F "file=@my-plugin.zip"Response
Success Response (200 OK)
{
"status": 200,
"message": "Plugin installed",
"data": {
"history": 12345,
"pluginId": "com.example.myplugin",
"pluginName": "My Custom Plugin",
"totalFiles": 15,
"successCount": 14,
"failedCount": 1
}
}Error Response (400 Bad Request)
{
"status": 400,
"error": "Plugin file (zip) is required"
}Plugin ZIP Structure
A plugin ZIP file should follow this structure:
my-plugin/
├── bshplugin.json # Plugin metadata (required)
├── BshEntities/ # Entity definitions
│ ├── __manifest__.json
│ └── MyEntity.json
├── BshSchemas/ # Schema definitions
│ ├── __manifest__.json
│ └── MyEntity.json
└── MyEntity/ # Data files for MyEntity
├── __manifest__.json
└── data.jsonPlugin Manifest (bshplugin.json)
{
"id": "com.example.myplugin",
"name": "My Custom Plugin",
"version": "1.0.0",
"description": "A custom plugin for BSH Engine",
"author": "Your Name"
}Error Handling
Common Errors
| Error | Cause | Solution |
|---|---|---|
Plugin file (zip) is required | No file uploaded or empty file | Ensure file is attached to request |
Conflict Issue! | Duplicate record with insertDuplicate: "Error" | Check for duplicate primary keys |
| Missing dependency | Required entity/schema not found | Install dependencies first |
Partial Failures
A plugin can partially succeed - some files may install while others fail. Check successCount and failedCount in the response, and use the history ID to retrieve detailed error logs.
See Also
- Plugin Structure - How to create and structure plugins
- Config File - Plugin configuration
- Manifest Files - Manifest file structure