> ## Documentation Index > Fetch the complete documentation index at: https://docs.amps.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get battery state > Retrieve the current state and capabilities of a battery device. ## OpenAPI ````yaml /openapi.json get /battery/{deviceId} openapi: 3.1.0 info: title: Amps.ai API description: >- Energy device management API for batteries, EV chargers, solar inverters, and HVAC systems version: '1.0' contact: {} servers: - url: https://api.amps.ai description: Amps API security: [] tags: [] paths: /battery/{deviceId}: get: tags: - Battery summary: Get battery state description: Retrieve the current state and capabilities of a battery device. operationId: getBattery parameters: - name: expedite required: false in: query description: >- Bypass the standard 15-minute cache and serve a result no older than 1 minute. Use sparingly; cache misses incur a live OEM round-trip. schema: example: false type: boolean - name: deviceId required: true in: path description: The unique identifier for the battery device. schema: example: device_abc123 type: string responses: '200': description: Battery state retrieved successfully. content: application/json: schema: type: object required: - success - data - meta properties: success: type: boolean const: true description: Always `true` for success responses. data: $ref: '#/components/schemas/BatteryResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: batteryIdle: summary: Battery idling — no charge or discharge activity description: >- `status: idle` and `chargeRate: 0`. The device is in `auto.balance` but has nothing to do at the moment. Capabilities map shows the full canonical surface; bounds are typical, not OEM-specific. value: success: true data: id: device_abc123 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Hybrid 5kWh source: cache cacheType: normal state: status: idle capacity: 10.4 level: 67 chargeRate: 0 dischargeLimit: 10 currentMode: auto.balance conflictStrategies: - cancel_and_replace - queue_after commands: charge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed discharge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed idle: parameters: {} execution: - immediate - scheduled auto.balance: parameters: {} execution: - immediate - scheduled auto.reserve: parameters: {} execution: - immediate - scheduled auto.export: parameters: {} execution: - immediate - scheduled settings: safety_reserve: value: 10 unit: percent min: 0 max: 100 discharge_floor: value: 20 unit: percent min: 0 max: 100 charge_ceiling: value: 100 unit: percent min: 0 max: 100 export_limit: value: 5000 unit: watts min: 0 max_charge_rate: value: 25 unit: amps min: 0 max_discharge_rate: value: 25 unit: amps min: 0 scheduler_enabled: value: false lastAction: id: action_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryCharging: summary: Battery actively charging description: >- `status: charging` with positive `chargeRate`. `currentMode: charge` reflects the active canonical mode. value: success: true data: id: device_abc123 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Hybrid 5kWh source: live cacheType: normal state: status: charging capacity: 10.4 level: 55 chargeRate: 2.4 dischargeLimit: 10 currentMode: charge conflictStrategies: - cancel_and_replace - queue_after commands: charge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed discharge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed idle: parameters: {} execution: - immediate - scheduled auto.balance: parameters: {} execution: - immediate - scheduled auto.reserve: parameters: {} execution: - immediate - scheduled auto.export: parameters: {} execution: - immediate - scheduled settings: safety_reserve: value: 10 unit: percent min: 0 max: 100 discharge_floor: value: 20 unit: percent min: 0 max: 100 charge_ceiling: value: 100 unit: percent min: 0 max: 100 export_limit: value: 5000 unit: watts min: 0 max_charge_rate: value: 25 unit: amps min: 0 max_discharge_rate: value: 25 unit: amps min: 0 scheduler_enabled: value: false lastAction: id: action_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryDischarging: summary: Battery actively discharging description: >- Negative `chargeRate` indicates discharge. `status` is `discharging` and `currentMode` reflects the canonical mode. value: success: true data: id: device_abc123 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Hybrid 5kWh source: live cacheType: normal state: status: discharging capacity: 10.4 level: 38 chargeRate: -3.1 dischargeLimit: 10 currentMode: discharge conflictStrategies: - cancel_and_replace - queue_after commands: charge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed discharge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed idle: parameters: {} execution: - immediate - scheduled auto.balance: parameters: {} execution: - immediate - scheduled auto.reserve: parameters: {} execution: - immediate - scheduled auto.export: parameters: {} execution: - immediate - scheduled settings: safety_reserve: value: 10 unit: percent min: 0 max: 100 discharge_floor: value: 20 unit: percent min: 0 max: 100 charge_ceiling: value: 100 unit: percent min: 0 max: 100 export_limit: value: 5000 unit: watts min: 0 max_charge_rate: value: 25 unit: amps min: 0 max_discharge_rate: value: 25 unit: amps min: 0 scheduler_enabled: value: false lastAction: id: action_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryAutoBalanced: summary: Battery in auto.balance — platform-managed self-consumption description: >- Auto modes carry no parameters. `currentMode: auto.balance` lets the platform decide when to charge or discharge to minimise grid spend. value: success: true data: id: device_abc123 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: Hybrid 5kWh source: cache cacheType: normal state: status: idle capacity: 10.4 level: 72 chargeRate: 0 dischargeLimit: 10 currentMode: auto.balance conflictStrategies: - cancel_and_replace - queue_after commands: charge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed discharge: parameters: target: unit: percent min: 10 max: 100 power: unit: kw min: 0 max: 5 reserve: unit: percent min: 0 max: 100 execution: - immediate - scheduled - windowed idle: parameters: {} execution: - immediate - scheduled auto.balance: parameters: {} execution: - immediate - scheduled auto.reserve: parameters: {} execution: - immediate - scheduled auto.export: parameters: {} execution: - immediate - scheduled settings: safety_reserve: value: 10 unit: percent min: 0 max: 100 discharge_floor: value: 20 unit: percent min: 0 max: 100 charge_ceiling: value: 100 unit: percent min: 0 max: 100 export_limit: value: 5000 unit: watts min: 0 max_charge_rate: value: 25 unit: amps min: 0 max_discharge_rate: value: 25 unit: amps min: 0 scheduler_enabled: value: false lastAction: id: action_def456 command: charge state: completed createdAt: '2026-05-07T08:15:00.000Z' updatedAt: '2026-05-07T08:18:00.000Z' links: self: /actions/action_def456 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryReducedCapabilities: summary: >- Battery with a reduced capability surface — only `charge`, `discharge`, `idle` description: >- Not every device supports every canonical mode. Capabilities are presence-based: a mode key is included only when the device declares it. This device omits the auto.* family and the windowed execution shape. value: success: true data: id: device_xyz789 vendor: example_vendor_b sync: available: true lastPulledAt: '2026-05-07T09:24:10.000Z' metadata: model: Hybrid Gen 2 source: live cacheType: normal state: status: idle capacity: 9.5 level: 42 chargeRate: 0 dischargeLimit: 10 currentMode: idle commands: charge: parameters: target: unit: percent min: 10 max: 100 execution: - immediate - scheduled discharge: parameters: target: unit: percent min: 10 max: 100 execution: - immediate - scheduled idle: parameters: {} execution: - immediate - scheduled conflictStrategies: - cancel_and_replace - queue_after settings: {} lastAction: id: action_ghi789 command: discharge state: completed createdAt: '2026-05-07T07:40:00.000Z' updatedAt: '2026-05-07T07:43:00.000Z' links: self: /actions/action_ghi789 currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 batteryNoMetadataYet: summary: Newly-registered battery — minimal capability surface description: >- A device that has just registered. Its state is served from the most recent stored read (`metadata.source: cache`) while the device advertises only a minimal command set. value: success: true data: id: device_minimal_001 vendor: example_vendor_c sync: available: true lastPulledAt: '2026-05-07T09:24:30.000Z' metadata: model: Example 5kWh source: cache cacheType: normal state: status: idle capacity: 5 level: 80 chargeRate: 0 dischargeLimit: 5 currentMode: auto.balance commands: charge: parameters: {} execution: - immediate - scheduled discharge: parameters: {} execution: - immediate - scheduled conflictStrategies: - cancel_and_replace - queue_after settings: {} lastAction: null currentSchedule: null meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- The device manufacturer rejected the pull request (`INVALID_PARAMETERS` or `COMMAND_FAILED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: No `x-api-key` header present value: success: false error: code: UNAUTHORIZED message: Authentication is required. details: description: API key is required meta: requestId: req_8sW2dRtX timestamp: '2026-04-29T12:00:00.000Z' path: /battery/device_abc123 latencyMs: 2 '403': description: >- Live access is disabled, consent is revoked, the device allowance is exceeded, or the manufacturer denied access to the device (`DEVICE_UNAUTHORIZED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- Device not found, access denied, or no data available for this device. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceNotFound: summary: No device matches the ID for this customer value: success: false error: code: DEVICE_NOT_FOUND message: No matching device was found for the supplied details. details: description: Device not found or access denied meta: requestId: req_5pH1cQbY timestamp: '2026-04-29T12:00:00.000Z' path: /battery/device_unknown_999 latencyMs: 5 noDataAvailable: summary: Device exists but has never been pulled value: success: false error: code: DEVICE_NOT_FOUND message: No matching device was found for the supplied details. meta: requestId: req_7tG6vCxA timestamp: '2026-04-29T12:00:00.000Z' path: /battery/device_abc123 latencyMs: 28 '410': description: >- The device is offline at the manufacturer. See the [device error codes](/reference/error-codes) reference for retry guidance. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceOffline: summary: >- The manufacturer reports the device as offline. Use the cached state from the previous pull, or retry once the device is back online. value: success: false error: code: DEVICE_OFFLINE message: The device is currently offline at the manufacturer. meta: requestId: req_FnP7tAhH timestamp: '2026-04-29T12:00:00.000Z' path: /battery/device_abc123 latencyMs: 142 '503': description: >- The device manufacturer service is temporarily unavailable. Retryable with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: >- The manufacturer cloud is down or refusing requests. Retry with backoff. value: success: false error: code: SERVICE_UNAVAILABLE message: >- The device manufacturer service is temporarily unavailable. meta: requestId: req_GoQ8uBiI timestamp: '2026-04-29T12:00:00.000Z' path: /battery/device_abc123 latencyMs: 1873 security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request GET \ --url 'https://api.amps.ai/battery/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/battery/device_abc123', { method: 'GET', headers: { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', }, }); const data = await response.json(); - lang: python label: Python source: |- import requests url = 'https://api.amps.ai/battery/device_abc123' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', } response = requests.get(url, headers=headers) data = response.json() components: schemas: BatteryResponse: type: object properties: id: type: string vendor: type: string sync: type: object properties: available: type: boolean lastPulledAt: anyOf: - type: string - type: 'null' required: - available - lastPulledAt metadata: type: object properties: model: type: string cacheType: type: string enum: - expedite - normal source: type: string enum: - cache - live - fallback - projection description: >- How this device-state reading was obtained. `live`: read from the device just now. `cache`: a recent reading served from cache. `fallback`: the most recent stored reading, returned when the device could not be reached. `projection`: simulated sandbox state — sandbox devices are not physical hardware, so their reported state reflects the commands you have sent. degraded: description: >- Present and `true` when this reading was served from stored state because the platform is temporarily not contacting this device’s manufacturer (a protective circuit is open). The data is the most recent known reading, not a live one. Absent on a normal reading. type: boolean required: - model - source state: type: object properties: status: type: string enum: - charging - discharging - idle - standby capacity: type: number level: type: number minimum: 0 maximum: 100 chargeRate: type: number dischargeLimit: type: number currentMode: type: string required: - status - capacity - level - chargeRate - dischargeLimit commands: type: object properties: charge: description: Active charge from grid or solar. type: object properties: parameters: type: object properties: target: description: >- Present when the device accepts a `target` SoC limit on this command. Upper SoC limit on `charge`, lower SoC limit on `discharge`. Send a value via `POST /battery/{deviceId}` within these bounds. type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number power: description: >- Present when the device accepts a `power` rate cap on this command. Send a value via `POST /battery/{deviceId}` within these bounds. type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number reserve: description: >- Present when the device accepts a `reserve` floor on this command. The reserve floor is preserved while the mode is active. type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number description: >- Parameter bounds for the `charge` command. Each canonical parameter is presence-based: a key is included only when the device declares bounds for it. Empty when the command takes no parameters at all. execution: type: array items: type: string enum: - immediate - scheduled - windowed description: >- Execution shapes the device accepts. `immediate` = no `start`; `scheduled` = `start` alone; `windowed` = `start` + `end`. required: - parameters - execution discharge: description: Active discharge to power the home or export. type: object properties: parameters: type: object properties: target: description: >- Present when the device accepts a `target` SoC limit on this command. Upper SoC limit on `charge`, lower SoC limit on `discharge`. Send a value via `POST /battery/{deviceId}` within these bounds. type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number power: description: >- Present when the device accepts a `power` rate cap on this command. Send a value via `POST /battery/{deviceId}` within these bounds. type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number reserve: description: >- Present when the device accepts a `reserve` floor on this command. The reserve floor is preserved while the mode is active. type: object properties: unit: description: Unit of measure (e.g. `percent`, `kw`). type: string min: description: Lower bound for the parameter value. type: number max: description: Upper bound for the parameter value. type: number step: description: >- Increment the value must land on, counted from `min` (or from 0 when no `min` is declared). A value off the grid is rejected. Absent when the device accepts any value within the bounds. type: number description: >- Parameter bounds for the `discharge` command. Each canonical parameter is presence-based: a key is included only when the device declares bounds for it. Empty when the command takes no parameters at all. execution: type: array items: type: string enum: - immediate - scheduled - windowed description: >- Execution shapes the device accepts. `immediate` = no `start`; `scheduled` = `start` alone; `windowed` = `start` + `end`. required: - parameters - execution idle: description: Pause all charge and discharge activity. type: object properties: parameters: type: object properties: {} description: >- Parameter bounds for the `idle` command. Each canonical parameter is presence-based: a key is included only when the device declares bounds for it. Empty when the command takes no parameters at all. execution: type: array items: type: string enum: - immediate - scheduled - windowed description: >- Execution shapes the device accepts. `immediate` = no `start`; `scheduled` = `start` alone; `windowed` = `start` + `end`. required: - parameters - execution auto.balance: description: >- Optimise for self-consumption: charge when solar is plentiful, discharge when the home needs it. type: object properties: parameters: type: object properties: {} description: >- Parameter bounds for the `auto.balance` command. Each canonical parameter is presence-based: a key is included only when the device declares bounds for it. Empty when the command takes no parameters at all. execution: type: array items: type: string enum: - immediate - scheduled - windowed description: >- Execution shapes the device accepts. `immediate` = no `start`; `scheduled` = `start` alone; `windowed` = `start` + `end`. required: - parameters - execution auto.reserve: description: >- Reserve capacity for grid outage protection. Stay charged above the reserve floor. type: object properties: parameters: type: object properties: {} description: >- Parameter bounds for the `auto.reserve` command. Each canonical parameter is presence-based: a key is included only when the device declares bounds for it. Empty when the command takes no parameters at all. execution: type: array items: type: string enum: - immediate - scheduled - windowed description: >- Execution shapes the device accepts. `immediate` = no `start`; `scheduled` = `start` alone; `windowed` = `start` + `end`. required: - parameters - execution auto.export: description: >- Maximise grid export. Discharge to the grid whenever the export tariff is attractive. type: object properties: parameters: type: object properties: {} description: >- Parameter bounds for the `auto.export` command. Each canonical parameter is presence-based: a key is included only when the device declares bounds for it. Empty when the command takes no parameters at all. execution: type: array items: type: string enum: - immediate - scheduled - windowed description: >- Execution shapes the device accepts. `immediate` = no `start`; `scheduled` = `start` alone; `windowed` = `start` + `end`. required: - parameters - execution description: >- Per-canonical-command capability and the per-device source of truth for orchestration. Use it to validate or build push bodies before sending them to `POST /battery/{deviceId}`. Presence-based at every level: a command is included only when the device supports it, and within each command a parameter is included only when the device accepts that parameter. Each present entry carries the parameter bounds and the execution shapes (`immediate` / `scheduled` / `windowed`) the device accepts. conflictStrategies: type: array items: type: string enum: - cancel_and_replace - queue_after description: >- Conflict-resolution strategies this device accepts on `onConflict`. Empty when the device declares none. settings: type: object properties: safety_reserve: description: >- Lowest state-of-charge the battery will ever reach, even during a power cut. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value discharge_floor: description: >- Lowest state-of-charge the battery will reach during normal operation. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value charge_ceiling: description: Highest state-of-charge the battery will charge to. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value export_limit: description: Maximum power the battery can send back to the grid. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value max_charge_rate: description: Maximum rate the battery will charge at. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value max_discharge_rate: description: Maximum rate the battery will discharge at. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value scheduler_enabled: description: >- Whether the device's native scheduler is active. Auto-managed; read-only. type: object properties: value: anyOf: - anyOf: - type: number - type: boolean - type: string - type: 'null' description: >- Current setting value. `null` if the device has not yet synced this setting. unit: description: Unit of measure for numeric settings. type: string min: description: Lower bound for the setting value. type: number max: description: Upper bound for the setting value. type: number required: - value description: >- Per-canonical-setting current value and bounds. Presence-based: a field is present when the device exposes that setting, absent when the device does not. scheduling: type: object properties: maxSlots: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- The largest number of slots a single schedule on this device can hold. supportsRecurrence: type: boolean description: >- Whether this device accepts a `recurrence` rule on a schedule. When `false`, only one-shot schedules are accepted. slotVariants: type: array items: type: string enum: - at - time description: >- The slot variants this device accepts. `at` = an absolute ISO 8601 timestamp; `time` = a wall-clock `HH:mm` resolved against a schedule-level IANA `timezone`. A schedule may not mix the two. supportedRecurrence: description: >- The recurrence rules this device accepts, when `supportsRecurrence` is `true`. Absent when the device declares no recurrence support. type: array items: type: string enum: - daily - weekly minSlotDuration: description: >- The shortest slot duration this device honours, as an ISO 8601 duration (e.g. `PT15M`). Absent when the device declares no minimum. type: string required: - maxSlots - supportsRecurrence - slotVariants description: >- The device's scheduling limits (max slots, supported slot variants, recurrence support). Presence-based and published ahead of the scheduler: the whole block is absent until the device declares its scheduling capabilities. Schedules are set on the device via `PUT /{type}/{id}/schedule` (coming soon) and followed today via the `auto.schedule` command. lastAction: anyOf: - type: object properties: id: type: string description: >- Unique action identifier. Fetch the full record at `links.self`. command: type: string description: >- The canonical verb of the action (e.g. `charge`, `heat`, `auto.schedule`). Derived from the same source as `GET /actions`, so it always matches the full record. state: type: string enum: - acknowledged - completed - failed - scheduled - cancelled description: >- Lifecycle state of the action. `scheduled` indicates a deferred action awaiting its fire time; the terminal states are `completed`, `failed`, and `cancelled`. createdAt: type: string format: date-time description: ISO 8601 timestamp when the action was created. updatedAt: type: string format: date-time description: ISO 8601 timestamp of the most recent state change. errorCode: anyOf: - type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - EXECUTION_NOT_SUPPORTED - MODE_OVERRIDDEN - VPP_LOCKED - INVALID_PARAMETERS - INVALID_OEM_PARAMETERS - INVALID_TIME_WINDOW - BIND_NOT_SUPPORTED - SCHEDULER_ACTIVE - SCHEDULER_FULL - UNSUPPORTED_AUTH_PATH - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - VEHICLE_NOT_CONNECTED - SESSIONS_NOT_SUPPORTED - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - INVALID_OEM_RESPONSE - COMMAND_NOT_APPLIED - STALE_ACTION - DEFERRED_SCHEDULE_FAILED - UNROUTABLE_ACTION_TYPE - UNAUTHORIZED - EXPIRED_TOKEN - FORBIDDEN - INSUFFICIENT_PERMISSIONS - LIVE_ACCESS_DISABLED - VALIDATION_ERROR - INVALID_INPUT - INVALID_REQUEST_BODY - EMPTY_SETTINGS - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - NOT_FOUND - METHOD_NOT_ALLOWED - CONFLICT - CONFLICT_IN_EXECUTION - GONE - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - NOT_IMPLEMENTED - BAD_GATEWAY - GATEWAY_TIMEOUT - DEVICE_TYPE_MISMATCH - CONSENT_REVOKED - DEVICE_OVERAGE - SETTINGS_STORE_UNAVAILABLE - ACTION_NOT_FOUND - DIRECT_ACTION_UNSUPPORTED - UNSUPPORTED_ACTION - UNSUPPORTED_MODE - UNSUPPORTED_PARAMETER - UNSUPPORTED_PARAMETER_COMBINATION - UNSUPPORTED_UNIT - PARAMETER_OUT_OF_RANGE - START_IN_PAST - START_OUT_OF_RANGE - START_OFFSET_NOT_ACCEPTED - START_INVALID_FORMAT - START_NONEXISTENT_WALL_CLOCK - TIMEZONE_UNRESOLVED - INVALID_TIMEZONE - ACTION_NOT_CANCELLABLE - STRATEGY_NOT_SUPPORTED - UNSUPPORTED_SETTING - UNSUPPORTED_SETTING_COMBINATION - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - NO_OP - NO_OVERRIDE - AVAILABILITY_ENV_UNSUPPORTED - UNSUPPORTED_COMBINATION - type: 'null' description: >- Machine-readable error code when `state` is `failed`. Null otherwise. Lets a device card show the failure reason without fetching the full record. errorMessage: anyOf: - type: string - type: 'null' description: >- Human-readable error message when `state` is `failed`. Null otherwise. links: type: object properties: self: type: string description: >- Canonical path to the full action record: `GET /actions/{actionId}`. required: - self description: Hypermedia link to the full action record. required: - id - command - state - createdAt - updatedAt - errorCode - errorMessage - links description: >- Summary of the most recent action dispatched to this device. A pointer, not a copy: the full record (parameters, timestamps, result) is at `links.self`. - type: 'null' description: >- Summary of the most recent action dispatched to this device; full record at `links.self`. Null when the device has no actions yet. A pointer for the "render a device card in one call" case, not a denormalised copy. currentSchedule: anyOf: - type: object properties: id: type: string description: >- Unique schedule identifier. Fetch the full schedule at `links.self`. status: type: string description: >- Lifecycle status of the schedule (e.g. `active`). The full status vocabulary lands with the scheduler. links: type: object properties: self: type: string description: >- Canonical path to the device's full schedule: `GET /{type}/{id}/schedule`. required: - self description: Hypermedia link to the full schedule. required: - id - status - links description: >- Summary of the schedule currently governing this device. A pointer, not a copy: the full schedule is at `links.self`. - type: 'null' description: >- The device's active Amps schedule. Always null until the scheduler ships. required: - id - vendor - sync - metadata - state - conflictStrategies - lastAction - currentSchedule title: Battery Response description: >- Carries live `state` (status, level, capacity, charge/discharge rates), connection `metadata` and `sync` info, the device's writable `settings`, and the per-canonical-command `commands` map. The schema enumerates every canonical command, parameter, and setting because the response shape is uniform across OEMs, but capabilities are presence-based: a real device only exposes the subset its OEM declares. A field is present if the device supports it, absent if it does not. ResponseMeta: type: object title: Response Meta description: >- Metadata attached to every response: the request identifier, the serving environment, the build timestamp, and the server-side latency. required: - environment - timestamp - latencyMs properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string environment: type: string description: The environment that served the request (`sandbox` or `live`). timestamp: type: string format: date-time description: ISO 8601 timestamp when the response was built. latencyMs: type: integer description: Server-side processing time in milliseconds. ErrorResponse: type: object properties: success: type: boolean description: Always `false` for error responses. error: type: object properties: code: type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - EXECUTION_NOT_SUPPORTED - MODE_OVERRIDDEN - VPP_LOCKED - INVALID_PARAMETERS - INVALID_OEM_PARAMETERS - INVALID_TIME_WINDOW - BIND_NOT_SUPPORTED - SCHEDULER_ACTIVE - SCHEDULER_FULL - UNSUPPORTED_AUTH_PATH - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - VEHICLE_NOT_CONNECTED - SESSIONS_NOT_SUPPORTED - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - INVALID_OEM_RESPONSE - COMMAND_NOT_APPLIED - STALE_ACTION - DEFERRED_SCHEDULE_FAILED - UNROUTABLE_ACTION_TYPE - UNAUTHORIZED - EXPIRED_TOKEN - FORBIDDEN - INSUFFICIENT_PERMISSIONS - LIVE_ACCESS_DISABLED - VALIDATION_ERROR - INVALID_INPUT - INVALID_REQUEST_BODY - EMPTY_SETTINGS - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - NOT_FOUND - METHOD_NOT_ALLOWED - CONFLICT - CONFLICT_IN_EXECUTION - GONE - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - NOT_IMPLEMENTED - BAD_GATEWAY - GATEWAY_TIMEOUT - DEVICE_TYPE_MISMATCH - CONSENT_REVOKED - DEVICE_OVERAGE - SETTINGS_STORE_UNAVAILABLE - ACTION_NOT_FOUND - DIRECT_ACTION_UNSUPPORTED - UNSUPPORTED_ACTION - UNSUPPORTED_MODE - UNSUPPORTED_PARAMETER - UNSUPPORTED_PARAMETER_COMBINATION - UNSUPPORTED_UNIT - PARAMETER_OUT_OF_RANGE - START_IN_PAST - START_OUT_OF_RANGE - START_OFFSET_NOT_ACCEPTED - START_INVALID_FORMAT - START_NONEXISTENT_WALL_CLOCK - TIMEZONE_UNRESOLVED - INVALID_TIMEZONE - ACTION_NOT_CANCELLABLE - STRATEGY_NOT_SUPPORTED - UNSUPPORTED_SETTING - UNSUPPORTED_SETTING_COMBINATION - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - NO_OP - NO_OVERRIDE - AVAILABILITY_ENV_UNSUPPORTED - UNSUPPORTED_COMBINATION description: >- Machine-readable error code (e.g. `VALIDATION_ERROR`, `CONFLICT`, `UNSUPPORTED_MODE`). Stable across releases; safe to switch on. message: type: string description: Human-readable error message. details: description: >- Structured context for the error: which fields were invalid, which actions conflicted, which capabilities the device declares. Shape varies by error code. type: object properties: {} additionalProperties: {} required: - code - message description: Error envelope. meta: type: object properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string timestamp: type: string description: ISO 8601 timestamp when the error response was built. path: type: string description: Request path that produced the error. latencyMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Server-side processing time in milliseconds. required: - timestamp - path - latencyMs description: Request metadata. required: - success - error - meta title: Error Response description: >- Uniform error response. The `error.code` identifies the failure, `error.message` carries a human-readable explanation, and `error.details` carries structured context (failed fields, conflicting action IDs, supported capabilities) where relevant. securitySchemes: api-key: type: apiKey in: header name: x-api-key ````