> ## Documentation Index > Fetch the complete documentation index at: https://docs.nox.energy/llms.txt > Use this file to discover all available pages before exploring further. # Get Devices > Get information about all NOX connected devices associated with your energy supplier account. If you want to know the response structure or possible enum values, like steerable reasons, you can check it in the response model `schema`. ## OpenAPI ````yaml /api-docs/full-control/openapi-full-control.json get /v1/devices openapi: 3.1.0 info: title: NOX Energy API - Full Control description: > # Full Control API Documentation This documentation shows only the endpoints available to full control users. ## Authentication 1. Get your API key from [NOX Energy](mailto:support@nox.energy). 2. Include the API key in your API calls with the header: `x-api-key: YOUR_API_KEY`. ## Access Level This documentation is specifically for **full control users** who have access to these endpoints. Base URL: [https://api.nox.energy](https://api.nox.energy) version: 1.0.0 servers: - url: https://api.nox.energy description: Production Server security: - ApiKeyAuth: [] tags: - name: Asset Info description: API to get basic information about your assets. - name: Device Consumption description: API to get consumption data of your devices. - name: User Management description: API endpoints to manage users and their data. paths: /v1/devices: get: tags: - Asset Info summary: Get Devices description: >- Get information about all NOX connected devices associated with your energy supplier account. If you want to know the response structure or possible enum values, like steerable reasons, you can check it in the response model `schema`. operationId: get_devices_v1_devices_get parameters: - name: limit in: query required: false schema: type: integer maximum: 4000 minimum: 1 description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. default: 1000 title: Limit description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. - name: steerable_status in: query required: false schema: type: boolean description: > If `true`, return only data related to the device's current steerable status. If `false` or not given, return all available device data including its status. default: false title: Steerable Status description: > If `true`, return only data related to the device's current steerable status. If `false` or not given, return all available device data including its status. - name: steering_enabled in: query required: false schema: type: boolean description: > If `true`, return only data related to the device's which has `steering_enabled` = `true`. If `false` or not given, do not filter on `steering_enabled` field. default: false title: Steering Enabled description: > If `true`, return only data related to the device's which has `steering_enabled` = `true`. If `false` or not given, do not filter on `steering_enabled` field. - name: steerable in: query required: false schema: type: boolean description: > If `true`, return only data related to the device's which has `steerable` = `true`. If `false` or not given, do not filter on `steerable` field. default: false title: Steerable description: > If `true`, return only data related to the device's which has `steerable` = `true`. If `false` or not given, do not filter on `steerable` field. - name: next_token in: query required: false schema: anyOf: - type: string - type: 'null' description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. title: Next Token description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. - name: device_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > The ID of the device to filter on. If not provided, all devices are returned. title: Device Id description: > The ID of the device to filter on. If not provided, all devices are returned. - name: user_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > The ID of the user to filter on. If not provided, all users are returned. title: User Id description: > The ID of the user to filter on. If not provided, all users are returned. - name: needs_reauthentication in: query required: false schema: anyOf: - type: boolean - type: 'null' description: | If `True`, filter devices that need reauthentication. default: false title: Needs Reauthentication description: | If `True`, filter devices that need reauthentication. - name: learning_period_ended in: query required: false schema: anyOf: - type: boolean - type: 'null' description: >+ If `True`, filter devices for which the learning period of gathering data has ended. If `False`, filter devices for which the learning period of gathering data has not ended. If `None`, do not filter based on learning period status. title: Learning Period Ended description: >+ If `True`, filter devices for which the learning period of gathering data has ended. If `False`, filter devices for which the learning period of gathering data has not ended. If `None`, do not filter based on learning period status. - name: has_delayed_power_data_1d in: query required: false schema: anyOf: - type: boolean - type: 'null' description: >+ If `True`, filter devices that have delayed power data by 1 day for the previous day. This means that the power data of the previous day is only updated between 2-4 AM UTC on a daily basis for the full previous day. If `False`, filter devices that do not have delayed power data by 1 day for the previous day but instead provide real-time power data. If `None`, do not filter based on whether devices have delayed power data by 1 day for the previous day. title: Has Delayed Power Data 1D description: >+ If `True`, filter devices that have delayed power data by 1 day for the previous day. This means that the power data of the previous day is only updated between 2-4 AM UTC on a daily basis for the full previous day. If `False`, filter devices that do not have delayed power data by 1 day for the previous day but instead provide real-time power data. If `None`, do not filter based on whether devices have delayed power data by 1 day for the previous day. - name: model_type in: query required: false schema: anyOf: - type: string - type: 'null' description: > The model type to filter on, e.g. 'ata', 'atw', 'wtw'. If None, do not filter on model type. title: Model Type description: > The model type to filter on, e.g. 'ata', 'atw', 'wtw'. If None, do not filter on model type. - name: has_cooling in: query required: false schema: anyOf: - type: boolean - type: 'null' description: |+ If `True`, filter devices that have cooling capabilities. If `False`, filter devices that do not have cooling capabilities. If `None`, do not filter based on cooling capabilities. title: Has Cooling description: |+ If `True`, filter devices that have cooling capabilities. If `False`, filter devices that do not have cooling capabilities. If `None`, do not filter based on cooling capabilities. - name: has_room_schedule in: query required: false schema: anyOf: - type: boolean - type: 'null' description: |+ If `True`, filter devices that have a room schedule. If `False`, filter devices that do not have a room schedule. If `None`, do not filter based on room schedule. title: Has Room Schedule description: |+ If `True`, filter devices that have a room schedule. If `False`, filter devices that do not have a room schedule. If `None`, do not filter based on room schedule. - name: being_steered in: query required: false schema: anyOf: - type: boolean - type: 'null' description: |+ If `True`, filter devices that are currently being steered. If `False`, filter devices that are not currently being steered. If `None`, do not filter based on being steered. title: Being Steered description: |+ If `True`, filter devices that are currently being steered. If `False`, filter devices that are not currently being steered. If `None`, do not filter based on being steered. - name: brand in: query required: false schema: anyOf: - type: string - type: 'null' description: | Filter on device brand. If `None`, do not filter on brand. title: Brand description: | Filter on device brand. If `None`, do not filter on brand. responses: '200': description: Successful response for thermal-control API content: application/json: schema: $ref: '#/components/schemas/DevicesResponse' example: data: - model: model_g model_type: atw brand: nibe country: BE device_id: 01a5c222-5b76-4531-b587-5deeb81a3db3 user_id: user_4 device_type: heat_pump has_delayed_power_data_1d: true legionella_config: frequency_per_weeks: 1 capacity: 20 duration_minutes: 60 cycle_config: max_cycles_per_day: 8 room_min_cycle_time: 15 dhw_min_cycle_time: 30 dhw_max_cycle_time: 120 steerable_status: steering_enabled: true steerable: true learning_period_ended: true general_reason: >- Heat pump connected recently, still collecting data to improve models. DHW: can_activate_action: true in_active_action: false reason: Device is ready to receive an action. room: can_activate_action: true in_active_action: false reason: Device is ready to receive an action. has_cooling: true being_steered: true being_steered_start_date: '2025-09-30' needs_reauthentication: false has_room_schedule: false first_connection_at: '2025-09-30T12:00:00+00:00' - model: model_b model_type: atw brand: nibe device_id: 01bbbaab-159a-4898-bcba-d81acdb2353c user_id: user_5 device_type: heat_pump has_delayed_power_data_1d: false legionella_config: frequency_per_weeks: 2 capacity: 20 duration_minutes: 60 cycle_config: max_cycles_per_day: 6 room_min_cycle_time: 15 dhw_min_cycle_time: 30 dhw_max_cycle_time: 60 steerable_status: steering_enabled: true steerable: true learning_period_ended: true general_reason: >- Heat pump connected recently, still collecting data to improve models. DHW: can_activate_action: true in_active_action: false reason: Device is ready to receive an action. room: can_activate_action: true in_active_action: false reason: Device is ready to receive an action. has_cooling: false being_steered: false needs_reauthentication: false has_room_schedule: false first_connection_at: '2025-09-30T12:00:00+00:00' meta: energy_supplier: Energy Supplier A capacity_unit: kWh next_token: >- eyJkZXZpY2VfaWQiOiAiMDFiYmJhYWItMTU5YS00ODk4LWJjYmEtZDgxYWNkYjIzNTNjIiwgImVuZXJneV9zdXBwbGllciI6ICJFbmVyZ3kgU3VwcGxpZXIgQSJ9 cycle_time_units: minutes being_steered_start_date_unit: UTC '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: DevicesResponse: properties: data: anyOf: - items: $ref: '#/components/schemas/Device' type: array - type: 'null' title: Data description: List of devices meta: anyOf: - $ref: '#/components/schemas/DevicesMeta' - type: 'null' description: Response metadata type: object title: DevicesResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Device: properties: model: anyOf: - type: string - type: 'null' title: Model description: Device model model_type: anyOf: - $ref: '#/components/schemas/ModelType' - type: 'null' description: >- Device model type such as (Air to Air Heat Pump, Air to Water Heat Pump, Water to Water Heat Pump) brand: anyOf: - type: string - type: 'null' title: Brand description: Device brand country: anyOf: - type: string - type: 'null' title: Country description: Country code device_id: anyOf: - type: string - type: 'null' title: Device Id description: Unique device identifier user_id: anyOf: - type: string - type: 'null' title: User Id description: User identifier device_type: anyOf: - type: string - type: 'null' title: Device Type description: Type of device has_delayed_power_data_1d: anyOf: - type: boolean - type: 'null' title: Has Delayed Power Data 1D description: >- Whether the device has delayed power data by 1 day for the previous day. This power data is updated between 2-4 AM UTC on a daily basis for the full previous day. legionella_config: anyOf: - $ref: '#/components/schemas/LegionellaConfig' - type: 'null' description: Legionella prevention configuration cycle_config: anyOf: - $ref: '#/components/schemas/CycleConfig' - type: 'null' description: Cycle configuration steerable_status: anyOf: - $ref: >- #/components/schemas/app__models__hp__device_models__SteerableStatus - type: 'null' description: Device steering status needs_reauthentication: anyOf: - type: boolean - type: 'null' title: Needs Reauthentication description: Whether the device needs reauthentication has_room_schedule: anyOf: - type: boolean - type: 'null' title: Has Room Schedule description: Whether the device has a room schedule currently set. first_connection_at: anyOf: - type: string - type: 'null' title: First Connection At description: >- The date when the device was first connected to Nox, in UTC time format. type: object title: Device DevicesMeta: properties: energy_supplier: anyOf: - type: string - type: 'null' title: Energy Supplier description: Energy supplier name capacity_unit: anyOf: - type: string - type: 'null' title: Capacity Unit description: Unit for capacity measurements next_token: anyOf: - type: string - type: 'null' title: Next Token description: Token for pagination cycle_time_units: anyOf: - type: string - type: 'null' title: Cycle Time Units description: >- Unit for MAX or MIN cycle times. Which is the amount of minutes a unit can be active for that purpose. being_steered_start_date_unit: anyOf: - type: string - type: 'null' title: Being Steered Start Date Unit description: >- Unit for being_steered_start_date, which is the date when we first started steering this device. type: object title: DevicesMeta ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ModelType: type: string enum: - ata - atw - wtw title: ModelType LegionellaConfig: properties: frequency_per_weeks: anyOf: - type: integer - type: 'null' title: Frequency Per Weeks description: Frequency per weeks for legionella prevention capacity: anyOf: - type: number - type: 'null' title: Capacity description: Capacity for legionella prevention duration_minutes: anyOf: - type: integer - type: 'null' title: Duration Minutes description: Duration in minutes for legionella prevention type: object title: LegionellaConfig CycleConfig: properties: max_cycles_per_day: anyOf: - type: integer - type: 'null' title: Max Cycles Per Day description: Maximum cycles allowed per day room_min_cycle_time: anyOf: - type: integer - type: 'null' title: Room Min Cycle Time description: Minimum cycle time for room heating in minutes, if applicable. dhw_min_cycle_time: anyOf: - type: integer - type: 'null' title: Dhw Min Cycle Time description: Minimum cycle time for DHW in minutes, if applicable. dhw_max_cycle_time: anyOf: - type: integer - type: 'null' title: Dhw Max Cycle Time description: Maximum cycle time for DHW in minutes, if applicable. type: object title: CycleConfig app__models__hp__device_models__SteerableStatus: properties: steering_enabled: anyOf: - type: boolean - type: 'null' title: Steering Enabled description: Whether steering is enabled steerable: anyOf: - type: boolean - type: 'null' title: Steerable description: Whether device is steerable learning_period_ended: anyOf: - type: boolean - type: 'null' title: Learning Period Ended description: Whether the learning period has ended general_reason: anyOf: - $ref: >- #/components/schemas/app__models__hp__device_models__GeneralReason - type: 'null' description: General reason for steerable status DHW: anyOf: - $ref: '#/components/schemas/ActionStatus' - type: 'null' description: Domestic Hot Water action status room: anyOf: - $ref: '#/components/schemas/ActionStatus' - type: 'null' description: Room heating action status has_cooling: anyOf: - type: boolean - type: 'null' title: Has Cooling description: Whether the device has cooling capabilities being_steered: anyOf: - type: boolean - type: 'null' title: Being Steered description: Whether the device is currently being steered being_steered_start_date: anyOf: - type: string - type: 'null' title: Being Steered Start Date description: Start date of when we first started steering this device. type: object title: SteerableStatus app__models__hp__device_models__GeneralReason: type: string enum: - Heat pump connected recently, still collecting data to improve models. - Processing error, please contact support. - >- Device disconnected, it might reconnect later or be permanently be disconnected. - Device in error state. Might recover automatically later. - User settings prevent steering. - Holiday mode active, steering disabled or blocked by device. - Device is turned off, steering disabled or blocked by device. - >- Device is unsupported brand/model, will be supported in future updates. - Device is unsupported model, will not be supported in future updates. - Air to Air Heat pumps not supported for this brand yet. - Air to Water Heat pumps not supported for this brand yet. - Water to Water Heat pumps not supported for this brand yet. - Multi zone air to air devices not supported yet. - Device gateway model does not allow steering. - Important data missing, this might improve with future updates. - Important data missing, will not be supported in future updates. - Unauthorized country, steering not allowed in this country. - Reauthentication required. - Too many heating zones, steering not supported for this configuration. - Unknown reason, please contact support. title: GeneralReason ActionStatus: properties: can_activate_action: anyOf: - type: boolean - type: 'null' title: Can Activate Action description: Whether action can be activated in_active_action: anyOf: - type: boolean - type: 'null' title: In Active Action description: Whether currently in active action reason: anyOf: - $ref: '#/components/schemas/Reason' - type: 'null' description: Reason for the current status type: object title: ActionStatus Reason: type: string enum: - No flexibility available based on current device state. - Cycle constraints prevent a new action at this time. - Cycle constraints forced stop of current cycle. - No DHW control available on this device. - No room control available on this device. - Outside comfort band, Nox takes over until within comfort. - No schedule available, Nox takes over to assure comfort. - Can receive actions. - Early activation command send to device, following DHW tank schedule. - DHW tank active, following DHW tank schedule. - >- Early deactivation command send to device, following DHW tank schedule. - >- Early activation command send to device, following room heating/cooling schedule. - Room heating/cooling active, following room heating/cooling schedule. - >- Early deactivation command send to device, following room heating/cooling schedule. - Room schedule not writable and enabled, ask end user to disable it. - Uncertain heat pump activity, waiting for more data. - Cannot steer space heating when ata is off. - Processing error, please contact support. title: Reason securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: 'API Key authentication. Enter your API key in the format: YOUR_API_KEY' ````