# API Reference

## API

Define functionality for interacting with the SimpliSafe API.

class simplipy.api.API(*, request_retries: int = 4, media_retries: int = 4, session: ClientSession)

  An API object to interact with the SimpliSafe cloud.

  Note that this class shouldn’t be instantiated directly; instead, the `simplipy.api.API.async_from_auth()` and `simplipy.api.API.async_from_refresh_token()` methods should be used.

  Parameters:

    - session – session: An optional `aiohttp` `ClientSession`.

    - request_retries – The default number of request retries to use.

    - media_retries – The default number of request retries to use to fetch media files.

  async classmethod async_from_auth(authorization_code: str, code_verifier: str, *, request_retries: int = 4, session: ClientSession) → API

    Get an authenticated API object from an Authorization Code and Code Verifier.

    Parameters:

      - authorization_code – The Authorization Code.

      - code_verifier – The Code Verifier.

      - request_retries – The default number of request retries to use.

      - session – An optional `aiohttp` `ClientSession`.

    Returns:

      An authenticated API object.

    Raises:

      - InvalidCredentialsError – Raised on invalid username/password.

      - RequestError – Raised on general HTTP error.

      - SimplipyError – Raised on an unknown error.

  async classmethod async_from_refresh_token(refresh_token: str, *, request_retries: int = 4, session: ClientSession) → API

    Get an authenticated API object from a refresh token.

    Parameters:

      - refresh_token – A refresh token.

      - request_retries – The default number of request retries to use.

      - session – An optional `aiohttp` `ClientSession`.

    Returns:

      An authenticated API object.

  async async_media(url: str) → bytes | None

    Fetch a media file and return raw bytes to caller.

    Parameters:

      url – An absolute url for the media file.

    Returns:

      The raw bytes of the media file.

  static is_fatal_error(retriable_error_codes: list[int]) → Callable[[ClientResponseError], bool]

    Determine whether a ClientResponseError is fatal and shouldn’t be retried.

    When sending general API requests:

    1. 401: We catch this, refresh the access token, and retry the original request.

    2. 409: SimpliSafe base stations regular synchronize themselves with the API,

         which is where this error can occur; we can’t control when/how that happens (e.g., we might query the API in the middle of a base station update), so it should be viewed as retryable.

    But when fetching media files:

    3. 404: When fetching media files, you may get a 404 if the media file is not

         yet available to read. Keep trying however, and it will eventually return a 200.

    Parameters:

      retriable_error_codes – A list of retriable error status codes.

    Returns:

      A callable function used by backoff to check for errors.

  disable_request_retries() → None

    Disable the request retry mechanism.

  enable_request_retries() → None

    Enable the request retry mechanism.

  add_refresh_token_callback(callback: Callable[[str], Awaitable[None] | None]) → Callable[[], None]

    Add a callback that should be triggered when tokens are refreshed.

    Note that callbacks should expect to receive a refresh token as a parameter.

    Parameters:

      callback – The callback to execute.

    Returns:

      A callable to cancel the callback.

  async async_get_systems() → dict[int, SystemV2 | SystemV3]

    Get systems associated to the associated SimpliSafe account.

    In the dict that is returned, the keys are the subscription ID and the values are actual `System` objects.

    Returns:

      A dictionary of system IDs to System objects.

  async async_refresh_access_token() → None

    Initiate a refresh of the access/refresh tokens.

    Note that this will execute any callbacks added via add_refresh_token_callback.

    Raises:

      - InvalidCredentialsError – Raised on invalid username/password.

      - RequestError – Raised on general HTTP error.

      - SimplipyError – Raised on an unknown error.

  async async_update_subscription_data() → None

    Get the latest subscription data.

## Websocket Communication

class simplipy.websocket.WebsocketClient(api: API)

  A websocket connection to the SimpliSafe cloud.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_from_auth()` or `simplipy.API.async_from_refresh_token()`.

  Parameters:

    api – A simplipy API object.

  property connected: bool

    Return if currently connected to the websocket.

    Returns:

      Whether the websocket is connected.

  add_connect_callback(callback: Callable[[], Awaitable[None] | None]) → Callable[[], None]

    Add a callback to be called after connecting.

    Parameters:

      callback – The callback to execute.

    Returns:

      A callable to cancel the callback.

  add_disconnect_callback(callback: Callable[[], Awaitable[None] | None]) → Callable[[], None]

    Add a callback to be called after disconnecting.

    Parameters:

      callback – The callback to execute.

    Returns:

      A callable to cancel the callback.

  add_event_callback(callback: Callable[[WebsocketEvent], Awaitable[None] | None]) → Callable[[], None]

    Add a callback to be called upon receiving an event.

    Note that callbacks should expect to receive a WebsocketEvent object as a parameter.

    Parameters:

      callback – The callback to execute.

    Returns:

      A callable to cancel the callback.

  async async_connect() → None

    Connect to the websocket server.

    Raises:

      CannotConnectError – Raises when we cannot connect to the websocket.

  async async_disconnect() → None

    Disconnect from the websocket server.

  async async_listen() → None

    Start listening to the websocket server.

  async async_reconnect() → None

    Reconnect (and re-listen, if appropriate) to the websocket.

class simplipy.websocket.WebsocketEvent(event_cid: dataclasses.InitVar[int], info: str, system_id: int, _raw_timestamp: float, _video: dict | None, _vid: str | None, changed_by: str | None = None, sensor_name: str | None = None, sensor_serial: str | None = None, sensor_type: DeviceTypes | None = None)

  Define a representation of a message.

  event_cid: dataclasses.InitVar[int]
  info: str
  system_id: int
  event_type: str | None
  timestamp: datetime
  media_urls: dict[str, str] | None
  changed_by: str | None = None
  sensor_name: str | None = None
  sensor_serial: str | None = None
  sensor_type: DeviceTypes | None = None

## Devices

class simplipy.device.Device(system: System, device_type: DeviceTypes, serial: str)

  A base SimpliSafe device.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  Parameters:

    - system – A `simplipy.system.System()` object (or one of its subclasses).

    - device_type – The type of device represented.

    - serial – The serial number of the device.

  property name: str

    Return the device name.

    Returns:

      The device name.

  property serial: str

    Return the device’s serial number.

    Returns:

      The device serial number.

  property type: DeviceTypes

    Return the device type.

    Returns:

      The device type.

  as_dict() → dict[str, Any]

    Return dictionary version of this device.

    Returns:

      Returns a dict representation of this device.

  async async_update(cached: bool = True) → None

    Retrieve the latest state/properties for the device.

    The `cached` parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (`True`) or retrieves new data.

    Parameters:

      cached – Whether to used cached data.

class simplipy.device.DeviceTypes(*values)

  Device types based on internal SimpliSafe ID number.

  REMOTE = 0
  KEYPAD = 1
  KEYCHAIN = 2
  PANIC_BUTTON = 3
  MOTION = 4
  ENTRY = 5
  GLASS_BREAK = 6
  CARBON_MONOXIDE = 7
  SMOKE = 8
  LEAK = 9
  TEMPERATURE = 10
  CAMERA = 12
  SIREN = 13
  SMOKE_AND_CARBON_MONOXIDE = 14
  DOORBELL = 15
  LOCK = 16
  OUTDOOR_CAMERA = 17
  MOTION_V2 = 20
  OUTDOOR_ALARM_SECURITY_BELL_BOX = 22
  LOCK_KEYPAD = 253
  UNKNOWN = 99

class simplipy.device.DeviceV3(system: System, device_type: DeviceTypes, serial: str)

  A base device for V3 systems.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  property error: bool

    Return the device’s error status.

    Returns:

      The device’s error status.

  property low_battery: bool

    Return whether the device’s battery is low.

    Returns:

      The device’s low battery status.

  property offline: bool

    Return whether the device is offline.

    Returns:

      The device’s offline status.

  property settings: dict[str, Any]

    Return the device’s settings.

    Note that these can change based on what device type the device is.

    Returns:

      A settings dictionary.

  as_dict() → dict[str, Any]

    Return dictionary version of this device.

    Returns:

      A dict representation of this device.

## Lock

class simplipy.device.lock.Lock(request: Callable[..., Awaitable[dict[str, Any]]], system: System, device_type: DeviceTypes, serial: str)

  A lock that works with V3 systems.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  Parameters:

    - request – The request method from the `simplipy.API()` object.

    - system – A `simplipy.system.System()` object (or one of its subclasses).

    - device_type – The type of device represented.

    - serial – The serial number of the device.

  property disabled: bool

    Return whether the lock is disabled.

    Returns:

      The lock’s disable status.

  property lock_low_battery: bool

    Return whether the lock’s battery is low.

    Returns:

      The lock’s low battery status.

  property pin_pad_low_battery: bool

    Return whether the pin pad’s battery is low.

    Returns:

      The pinpad’s low battery status.

  property pin_pad_offline: bool

    Return whether the pin pad is offline.

    Returns:

      The pinpad’s offline status.

  property state: LockStates

    Return the current state of the lock.

    Returns:

      The lock’s state.

  as_dict() → dict[str, Any]

    Return dictionary version of this device.

    Returns:

      A dict representation of this device.

  async async_lock() → None

    Lock the lock.

  async async_unlock() → None

    Unlock the lock.

class simplipy.device.lock.LockStates(*values)

  States that a lock can be in.

  UNLOCKED = 0
  LOCKED = 1
  JAMMED = 2
  UNKNOWN = 99

## Sensors

class simplipy.device.sensor.v2.SensorV2(system: System, device_type: DeviceTypes, serial: str)

  A V2 (old) sensor.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  property data: int

    Return the sensor’s current data flag (currently not understood).

    Returns:

      The current data flag.

  property error: bool

    Return the sensor’s error status.

    Returns:

      The current error status.

  property low_battery: bool

    Return whether the sensor’s battery is low.

    Returns:

      The current low battery status.

  property settings: bool

    Return the sensor’s settings.

    Returns:

      The current settings.

  property trigger_instantly: bool

    Return whether the sensor will trigger instantly.

    Returns:

      The “instant trigger” settings.

  property triggered: bool

    Return whether the sensor has been triggered.

    Returns:

      The triggered status.

    Raises:

      SimplipyError – Raised when the state can’t be determined.

class simplipy.device.sensor.v3.SensorV3(system: System, device_type: DeviceTypes, serial: str)

  A V3 (new) sensor.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  property trigger_instantly: bool

    Return whether the sensor will trigger instantly.

    Returns:

      The “instant trigger” status.

  property triggered: bool

    Return whether the sensor has been triggered.

    Returns:

      The triggered status.

  property temperature: int

    Return the temperature of the sensor (as appropriate).

    If the sensor isn’t a temperature sensor, an `AttributeError` will be raised.

    Returns:

      The temperature.

    Raises:

      AttributeError – Raised when property is read on a non-temperature device.

  as_dict() → dict[str, Any]

    Return dictionary version of this device.

    Returns:

      A dict representation of this device.

## Systems

class simplipy.system.System(api: API, sid: int)

  Define a system.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  Parameters:

    - api – A `simplipy.API()` object.

    - sid – A subscription ID.

  property address: str | None

    Return the street address of the system.

    Returns:

      The street address.

  property alarm_going_off: bool

    Return whether the alarm is going off.

    Returns:

      Whether the alarm is going off.

  property connection_type: str | None

    Return the system’s connection type (cell or WiFi).

    Returns:

      The connection type.

  property notifications: list[SystemNotification]

    Return the system’s current messages/notifications.

    Returns:

      A list of `simplipy.system.SystemNotification()` objects.

  property serial: str

    Return the system’s serial number.

    Returns:

      The system serial number.

  property state: SystemStates

    Return the current state of the system.

    Returns:

      The system state.

  property system_id: int

    Return the SimpliSafe identifier for this system.

    Returns:

      The system ID.

  property temperature: int | None

    Return the overall temperature measured by the system.

    Returns:

      The average system temperature.

  property version: int | None

    Return the system version.

    Returns:

      The system version.

  as_dict() → dict[str, Any]

    Return dictionary version of this device.

    Returns:

      A dict representation of this device.

  async async_clear_notifications() → None

    Clear all active notifications.

    This will remove the notifications from SimpliSafe’s cloud, meaning they will no longer visible in the SimpliSafe mobile and web apps.

  generate_device_objects() → None

    Generate device objects for this system.

    Raises:

      NotImplementedError – Raises when not implemented.

  async async_get_events(from_datetime: datetime | None = None, num_events: int | None = None) → list[dict[str, Any]]

    Get events recorded by the base station.

    If no parameters are provided, this will return the most recent 50 events.

    Parameters:

      - from_datetime – The starting datetime (if desired).

      - num_events – The number of events to return.

    Returns:

      An API response payload.

  async async_get_latest_event() → dict[str, Any]

    Get the most recent system event.

    Returns:

      An API response payload.

    Raises:

      SimplipyError – Raised when there are no events.

  async async_get_pins(cached: bool = True) → dict[str, str]

    Return all of the set PINs, including master and duress.

    The `cached` parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (`True`) or retrieves new data.

    Parameters:

      cached – Whether to used cached data.

    Raises:

      NotImplementedError – Raises when not implemented.

  async async_remove_pin(pin_or_label: str) → None

    Remove a PIN by its value or label.

    Parameters:

      pin_or_label – The PIN value or label to remove.

    Raises:

      PinError – Raised when attempting to remove a PIN that doesn’t exist.

  async async_set_away() → None

    Set the system in “Away” mode.

  async async_set_home() → None

    Set the system in “Home” mode.

  async async_set_off() → None

    Set the system in “Off” mode.

  async async_set_pin(label: str, pin: str) → None

    Set a PIN.

    Parameters:

      - label – The label to use for the PIN (shown in the SimpliSafe app).

      - pin – The pin value.

    Raises:

      - MaxUserPinsExceededError – Raised when attempting to add more than the maximum number of user PINs.

      - PinError – Raised when setting an invalid PIN.

  async async_update(*, include_subscription: bool = True, include_settings: bool = True, include_devices: bool = True, cached: bool = True) → None

    Get the latest system data.

    The `cached` parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (`True`) or retrieves new data.

    Parameters:

      - include_subscription – Whether system state/properties should be updated.

      - include_settings – Whether system settings (like PINs) should be updated.

      - include_devices – whether sensors/locks/etc. should be updated.

      - cached – Whether to used cached data.

class simplipy.system.v2.SystemV2(api: API, sid: int)

  Define a V2 (original) system.

  generate_device_objects() → None

    Generate device objects for this system.

  async async_get_pins(cached: bool = True) → dict[str, str]

    Return all of the set PINs, including master and duress.

    The `cached` parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (`True`) or retrieves new data.

    Parameters:

      cached – Whether to update with cached data.

    Returns:

      A dictionary of PINs.

class simplipy.system.v3.SystemV3(api: API, system_id: int)

  Define a V3 (new) system.

  Note that this class shouldn’t be instantiated directly; it will be instantiated as appropriate via `simplipy.API.async_get_systems()`.

  Parameters:

    - api – A `simplipy.API()` object.

    - sid – A subscription ID.

  property alarm_duration: int | None

    Return the number of seconds an activated alarm will sound for.

    Returns:

      The alarm duration.

  property alarm_volume: Volume

    Return the volume level of the alarm.

    Returns:

      The alarm volume.

  property battery_backup_power_level: int

    Return the power rating of the battery backup.

    Returns:

      The battery backup power rating.

  property chime_volume: Volume

    Return the volume level of the door chime.

    Returns:

      The door chime volume.

  property entry_delay_away: int

    Return the number of seconds to delay when returning to an “away” alarm.

    Returns:

      The entry delay when returning to an “away” alarm.

  property entry_delay_home: int

    Return the number of seconds to delay when returning to a “home” alarm.

    Returns:

      The entry delay when returning to a “home” alarm.

  property exit_delay_away: int

    Return the number of seconds to delay when exiting an “away” alarm.

    Returns:

      The exit delay when exiting an “away” alarm.

  property exit_delay_home: int

    Return the number of seconds to delay when exiting an “home” alarm.

    Returns:

      The exit delay when exiting a “home” alarm.

  property gsm_strength: int

    Return the signal strength of the cell antenna.

    Returns:

      The cell antenna strength.

  property light: bool

    Return whether the base station light is on.

    Returns:

      The light status.

  property offline: bool

    Return whether the system is offline.

    Returns:

      The offline status.

  property power_outage: bool

    Return whether the system is experiencing a power outage.

    Returns:

      The power outage status.

  property rf_jamming: bool

    Return whether the base station is noticing RF jamming.

    Returns:

      The RF jamming status.

  property voice_prompt_volume: Volume

    Return the volume level of the voice prompt.

    Returns:

      The voice prompt volume.

  property wall_power_level: int

    Return the power rating of the A/C outlet.

    Returns:

      The A/C power rating.

  property wifi_ssid: str

    Return the ssid of the base station.

    Returns:

      The connected SSID.

  property wifi_strength: int

    Return the signal strength of the wifi antenna.

    Returns:

      The WiFi strength.

  as_dict() → dict[str, Any]

    Return dictionary version of this device.

    Returns:

      A dict representation of this device.

  generate_device_objects() → None

    Generate device objects for this system.

  async async_get_pins(cached: bool = True) → dict[str, str]

    Return all of the set PINs, including master and duress.

    The `cached` parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (`True`) or retrieves new data.

    Parameters:

      cached – Whether to update with cached data.

    Returns:

      A dictionary of PINs.

  async async_set_properties(properties: dict[str, bool | int | Volume]) → None

    Set various system properties.

    Volume properties should take values from `simplipy.system.v3.Volume()`.

    The following properties can be set:

      1. alarm_duration (in seconds): 30-480

      2. alarm_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH

      3. chime_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH

      4. entry_delay_away (in seconds): 30-255

      5. entry_delay_home (in seconds): 0-255

      6. exit_delay_away (in seconds): 45-255

      7. exit_delay_home (in seconds): 0-255

      8. light: True or False

      9. voice_prompt_volume: Volume.OFF, Volume.LOW, Volume.MEDIUM, Volume.HIGH

    Parameters:

      properties – The system properties to set.

    Raises:

      ValueError – Raised on invalid properties.

  async async_update(*, include_subscription: bool = True, include_settings: bool = True, include_devices: bool = True, cached: bool = True) → None

    Get the latest system data.

    The `cached` parameter determines whether the SimpliSafe Cloud uses the last known values retrieved from the base station (`True`) or retrieves new data.

    Parameters:

      - include_subscription – Whether system state/properties should be updated.

      - include_settings – Whether system settings (like PINs) should be updated.

      - include_devices – whether sensors/locks/etc. should be updated.

      - cached – Whether to used cached data.

class simplipy.system.SystemNotification(notification_id: str, text: str, category: str, code: str, timestamp: float, link: str | None = None, link_label: str | None = None)

  Define a representation of a system notification.

  notification_id: str
  text: str
  category: str
  code: str
  timestamp: float
  received_dt: datetime | None
  link: str | None = None
  link_label: str | None = None

class simplipy.system.SystemStates(*values)

  States that the system can be in.

  ALARM = 1
  ALARM_COUNT = 2
  AWAY = 3
  AWAY_COUNT = 4
  ENTRY_DELAY = 5
  ERROR = 6
  EXIT_DELAY = 7
  HOME = 8
  HOME_COUNT = 9
  OFF = 10
  TEST = 11
  UNKNOWN = 99

## Utilities

Define utility modules.

simplipy.util.execute_callback(callback: Callable[[...], Awaitable[None] | None], *args: Any) → None

  Schedule a callback to be called.

  The callback is expected to be short-lived, as no sort of task management takes place – this is a fire-and-forget system.

  Parameters:

    - callback – The callback to execute.

    - *args – Any arguments to pass to the callback.

### `auth`

Define some utilities to work with SimpliSafe’s authentication mechanism.

simplipy.util.auth.get_auth_url(code_challenge: str, *, device_id: str | None = None) → str

  Get a SimpliSafe authorization URL to visit in a browser.

  Parameters:

    - code_challenge – A code challenge generated by `simplipy.util.auth.get_auth0_code_challenge()`.

    - device_id – A UUID to identify the device getting the auth URL. If not provided, a random UUID will be generated.

  Returns:

    An authorization URL.

simplipy.util.auth.get_auth0_code_challenge(code_verifier: str) → str

  Get an Auth0 code challenge from a code verifier.

  Parameters:

    code_verifier – A code challenge generated by `simplipy.util.auth.get_auth0_code_verifier()`.

  Returns:

    A code challenge.

simplipy.util.auth.get_auth0_code_verifier() → str

  Get an Auth0 code verifier.

  Returns:

    A code verifier.

### `dt`

Define datetime utilities.

simplipy.util.dt.utcnow() → datetime

  Return the current UTC time.

  Returns:

    A `datetime.datetime` object.

simplipy.util.dt.utc_from_timestamp(timestamp: float) → datetime

  Return a UTC time from a timestamp.

  Parameters:

    timestamp – The epoch to convert.

  Returns:

    A parsed `datetime.datetime` object.

### `string`

Define various string utilities.

simplipy.util.string.convert_to_underscore(string: str) → str

  Convert thisString to this_string.

  Parameters:

    string – The string to convert.

  Returns:

    A converted string.

## Errors

Define package errors.

exception simplipy.errors.SimplipyError

  A base error.

exception simplipy.errors.EndpointUnavailableError

  An error related to accessing an endpoint that isn’t available in the plan.

exception simplipy.errors.InvalidCredentialsError

  An error related to invalid credentials.

exception simplipy.errors.MaxUserPinsExceededError

  An error related to exceeding the maximum number of user PINs.

exception simplipy.errors.PinError

  An error related to invalid PINs or PIN operations.

exception simplipy.errors.RequestError

  An error related to invalid requests.

exception simplipy.errors.WebsocketError

  An error related to generic websocket errors.

exception simplipy.errors.CannotConnectError

  Define a error when the websocket can’t be connected to.

exception simplipy.errors.ConnectionClosedError

  Define a error when the websocket closes unexpectedly.

exception simplipy.errors.ConnectionFailedError

  Define a error when the websocket connection fails.

exception simplipy.errors.InvalidMessageError

  Define a error related to an invalid message from the websocket server.

exception simplipy.errors.NotConnectedError

  Define a error when the websocket isn’t properly connected to.

simplipy.errors.raise_on_data_error(data: dict[str, Any] | None) → None

  Raise a specific error if the data payload suggests there is one.

  Parameters:

    data – An optional API response payload.

  Raises:

    error – A SimplipyError subclass.