Gridshare Partner API — Devices

naftiko: 1.0.0-alpha2
info:
  label: Gridshare Partner API — Devices
  description: 'Gridshare Partner API — Devices, Telemetry, Operation Mode, and Overlay Plans for the fleet operator.'
  tags:
    - Lunar Energy
    - Gridshare
    - Partner
    - Devices
    - Telemetry
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
  - namespace: env
    keys:
      GRIDSHARE_ACCESS_TOKEN: GRIDSHARE_ACCESS_TOKEN
capability:
  consumes:
    - type: http
      namespace: partner-devices
      baseUri: https://developer-api.partner.us.mygridshare.com
      description: Gridshare Partner Devices resource family.
      resources:
        - name: devices
          path: /api/v1/devices
          operations:
            - name: listdevices
              method: GET
              description: List Devices
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: createdevice
              method: POST
              description: Create Device
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: devices-synthid
          path: /api/v1/devices/{synthId}
          operations:
            - name: getdevice
              method: GET
              description: Get Device
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: replaceorcreatedevice
              method: PUT
              description: Replace Or Create Device
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: devices-synthid-telemetry
          path: /api/v1/devices/{synthId}/telemetry
          operations:
            - name: getdevicetelemetry
              method: GET
              description: Get Device Telemetry
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: devices-synthid-operationmode
          path: /api/v1/devices/{synthId}/operationmode
          operations:
            - name: getdeviceoperationmode
              method: GET
              description: Get Device Operation Mode
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: setdeviceoperationmode
              method: PUT
              description: Change Device Operation Mode
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: devices-synthid-plans-overlay
          path: /api/v1/devices/{synthId}/plans/overlay
          operations:
            - name: getdeviceoverlayplan
              method: GET
              description: Get Device Overlay Plan
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: setdeviceoverlayplan
              method: PUT
              description: Set Device Overlay Plan
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: counterfactuals-telemetry
          path: /api/v1/counterfactuals/{counterfactualName}/devices/{deviceId}/telemetry
          operations:
            - name: getcounterfactualtelemetry
              method: GET
              description: Get Counterfactual Telemetry
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
      authentication:
        type: bearer
        value: '{{env.GRIDSHARE_ACCESS_TOKEN}}'
        placement: header
  exposes:
    - type: mcp
      namespace: partner-devices-mcp
      port: 9090
      transport: http
      description: MCP adapter for Gridshare Partner Devices.
      tools:
        - name: gridshare-partner-list-devices
          description: List Devices
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: partner-devices.listdevices
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-get-device
          description: Get Device
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: partner-devices.getdevice
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-create-device
          description: Create Device
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: partner-devices.createdevice
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-replace-device
          description: Replace Or Create Device
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: partner-devices.replaceorcreatedevice
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-get-device-telemetry
          description: Get Device Telemetry
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: partner-devices.getdevicetelemetry
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-get-device-operation-mode
          description: Get Device Operation Mode
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: partner-devices.getdeviceoperationmode
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-set-device-operation-mode
          description: Change Device Operation Mode
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: partner-devices.setdeviceoperationmode
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-get-device-overlay-plan
          description: Get Device Overlay Plan
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: partner-devices.getdeviceoverlayplan
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-set-device-overlay-plan
          description: Set Device Overlay Plan
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: partner-devices.setdeviceoverlayplan
          outputParameters: [{ type: object, mapping: $. }]
        - name: gridshare-partner-get-counterfactual-telemetry
          description: Get Counterfactual Telemetry
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: partner-devices.getcounterfactualtelemetry
          outputParameters: [{ type: object, mapping: $. }]