{
    "openapi": "3.0.0",
    "info": {
        "version": "1.1.0",
        "title": "KIP Plugin API",
        "description": "Endpoints\n- List remote displays and control remote dashboard of a given KIP instance.\n- Configure data series for widget framework historical data series and data chart widgets.",
        "termsOfService": "http://signalk.org/terms/",
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "externalDocs": {
        "url": "http://signalk.org/specification/",
        "description": "Signal K specification."
    },
    "servers": [
        {
            "url": "/"
        }
    ],
    "tags": [
        {
            "name": "Displays",
            "description": "KIP remote display discovery and control."
        },
        {
            "name": "Series",
            "description": "KIP widget history series configuration."
        }
    ],
    "components": {
        "schemas": {
            "DisplayInfo": {
                "type": "object",
                "properties": {
                    "displayId": {
                        "type": "string",
                        "description": "KIP instance UUID"
                    },
                    "displayName": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "required": [
                    "displayId"
                ]
            },
            "ScreenItem": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "icon": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "name",
                    "icon"
                ]
            },
            "ScreenListOrNull": {
                "type": "array",
                "nullable": true,
                "items": {
                    "$ref": "#/components/schemas/ScreenItem"
                }
            },
            "SuccessResponse": {
                "type": "object",
                "properties": {
                    "state": {
                        "type": "string",
                        "enum": [
                            "SUCCESS"
                        ]
                    },
                    "statusCode": {
                        "type": "integer",
                        "enum": [
                            200
                        ]
                    }
                },
                "required": [
                    "state",
                    "statusCode"
                ]
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "state": {
                        "type": "string",
                        "enum": [
                            "FAILED"
                        ]
                    },
                    "statusCode": {
                        "type": "integer"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "required": [
                    "state",
                    "statusCode",
                    "message"
                ]
            },
            "ActiveScreenSetRequest": {
                "type": "object",
                "properties": {
                    "screenIdx": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Index of active screen or null to clear"
                    }
                }
            },
            "AnyObjectOrNull": {
                "type": "object",
                "nullable": true,
                "additionalProperties": true
            },
            "SeriesDefinitionBase": {
                "type": "object",
                "properties": {
                    "seriesId": {
                        "type": "string"
                    },
                    "datasetUuid": {
                        "type": "string"
                    },
                    "ownerWidgetUuid": {
                        "type": "string"
                    },
                    "ownerWidgetSelector": {
                        "type": "string",
                        "nullable": true
                    },
                    "path": {
                        "type": "string"
                    },
                    "context": {
                        "type": "string",
                        "nullable": true
                    },
                    "source": {
                        "type": "string",
                        "nullable": true
                    },
                    "timeScale": {
                        "type": "string",
                        "nullable": true
                    },
                    "period": {
                        "type": "integer",
                        "nullable": true
                    },
                    "retentionDurationMs": {
                        "type": "integer",
                        "nullable": true
                    },
                    "sampleTime": {
                        "type": "integer",
                        "nullable": true
                    },
                    "enabled": {
                        "type": "boolean",
                        "default": true
                    },
                    "methods": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "min",
                                "max",
                                "avg",
                                "sma",
                                "ema"
                            ]
                        }
                    },
                    "reconcileTs": {
                        "type": "integer",
                        "nullable": true
                    }
                },
                "required": [
                    "seriesId",
                    "datasetUuid",
                    "ownerWidgetUuid",
                    "ownerWidgetSelector",
                    "path",
                    "enabled"
                ]
            },
            "ConcreteSeriesDefinition": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/SeriesDefinitionBase"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "expansionMode": {
                                "nullable": true,
                                "description": "Null for concrete series definitions."
                            },
                            "familyKey": {
                                "type": "string",
                                "nullable": true,
                                "description": "Concrete series do not use family key and should leave this null."
                            },
                            "allowedIds": {
                                "type": "array",
                                "nullable": true,
                                "items": {
                                    "type": "string"
                                },
                                "description": "Concrete series do not use template filters and should leave this null."
                            },
                            "trackedDevices": {
                                "type": "array",
                                "nullable": true,
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        },
                                        "source": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "id",
                                        "source"
                                    ]
                                },
                                "description": "Concrete series do not use tracked device template filters and should leave this null."
                            }
                        }
                    }
                ]
            },
            "TemplateSeriesDefinition": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/SeriesDefinitionBase"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "ownerWidgetSelector": {
                                "type": "string",
                                "enum": [
                                    "widget-bms",
                                    "widget-solar-charger",
                                    "widget-charger",
                                    "widget-inverter",
                                    "widget-alternator",
                                    "widget-ac"
                                ]
                            },
                            "expansionMode": {
                                "type": "string",
                                "enum": [
                                    "bms-battery-tree",
                                    "solar-tree",
                                    "charger-tree",
                                    "inverter-tree",
                                    "alternator-tree",
                                    "ac-tree"
                                ]
                            },
                            "familyKey": {
                                "type": "string",
                                "enum": [
                                    "batteries",
                                    "solar",
                                    "chargers",
                                    "inverters",
                                    "alternators",
                                    "ac"
                                ]
                            },
                            "allowedIds": {
                                "type": "array",
                                "nullable": true,
                                "items": {
                                    "type": "string"
                                },
                                "description": "Template device IDs to include. Null or empty includes all discovered devices."
                            },
                            "trackedDevices": {
                                "type": "array",
                                "nullable": true,
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        },
                                        "source": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "id",
                                        "source"
                                    ]
                                },
                                "description": "Explicit tracked device id/source pairs to expand. When provided, template expansion skips self-tree discovery and emits one concrete series per pair and metric."
                            }
                        },
                        "required": [
                            "ownerWidgetSelector",
                            "expansionMode",
                            "familyKey"
                        ]
                    }
                ]
            },
            "SeriesDefinition": {
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/ConcreteSeriesDefinition"
                    },
                    {
                        "$ref": "#/components/schemas/TemplateSeriesDefinition"
                    }
                ]
            },
            "SeriesReconcileResult": {
                "type": "object",
                "properties": {
                    "created": {
                        "type": "integer"
                    },
                    "updated": {
                        "type": "integer"
                    },
                    "deleted": {
                        "type": "integer"
                    },
                    "total": {
                        "type": "integer"
                    }
                },
                "required": [
                    "created",
                    "updated",
                    "deleted",
                    "total"
                ]
            }
        },
        "parameters": {
            "DisplayIdParam": {
                "in": "path",
                "required": true,
                "name": "displayId",
                "description": "KIP instance UUID",
                "schema": {
                    "type": "string"
                }
            },
            "SeriesIdParam": {
                "in": "path",
                "required": true,
                "name": "seriesId",
                "description": "Series identifier (dataset UUID)",
                "schema": {
                    "type": "string"
                }
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT"
            },
            "cookieAuth": {
                "type": "apiKey",
                "in": "cookie",
                "name": "JAUTHENTICATION"
            }
        }
    },
    "security": [
        {
            "cookieAuth": []
        },
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/plugins/kip/displays": {
            "get": {
                "tags": [
                    "Displays"
                ],
                "summary": "List available KIP displays",
                "responses": {
                    "200": {
                        "description": "List of KIP instances discovered under self.displays",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/DisplayInfo"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plugins/kip/displays/{displayId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/DisplayIdParam"
                }
            ],
            "get": {
                "tags": [
                    "Displays"
                ],
                "summary": "List screens for a display (self.displays.{displayId}.value.screens)",
                "responses": {
                    "200": {
                        "description": "Array of screen entries (or null)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ScreenListOrNull"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Displays"
                ],
                "summary": "Set display entry under self.displays.{displayId}",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AnyObjectOrNull"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plugins/kip/displays/{displayId}/screenIndex": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/DisplayIdParam"
                }
            ],
            "get": {
                "tags": [
                    "Displays"
                ],
                "summary": "Get current screen index for display (self.displays.{displayId}.screenIndex)",
                "responses": {
                    "200": {
                        "description": "Current screen index or null",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "integer",
                                    "nullable": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Displays"
                ],
                "summary": "Set current screen index for display (self.displays.{displayId}.screenIndex)",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ActiveScreenSetRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plugins/kip/displays/{displayId}/activeScreen": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/DisplayIdParam"
                }
            ],
            "get": {
                "tags": [
                    "Displays"
                ],
                "summary": "Get requested screen change index (self.displays.{displayId}.activeScreen)",
                "responses": {
                    "200": {
                        "description": "Requested screen index or null",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "integer",
                                    "nullable": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Displays"
                ],
                "summary": "Request a screen change (sets self.displays.{displayId}.activeScreen)",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ActiveScreenSetRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SuccessResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plugins/kip/series": {
            "get": {
                "tags": [
                    "Series"
                ],
                "summary": "List all configured history series",
                "responses": {
                    "200": {
                        "description": "Current series definitions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/SeriesDefinition"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plugins/kip/series/{seriesId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/SeriesIdParam"
                }
            ],
            "put": {
                "tags": [
                    "Series"
                ],
                "summary": "Create or update a series definition",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SeriesDefinition"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Series upserted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SeriesDefinition"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Series"
                ],
                "summary": "Delete a series definition",
                "responses": {
                    "200": {
                        "description": "Series removed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SuccessResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Series not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/plugins/kip/series/reconcile": {
            "post": {
                "tags": [
                    "Series"
                ],
                "summary": "Reconcile full desired series set",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/SeriesDefinition"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Reconcile summary",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SeriesReconcileResult"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}