14.2. API Catalog Reference

This section is not intended to be read as a narrative description of system behavior, but to serve as a structured reference for developers implementing or integrating with the GEISA API.

It serves as a comprehensive catalog of all defined API calls, including:

• MQTT topic structures

• Required and optional parameters

• Message payload formats

• Expected responses

• Error conditions, where applicable

GEISA APIs are implemented using MQTT topic hierarchies. Each API call is defined by:

• The MQTT topic structure

• The direction of message flow

• The associated request and response payload definitions

• References to relevant sections of the GEISA specification that define relevant behavior and constraints

Request/response APIs that include GeisaStatus use the common response status and error model documented in Common Response Status.

Note

In the event of a conflict between this API catalog and the specific description in each API reference section, the API reference section SHALL prevail.

14.2.1. API Topic and Permission Catalog

Note

In the topic definitions below, <userid> refers to the platform-local identifier of the requesting GEISA application instance (see Glossary) and SName, AppID-A, and AppID-B refers to the Service Name and Application IDs for App-to-App Communication.

Table 14.1 API Topic and Permission Catalog

Category	Topic	Role	Action	Direction	Message Name	Message Type
Discovery	geisa/api/platform/discovery/req/<userid>	Application	Publish	App → Platform	GeisaPlatformDiscovery_Req	Request
	geisa/api/platform/discovery/rsp/<userid>	Application	Subscribe	Platform → App	GeisaPlatformDiscovery_Rsp	Response
	geisa/api/app/manifest/req/<userid>	Application	Publish	App → Platform	GeisaApplicationDeploymentManifest_Req	Request
	geisa/api/app/manifest/rsp/<userid>	Application	Subscribe	Platform → App	GeisaApplicationDeploymentManifest_Rsp	Response
	geisa/api/platform/discovery/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaPlatformDiscovery_Req	Request
	geisa/api/platform/discovery/rsp/<userid>	Platform	Publish	Platform → App	GeisaPlatformDiscovery_Rsp	Response
	geisa/api/app/manifest/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaApplicationDeploymentManifest_Req	Request
	geisa/api/app/manifest/rsp/<userid>	Platform	Publish	Platform → App	GeisaApplicationDeploymentManifest_Rsp	Response
Platform Status	geisa/api/platform/status	Application	Subscribe	Platform → App	GeisaPlatformToAppStatus	Broadcast
	geisa/api/platform/app/status/<userid>	Application	Subscribe	Platform → App	GeisaPlatformToAppStatus	Directed
	geisa/api/app/platform/status/<userid>	Application	Publish	App → Platform	GeisaAppToPlatformStatus	Directed
	geisa/api/platform/status	Platform	Publish	Platform → App	GeisaPlatformToAppStatus	Broadcast
	geisa/api/platform/app/status/<userid>	Platform	Publish	Platform → App	GeisaPlatformToAppStatus	Directed
	geisa/api/app/platform/status/#	Platform	Wildcard Subscribe	App → Platform	GeisaAppToPlatformStatus	Directed
Networking	geisa/api/message/upstream/req/<userid>	Application	Publish	App → Platform	GeisaAppMessage_Req	Request
	geisa/api/message/upstream/rsp/<userid>	Application	Subscribe	Platform → App	GeisaAppMessage_Rsp	Response
	geisa/api/message/downstream/req/<userid>	Application	Subscribe	Platform → App	GeisaAppMessage_Req	Request
	geisa/api/message/downstream/rsp/<userid>	Application	Publish	App → Platform	GeisaAppMessage_Rsp	Response
	geisa/api/message/upstream/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaAppMessage_Req	Request
	geisa/api/message/upstream/rsp/<userid>	Platform	Publish	Platform → App	GeisaAppMessage_Rsp	Response
	geisa/api/message/downstream/req/<userid>	Platform	Publish	Platform → App	GeisaAppMessage_Req	Request
	geisa/api/message/downstream/rsp/#	Platform	Wildcard Subscribe	App → Platform	GeisaAppMessage_Rsp	Response
Instantaneous Data	geisa/api/instantaneous/data	Application	Subscribe	Platform → App	GeisaInstantaneousQuantities	Broadcast
	geisa/api/instantaneous/data	Platform	Publish	Platform → App	GeisaInstantaneousQuantities	Broadcast
Billing Data	geisa/api/billing/data	Application	Subscribe	Platform → App	GeisaBillingQuantities	Broadcast
	geisa/api/billing/data	Platform	Publish	Platform → App	GeisaBillingQuantities	Broadcast
Waveform Data	geisa/api/waveform/req/<userid>	Application	Publish	App → Platform	GeisaWaveform_Req	Request
	geisa/api/waveform/rsp/<userid>	Application	Subscribe	Platform → App	GeisaWaveform_Rsp	Response
	geisa/api/waveform/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaWaveform_Req	Request
	geisa/api/waveform/rsp/<userid>	Platform	Publish	Platform → App	GeisaWaveform_Rsp	Response
Actuator Status & Control	geisa/api/actuator/get/req/<userid>	Application	Publish	App → Platform	GeisaActuatorGet_Req	Request
	geisa/api/actuator/get/rsp/<userid>	Application	Subscribe	Platform → App	GeisaActuatorGet_Rsp	Response
	geisa/api/actuator/set/req/<userid>	Application	Publish	App → Platform	GeisaActuatorSet_Req	Request
	geisa/api/actuator/set/rsp/<userid>	Application	Subscribe	Platform → App	GeisaActuatorSet_Rsp	Response
	geisa/api/actuator/get/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaActuatorGet_Req	Request
	geisa/api/actuator/get/rsp/<userid>	Platform	Publish	Platform → App	GeisaActuatorGet_Rsp	Response
	geisa/api/actuator/set/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaActuatorSet_Req	Request
	geisa/api/actuator/set/rsp/<userid>	Platform	Publish	Platform → App	GeisaActuatorSet_Rsp	Response
Sensors	geisa/api/sensor	Application	Subscribe	Platform → App	GeisaSensorReading	Broadcast
	geisa/api/sensor/req/<userid>	Application	Publish	App → Platform	GeisaSensorReadings_Req	Request
	geisa/api/sensor/rsp/<userid>	Application	Subscribe	Platform → App	GeisaSensorReadings_Rsp	Response
	geisa/api/sensor	Platform	Publish	Platform → App	GeisaSensorReading	Broadcast
	geisa/api/sensor/req/#	Platform	Wildcard Subscribe	App → Platform	GeisaSensorReadings_Req	Request
	geisa/api/sensor/rsp/<userid>	Platform	Publish	Platform → App	GeisaSensorReadings_Rsp	Response
App-to-App	geisa/api/app2app/pub/<SName>/<AppID-A>	Application Publisher (A)	Publish	App A → App B	N/A	Broadcast
	geisa/api/app2app/pub/<SName>/#	Application Subscriber (B)	Wildcard Subscribe	App A → App B	N/A	Broadcast
	geisa/api/app2app/req/<SName>/#	Application Responder (A)	Wildcard Subscribe	App B → App A	N/A	Request
	geisa/api/app2app/rsp/<SName>/<AppID-B>/<AppID-A>	Application Responder (A)	Publish	App A → App B	N/A	Response
	geisa/api/app2app/rsp/<SName>/<AppID-B>/#	Application Requester (B)	Wildcard Subscribe	App A → App B	N/A	Response
	geisa/api/app2app/req/<SName>/<AppID-B>	Application Requester (B)	Publish	App B → App A	N/A	Request

Actuator payloads are defined by GeisaActuatorGet_Req, GeisaActuatorGet_Rsp, GeisaActuatorSet_Req, and GeisaActuatorSet_Rsp. Status and control are permission-gated. Actuator support and target availability are platform-specific.