Object Models

The Cumulocity Python SDK's object model provides object-oriented access to the Cumulocity REST API. Use it to create and modify single objects within the Database.

Object-oriented database access

The object model define functions for direct, object-oriented database access:

# Create an object in the database and use it
obj = ManagedObject(
    connection,
    name="MyObject",
    type="my_CustomType"
)
obj = await obj.create()

# Update the object and write changes to the database
obj.type = "my_ChangedType"  
await obj.update()

# Remove the previously created object from the database
await obj.delete()

Note: These objects can also be used directly within the Main API classes to modify data in bulk.

Direct JSON data access

The object model instances are essentially enriched JSON-like objects and can be used like standard nested dictionaries:

the_value = obj["my_Fragment"]["value"]  # read nested value
obj["my_Fragment"]["value"] = new_value  # set nested value

For convenience the SDK supports dot-notation for the [] operator:

the_value = obj["my_Fragment.value"]  # read nested value
obj["my_Fragment.value"] = new_Value  # set nested value

Likewise, the .get and .set functions:

the_value = obj.get("my_Fragment.value", default=42)  # read nested value
obj.set("my_Fragment.value", 42)  # set a nested value

which also protect against missing keys along the path.

Many Cumulocity objects define standard properties, e.g. id, type, name and creationTime. These fields can additionally also read (and set if allowed) through explicit class properties:

# Most objects have an id, name, and type
print(f"Object details: #{obj.id}, '{obj.name}' ({obj.type})")

# Date-like properties can be read as strings (actual JSON value) or datetime (parsed)
total_minutes = int((datetime.now(timezone.utc) - obj.creation_datetime).total_seconds() / 60)
print(f"Object creation: {obj.creation_time} ({total_minutes} minutes ago)")

These properties use Pythonic snake_case naming to integrate nicely into Python code. The original data is always available through direct access, e.g. obj["creationTime"].

---

ManagedObject

Represent a managed object within the database.

Instances of this class are returned by functions of the corresponding Inventory API. Use this class to create new or update managed objects.

See also https://cumulocity.com/guides/reference/inventory/#managed-object

__init__(c8y: CumulocityRestClient | None = None, type: str | None = None, name: str | None = None, owner: str | None = None, **kwargs)

Create a new ManagedObject instance.

Custom fragments can be added to the object using kwargs or after creation using += or [] syntax.

Parameters:

Name	Type	Description	Default
c8y	CumulocityRestClient	Cumulocity connection reference; needs to be set for direct manipulation (create, delete)	None
type	str	ManagedObject type	None
name	str	ManagedObject name	None
owner	str	User ID of the owning user (can be left None to automatically assign to the connection user upon creation)	None
kwargs		Additional arguments are treated as custom fragments	{}

Returns:

Type	Description
	ManagedObject instance

apply(json: dict, copy: bool = False) -> Self async

Apply a JSON model to this object.

Parameters:

Name	Type	Description	Default
json	dict	A JSON document to apply	required
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated ManagedObject. By default, this is self; if copy=True,
Self	a fresh instance.

apply_to(other_id: str) -> Self async

Apply the details of this object to another object in the database.

Note: This will take the full details, not just the updates.

Parameters:

Name	Type	Description	Default
other_id	str	Database ID of the event to update.	required

Returns: A fresh ManagedObject instance representing the updated object within the database.

See also function Inventory.apply_to which doesn't parse the result.

assign_child_addition(child: Self | str) async

Link a child addition to this managed object.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str	Child addition or its object ID	required

assign_child_asset(child: Self | str) async

Link a child asset to this managed object.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str	Child asset or its object ID	required

assign_child_device(child: Self | str) async

Link a child device to this managed object.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str	Child device or its object ID	required

create() -> Self async

Create a new representation of this object within the database.

This function can be called multiple times to create multiple instances of this object with different ID.

Returns:

Type	Description
Self	A fresh ManagedObject instance representing the created
Self	object within the database. This instance can be used to get
Self	at the ID of the new managed object.

See also function Inventory.create which doesn't parse the result.

delete(**_) -> None async

Delete this object within the database.

Note: child additions, assets (and devices) are not implicitly deleted. The database ID must be defined for this to function.

See also function Inventory.delete to delete multiple objects.

delete_tree() -> None async

Delete this managed object within the database including child. additions, devices and assets. This is equivalent to using the forceCascade parameter of the Cumulocity REST API.

The database ID must be defined for this to function.

See also function DeviceInventory.delete_trees to delete multiple objects.

get_latest_availability() -> Availability async

Retrieve the latest availability information of this object.

Return

DeviceAvailability object

get_supported_measurements() -> list[str] async

Retrieve all supported measurement names of this managed object.

Return

List of measurement fragment names.

get_supported_series() -> list[str] async

Retrieve all supported measurement series names of this managed object.

Return

List of measurement series names.

reload(copy: bool = False) -> Self async

Reload this object's data from database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The reloaded ManagedObject. By default this is self; if copy=True,
Self	a fresh instance.

unassign_child_addition(child: Self | str) async

Remove the link to a child addition.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str	Child device or its object ID	required

unassign_child_asset(child: Self | str) async

Remove the link to a child asset.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str	Child device or its object ID	required

unassign_child_device(child: Self | str) async

Remove the link to a child device.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str	Child device or its object ID	required

update(copy: bool = False) -> Self async

Write changes to the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated ManagedObject. By default this is self; if copy=True,
Self	a fresh instance.

See also function Inventory.update which doesn't parse the result.

Device

Represent an instance of a Device object within Cumulocity.

Instances of this class are returned by functions of the corresponding DeviceInventory API. Use this class to create new or update Device objects.

Device objects are regular managed objects with additional standardized fragments and fields.

See also https://cumulocity.com/guides/reference/inventory/#managed-object https://cumulocity.com/guides/reference/device-management/

__init__(c8y: CumulocityRestClient | None = None, type: str | None = None, name: str | None = None, owner: str | None = None, **kwargs)

Create a new Device instance.

A Device object will always have a c8y_IsDevice fragment. Additional custom fragments can be added using kwargs or after creation, using += or [] syntax.

Parameters:

Name	Type	Description	Default
c8y	CumulocityRestClient	Cumulocity connection reference; needs to be set for direct manipulation (create, delete)	None
type	str	Device type	None
name	str	Device name	None
owner	str	User ID of the owning user (can be left None to automatically assign to the connection user upon creation)	None
kwargs		Additional arguments are treated as custom fragments	{}

Returns:

Type	Description
	Device instance

delete(with_device_user=False, **_) -> None async

Delete this device object within the database.

Note: child additions, assets (and devices) are not implicitly deleted. The database ID must be defined for this to function.

Parameters:

Name	Type	Description	Default
with_device_user	bool	Whether the device user is deleted as well.	False

See also function DeviceInventory.delete to delete multiple objects.

delete_tree(with_device_user=False) -> None async

Delete this device object within the database including child. additions, devices and assets.

The database ID must be defined for this to function.

Parameters:

Name	Type	Description	Default
with_device_user	bool	Whether the device user is deleted as well.	False

See also function DeviceInventory.delete to delete multiple objects.

get_user() -> User async

Return the device user.

Returns:

Type	Description
User	Device's user.

get_username() -> str

Return the device username.

Returns:

Type	Description
str	Username of the device's user.

DeviceGroup

Represent a device group within Cumulocity.

Instances of this class are returned by functions of the corresponding DeviceGroupInventory API. Use this class to create new or update DeviceGroup objects.

DeviceGroup objects are regular managed objects with additional standardized fragments and fields.

See also https://cumulocity.com/guides/reference/inventory/#managed-object https://cumulocity.com/guides/users-guide/device-management/#grouping-devices

__init__(c8y=None, root: bool = False, name: str | None = None, owner: str | None = None, **kwargs)

Build a new DeviceGroup object.

The type of a device group will always be either c8y_DeviceGroup or c8y_DeviceSubGroup (depending on it's level). This is handled by the API.

A DeviceGroup object will always have a c8y_IsDeviceGroup fragment. Additional custom fragments can be added using kwargs or after creation, using += or [] syntax.

Parameters:

Name	Type	Description	Default
c8y	CumulocityRestClient	Cumulocity connection reference; needs to be set for direct manipulation (create, delete)	None
root	bool	Whether the group is a root group (default is False)	False
name	str	Device name	None
owner	str	User ID of the owning user (can be left None to automatically assign to the connection user upon creation)	None
kwargs		Additional arguments are treated as custom fragments	{}

Returns:

Type	Description
	DeviceGroup instance

assign_child_group(child: Self | str) async

Link a child group to this device group.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	DeviceGroup | str	Child device or its object ID	required

create() -> Self async

Create a new representation of this object within the database.

This operation will create the group and all added child groups within the database.

:returns: A fresh DeviceGroup instance representing the created object within the database. This instance can be used to get at the ID of the new object.

See also function DeviceGroupInventory.create which doesn't parse the result.

create_child(name: str, owner: str | None = None, **kwargs) -> Self async

Create and assign a child group.

This change is written to the database immediately.

Parameters:

Name	Type	Description	Default
name	str	Device name	required
owner	str	User ID of the owning user (can be left None to automatically assign to the connection user upon creation)	None
kwargs		Additional arguments are treated as custom fragments	{}

Returns:

Type	Description
Self	The newly created DeviceGroup object

delete(**_) -> None async

Delete this device group.

The child groups (if there are any) are left dangling. This is equivalent to using the cascade=false parameter in the Cumulocity REST API.

delete_tree() -> None async

Delete this device group and its children.

This is equivalent to using the cascade=true parameter in the Cumulocity REST API.

unassign_child_group(child: Self | str) async

Remove the link to a child group.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	DeviceGroup | str	Child device or its object ID	required

update(copy: bool = False, **_) -> Self async

Write changed to the database.

Note: Removing child groups is currently not supported.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

:returns: The updated DeviceGroup. By default this is self; if copy=True, a fresh instance.

ExternalId

Represents an ExternalID in Cumulocity.

Instances of this class are returned by functions of the corresponding Identity API. Use this class to create or remove external IDs.

See also: https://cumulocity.com/api/core/#tag/External-IDs

__init__(c8y: CumulocityRestClient | None = None, *, external_id: str | None = None, external_type: str | None = None, managed_object_id: str | None = None)

create() -> Self async

Store the external ID in the database.

Returns:

Type	Description
Self	Self reference.

delete() -> None async

Remove the external ID from the database.

get_object() async

Read the referenced managed object from the database.

Returns:

Type	Description
	ManagedObject instance

Binary

Represents a binary object/file within the Database.

See also: https://cumulocity.com/api/core/#tag/Binaries

__init__(c8y: CumulocityRestClient | None = None, *, type: str | None = None, name: str | None = None, owner: str | None = None, content_type: str | None = None, file: FileSpec | None = None, **kwargs)

create() -> Self async

Create a new binary within the database by uploading the file.

Returns:

Type	Description
Self	A fresh Binary instance representing the created object.

Raises:

Type	Description
FileNotFoundError	if the file attribute refers to an invalid path

from_json(json: dict, c8y: CumulocityRestClient | None = None) -> Self classmethod

read_file() -> bytes async

Read the content of the binary attachment.

Returns:

Type	Description
bytes	The binary attachment's content as bytes

update(copy: bool = False) -> Self async

Update the binary attachment.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated Binary. By default this is self; if copy=True,
Self	a fresh instance.

Raises:

Type	Description
FileNotFoundError	if the file attribute refers to an invalid path

Measurement

__init__(c8y: CumulocityRestClient | None = None, *, type: str | None = None, source: str | None = None, time: str | datetime | None = None, series: SeriesValue | Iterable[SeriesValue] | None = None, **kwargs)

Create a new Measurement object.

Parameters:

Name	Type	Description	Default
time	str | datetime	Datetime string or Python datetime object. A given datetime string needs to be in standard ISO format incl. timezone: YYYY-MM-DD'T'HH:MM:SS.SSSZ as it is returned by the Cumulocity REST API. A given datetime object needs to be timezone aware. For manual construction it is recommended to specify a datetime object as the formatting of a timestring is never checked for performance reasons.	None
kwargs		All additional named arguments are interpreted as custom fragments e.g. for data points.	{}

Returns:

Type	Description
	Measurement object

create() -> Self async

Store the Measurement within the database.

A fresh Measurement object representing what was

Type	Description
Self	created within the database (including the ID).

get_series() -> Sequence[str]

Collect series names.

Collect series names defined in this measurement. Any top level fragment having a nested element featuring a value field is considered a series. Multiple such series could be defined.

{
    "c8y_Temperature": {
        "T": {
            "unit": "C",
            "value": 12.8
        }
    }
}

Returns:

Type	Description
Sequence[str]	A list of series names (e.g. c8y_Temperature.T) defined in this measurement.

Event

Represent an instance of an event object in Cumulocity.

Instances of this class are returned by functions of the corresponding Events API. Use this class to create new or update Event objects.

See also: https://cumulocity.com/api/#tag/Events

__init__(c8y: CumulocityRestClient | None = None, type: str | None = None, time: str | datetime | None = None, source: str | None = None, text: str | None = None, **kwargs)

apply_to(other_id: str) -> Self async

Apply changes made to this event to another event in the database.

Parameters:

Name	Type	Description	Default
other_id	str	Database ID of the event to update.	required

Returns:

Type	Description
Self	A fresh Event instance representing the updated state.

create() -> Self async

Create this event within the database.

Returns:

Type	Description
Self	A fresh Event instance representing what was created (including the ID).

create_attachment(file: FileSpec, content_type: str | None = None) -> dict async

Create the binary attachment.

Parameters:

Name	Type	Description	Default
file	str | PathLike | BinaryIO	File-like object or a file path	required
content_type	str	Content type of the file sent (default is application/octet-stream)	None

Returns:

Type	Description
dict	Attachment details as JSON object (dict).

delete(**_) -> None async

Delete this event from the database.

delete_attachment() -> None async

Remove the binary attachment.

download_attachment() -> bytes async

Read the binary attachment.

Returns:

Type	Description
bytes	The event's binary attachment as bytes.

has_attachment() -> bool

Check whether the event has a binary attachment.

Event objects that have an attachment feature a c8y_IsBinary fragment. This function checks the presence of that fragment.

Note: This does not query the database. Hence, the information might be outdated if a binary was attached after the event object was last read from the database.

Returns:

Type	Description
bool	True if the event object has an attachment, False otherwise.

reload(copy: bool = False) -> Self async

Reload this event's data from the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The reloaded Event. By default this is self; if copy=True,
Self	a fresh instance.

update(copy: bool = False) -> Self async

Write changes to this event to the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated Event. By default this is self; if copy=True,
Self	a fresh instance.

update_attachment(file: FileSpec, content_type: str | None = None) -> dict async

Update the binary attachment.

Parameters:

Name	Type	Description	Default
file	str | PathLike | BinaryIO	File-like object or a file path	required
content_type	str	Content type of the file sent (default is application/octet-stream)	None

Returns:

Type	Description
dict	Attachment details as JSON object (dict).

Alarm

Represent an instance of an event object in Cumulocity.

Instances of this class are returned by functions of the corresponding Events API. Use this class to create new or update Event objects.

See also: https://cumulocity.com/api/#tag/Events

__init__(c8y: CumulocityRestClient | None = None, *, type: str | None = None, time: str | datetime | None = None, source: str | None = None, text: str | None = None, status: AlarmStatus | str | None = None, severity: AlarmSeverity | str | None = None, **kwargs)

apply_to(other_id: str) -> Self async

Apply changes made to this object to another object in the database.

Parameters:

Name	Type	Description	Default
other_id	str	Database ID of the object to update.	required

Returns:

Type	Description
Self	A fresh object representing the updated object's state within
Self	the database.

create() async

delete(**_) -> None async

Delete this object within the database.

An alarm is identified through its type and source. These fields must be defined for this to function. This is always the case if the instance was built by the API.

See also functions Alarms.delete and Alarms.delete_by

update(copy: bool = False) -> Self async

Update the object within the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated Alarm. By default this is self; if copy=True,
Self	a fresh instance.

Series

A wrapper for a series result.

See also: Measurements.get_series function

This class wraps the raw JSON result but can also be used to read result specs and collect result values conveniently.

See also: https://cumulocity.com/api/core/#operation/getMeasurementSeriesResource

collect(series: str | Sequence[str] | None = None, value: str | Sequence[str] | None = None, timestamps: bool | str | None = None) -> list[tuple]

Collect series results as a list of flat tuples.

Each row corresponds to one timestamp and always carries a tuple of uniform length: (len(series) * len(value_keys)), optionally prefixed with the timestamp. Column order is series-major (s0_v0, s0_v1, ..., s1_v0, s1_v1, ...). Missing values appear as None.

Use values_of instead if you just want a flat list of values for a single (series, value) combination.

Parameters:

Name	Type	Description	Default
series	str | Sequence[str]	Series name or names. If omitted, all series are collected.	None
value	str | Sequence[str]	Value key or list of keys (e.g. 'min', 'max'). If omitted, all available value keys are collected.	None
timestamps	bool | str	If truthy, each tuple is prefixed with the corresponding timestamp. Use True for the raw string, 'datetime' for parsed datetimes, 'epoch' for epoch seconds.	None

Returns:

Type	Description
list[tuple]	A list of tuples. Example shapes: - 1 series, value='min' -> [(min,), ...] - 1 series, value=['min','max'], ts=True -> [(ts, min, max), ...] - 2 series, value='min' -> [(A_v, B_v), ...] - 2 series, value=['min','max'] -> [(A_min, A_max, B_min, B_max), ...]

to_dataframe(series: str | Sequence[str] | None = None, value: str | Sequence[str] | None = None, timestamps: bool | str | None = None)

Build a Pandas DataFrame from this Series object.

All timestamps are included as rows; missing values for a series at a given timestamp are represented as NaN.

Parameters:

Name	Type	Description	Default
series	str | list	A series name or list of series names; defaults to all available series. Names are used as column names (special characters replaced with underscores).	None
value	str | list	Value key or list of value keys to extract (e.g. 'min', 'max', or ['min', 'max']); if omitted all available value keys are extracted. Column names are suffixed with the value key when multiple values are extracted.	None
timestamps	bool | str	Use timestamps as the DataFrame index; use True for raw strings, 'datetime' for parsed datetimes, or 'epoch' for epoch floats.	None

Returns:

Type	Description
	A Pandas DataFrame.

to_numpy(series: str | None = None, value: str | None = None)

Build a NumPy array from a single series and value.

All available data points/timestamps are included in the result. Missing values are represented as NaN, preserving alignment with other series extracted from the same object.

Parameters:

Name	Type	Description	Default
series	str	Series name (e.g. 'c8y_Temperature.T'); can be omitted if this object holds only one series.	None
value	str	Value key to extract (e.g. 'min' or 'max'); can be omitted if the series holds only one value.	None

Returns:

Type	Description
	A 1-dimensional NumPy array.

to_series and to_dataframe to convert multiple series

and/or values into a Pandas Series/DataFrame optionally using the timestamps as index.

to_series(series: str | None = None, value: str = 'min', timestamps: bool | str | None = None)

Build a Pandas Series from a single Cumulocity series.

All timestamps are included; missing values are represented as NaN.

Parameters:

Name	Type	Description	Default
series	str	Series name; can be omitted if this object holds only one series.	None
value	str	Value key to extract; defaults to 'min'.	'min'
timestamps	bool | str	Use timestamps as the index; use True for raw strings, 'datetime' for parsed datetimes, or 'epoch' for epoch floats.	None

Returns:

Type	Description
	A Pandas Series.

values_of(series: str | None = None, value: str | None = None) -> list[float]

Return a flat list of actual values for one series and one value key.

Rows where the series has no value (or the value key is missing) are skipped; the result is therefore not aligned with .values.keys(). Use collect(timestamps=...) if you need alignment.

Parameters:

Name	Type	Description	Default
series	str	Series name (e.g. 'c8y_Temperature.T'). Can be omitted if this object holds exactly one series.	None
value	str	Value key (e.g. 'min', 'max'). Can be omitted if the series holds exactly one value key.	None

Returns:

Type	Description
list[float]	A list of floats; None entries are filtered out.

Subscription

Represents a Notification 2.0 subscription within the database.

Instances of this class are returned by functions of the corresponding Subscriptions API. Use this class to create new subscriptions.

See also: https://cumulocity.com/api/core/#tag/Subscriptions

ApiFilter

Notification API filter types.

Context

Notification context types.

__init__(c8y: CumulocityRestClient | None = None, *, name: str | None = None, context: str | None = None, source_id: str | None = None, api_filter: list[str] | None = None, type_filter: str | None = None, fragments: list[str] | None = None, non_persistent: bool | None = None)

create() -> Self async

Create a new subscription within the database.

Returns:

Type	Description
Self	A fresh Subscription instance representing the created subscription.

from_json(json: dict, c8y: CumulocityRestClient | None = None) -> Self classmethod

Availability

Cumulocity availability status labels

ConnectionStatus

Connection status labels

DataStatus

Data status labels

User

Represents a User object within Cumulocity.

assign_global_role(group_id: int | str) -> None async

Assign a global role (user group) to this user.

Parameters:

Name	Type	Description	Default
group_id	int | str	ID of an existing user group	required

assign_inventory_roles(managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment async

Assign inventory roles for a managed object to this user.

Parameters:

Name	Type	Description	Default
managed_object_id	str | int	ID of the managed object (e.g. device group)	required
*roles	InventoryRole | int | str	Role objects or IDs to assign	()

Returns:

Type	Description
InventoryRoleAssignment	The created InventoryRoleAssignment

create() -> Self async

Create the User within the database.

Returns:

Type	Description
Self	A fresh User object representing what was
Self	created within the database (including the ID).

delete() -> None async

Delete this user from the database.

retrieve_global_roles() -> list[UserGroup] async

Retrieve the user's assigned global roles.

Returns:

Type	Description
list[UserGroup]	List of assigned UserGroup instances.

retrieve_inventory_role_assignments() -> list[InventoryRoleAssignment] async

Retrieve the user's inventory role assignments.

Returns:

Type	Description
list[InventoryRoleAssignment]	List of InventoryRoleAssignment instances.

set_delegate(user_id: str) -> None async

Set the delegate for this user.

Parameters:

Name	Type	Description	Default
user_id	str	ID of the delegate to set; use None to remove.	required

set_owner(user_id: str) -> None async

Set the owner for this user.

Parameters:

Name	Type	Description	Default
user_id	str	ID of the owner to set; use None to remove.	required

unassign_global_role(group_id: int | str) -> None async

Unassign a global role (user group) from this user.

Parameters:

Name	Type	Description	Default
group_id	int | str	ID of an assigned user group	required

unassign_inventory_roles(*assignment_ids: str | int) -> None async

Unassign inventory role assignments from this user.

Parameters:

Name	Type	Description	Default
*assignment_ids	str | int	IDs of existing inventory role assignments	()

CurrentUser

Represents a "current" User object within Cumulocity.

See also https://cumulocity.com/api/core/#tag/Current-User

update_password(current_password: str, new_password: str) async

Update the current user's password.

Parameters:

Name	Type	Description	Default
current_password	str	the current password	required
new_password	str	the new password to set	required

UserGroup

Represents a Group object ("Global Role") within Cumulocity.

Notes

• Global Roles are called 'groups' in the Cumulocity Standard REST API; However, 'global roles' is the official concept name and therefore used for consistency with the Cumulocity realm.

• Only a limited set of properties are actually updatable. Others must be set explicitly using the corresponding API (for example: permissions).

See also: https://cumulocity.com/api/core/#tag/Groups

__init__(c8y: CumulocityRestClient | None = None, name: str | None = None, description: str | None = None)

assign_roles(*role_ids: str) async

assign_users(*users: str) async

Assign users to this group.

This operation is executed immediately.

Parameters:

Name	Type	Description	Default
*users	str	An Iterable of usernames	()

create() -> Self async

Create the GlobalRole within the database.

Returns:

Type	Description
Self	A fresh GlobalRole object representing what was
Self	created within the database (including the ID).

delete() async

Delete this object within the database.

reload(copy: bool = False) -> Self async

Reload this object's data from database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The reloaded GlobalRole. By default this is self; if copy=True,
Self	a fresh instance.

unassign_roles(*role_ids: str) async

unassign_users(*users: str) async

Unassign users from this group.

This operation is executed immediately.

Parameters:

Name	Type	Description	Default
*users	str	An Iterable of usernames	()

update(copy: bool = False) -> Self async

Write changes to the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated GlobalRole. By default this is self; if copy=True,
Self	a fresh instance.

UserGroups

Provides access to the (User) Groups API.

Notes

• User groups are called Global Roles in the Cumulocity UI; However, 'group' is the technical name and therefore used for consistency with the REST API.

See also: https://cumulocity.com/api/core/#tag/Groups

assign_roles(group_id: int | str, *role_ids: str, workers: int | None = None) async

Add roles to a user group.

Parameters:

Name	Type	Description	Default
group_id	int | str	Technical ID of the global role	required
*role_ids	str	Iterable of role ID to assign	()
workers	int	Number of parallel requests; defaults to sequential	None

assign_users(group_id: int | str, *usernames: str, workers: int | None = None) async

Assign users to a global role.

Parameters:

Name	Type	Description	Default
group_id	int | str	Technical ID of the user group	required
*usernames	str	Iterable of usernames to assign	()
workers	int	Number of parallel requests; defaults to sequential	None

build_object_path(object_id: str) -> str

create(*groups: UserGroup, workers: int | None = None) -> None async

Create user groups within the database.

Parameters:

Name	Type	Description	Default
*groups	UserGroup	Collection of UserGroup instances	()
workers	int	Number of parallel requests	None

delete(*groups: str | int | UserGroup, workers: int | None = None) -> None async

Delete user groups from the database.

Parameters:

Name	Type	Description	Default
*groups	str | int | UserGroup	Group objects or IDs to delete	()
workers	int	Number of parallel requests	None

get(group_id: int | str) async

Retrieve a specific group.

Parameters:

Name	Type	Description	Default
group_id	int | str	The ID of the user group.	required

Returns:

Type	Description
	A UserGroup instance

get_all(expression: str | None = None, *, username: str | None = None, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> list[UserGroup] async

Query the database for user groups and return the results as a list.

This function is a greedy version of the select function. All available results are read immediately and returned as a list.

See select for a documentation of arguments.

Returns:

Type	Description
list[UserGroup]	List of UserGroup objects

get_by_name(name: str) async

Retrieve a specific group by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the user group.	required

Returns:

Type	Description
	A UserGroup instance

get_count(expression: str | None = None, *, username: str | None = None) -> int async

Calculate the number of user groups in the database.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
username	str	Count groups assigned to a specific user; if omitted, the total number of groups is returned.	None

Returns:

Type	Description
int	Number of user groups

resolve_group_ids(*names: str) -> list[int] async

Resolve group names to their numeric IDs.

Parameters:

Name	Type	Description	Default
*names	str	Names of user groups to resolve.	()

Returns:

Type	Description
list[int]	List of numeric group IDs

select(expression: str | None = None, *, username: str | None = None, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> AsyncIterator[UserGroup]

Iterate over user groups.

Parameters:

Name	Type	Description	Default
expression	str	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	None
username	str	Retrieve groups assigned to a specified user If omitted, all available groups are returned	None
include	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
exclude	str | JsonMatcher	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	None
limit	int | None	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass None to fetch all matching.	5
page_size	int | None	Number of records read per request. If None (default), inferred from limit and whether client-side filters are set.	None
page_number	int	Pull a specific page; this effectively disables automatic follow-up page retrieval.	None
as_values	str | tuple | Sequence[str | tuple] | None	(*str|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	None
workers	int	Number of pages to fetch in parallel; defaults to sequential	None

Return

Generator of GlobalRole instances

See also

https://github.com/bytebutcher/pydfql/blob/main/docs/USER_GUIDE.md#4-query-language

unassign_roles(group_id: int | str, *role_ids: str, workers: int | None = None) async

Remove roles from a user group.

Parameters:

Name	Type	Description	Default
group_id	int | str	Technical ID of the global role	required
*role_ids	str	Iterable of role ID to assign	()
workers	int	Number of parallel requests; defaults to sequential	None

unassign_users(group_id: int | str, *usernames: str, workers: int | None = None) async

Unassign users from a user group.

Parameters:

Name	Type	Description	Default
group_id	int | str	Technical ID of the user group	required
*usernames	str	Iterable of usernames to unassign	()
workers	int	Number of parallel requests; defaults to sequential	None

update(*groups: UserGroup, workers: int | None = None) -> None async

Update user groups within the database.

Parameters:

Name	Type	Description	Default
*groups	UserGroup	Collection of UserGroup instances	()
workers	int	Number of parallel requests	None

TfaSettings

TFA settings representation within Cumulocity.

This is a regular JSON dict which features convenience properties for known/default entries.

Permission

Represents a permission within an inventory role.

See also: https://cumulocity.com/api/core/#tag/Inventory-Roles

Level

Scope

__init__(data: dict | None = None, *, level: str = Level.ANY, scope: str = Scope.ANY, type: str = '*')

from_json(data: dict) -> Self classmethod

ReadPermission

Represents a read-only permission within an inventory role.

__init__(scope: str = Permission.Scope.ANY, type: str = '*')

WritePermission

Represents a write permission within an inventory role.

__init__(scope: str = Permission.Scope.ANY, type: str = '*')

AnyPermission

Represents a read/write permission within an inventory role.

__init__(scope: str = Permission.Scope.ANY, type: str = '*')

Operation

Represents an instance of an operation object in Cumulocity.

Instances of this class are returned by functions of the corresponding Operation API. Use this class to create new or update existing operations.

See also: https://cumulocity.com/api/core/#tag/Operations

__init__(c8y: CumulocityRestClient | None = None, *, device_id: str | None = None, description: str | None = None, status: str | None = None, **kwargs)

create() -> Self async

Store the Operation within the database.

Returns:

Type	Description
Self	A fresh Operation object representing what was created within the database.

send_to(*devices: str | Device, workers: int | None = None) -> None async

Send the Operation to devices within the database.

Parameters:

Name	Type	Description	Default
*devices	str | Device	A collection of devices or device IDs	()
workers	int	The number of parallel processes to use	None

update(copy: bool = False) -> Self async

Update the Operation within the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated Operation. By default this is self; if copy=True,
Self	a fresh instance.

BulkOperation

Represents an instance of a bulk operation object in Cumulocity.

Instances of this class are returned by functions of the corresponding Bulk Operation API. Use this class to create new or update existing bulk operations.

See also: https://cumulocity.com/api/core/#tag/Bulk-operations

__init__(c8y: CumulocityRestClient | None = None, *, group_id: str | None = None, failed_parent_id: str | None = None, start_time: str | datetime | None = None, creation_ramp: float | None = None, operation_prototype: dict | None = None, **kwargs)

create() -> Self async

Store the Bulk Operation within the database.

Returns:

Type	Description
Self	A fresh BulkOperation object representing what was created within the database.

reload(copy: bool = False) -> Self async

Reload the BulkOperation from the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The reloaded BulkOperation. By default this is self; if copy=True,
Self	a fresh instance.

update(copy: bool = False) -> Self async

Update the BulkOperation within the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated BulkOperation. By default this is self; if copy=True,
Self	a fresh instance.

Application

Represent an instance of an application object in Cumulocity.

Instances of this class are returned by functions of the corresponding API. Use this class to create new or update objects.

See also: https://cumulocity.com/api/#tag/Application-API

__init__(c8y: CumulocityRestClient | None = None, *, name: str | None = None, key: str | None = None, type: str | None = None, availability: str | None = None, context_path: str | None = None, manifest: dict | None = None, roles: list[str] | None = None, required_roles: list[str] | None = None, breadcrumbs: bool | None = None, content_security_policy: str | None = None, dynamic_options_url: str | None = None, global_title: str | None = None, legacy: bool | None = None, right_drawer: bool | None = None, upgrade: bool | None = None, **kwargs)

Create a new Application object.

Parameters:

Name	Type	Description	Default
c8y	CumulocityRestClient	Cumulocity connection reference; needs to be set for direct manipulation (create, delete)	None
name	str	Name of the application	None
key	str	Key to identify the application	None
type	str	Type of the application	None
availability	str	Application access level for tenants	None
context_path	str	The path where the application is accessible	None
manifest	dict	Microservice or web application manifest	None
roles	list[str]	List of roles provided by the application	None
required_roles	list[str]	List of roles required by the application	None
breadcrumbs	bool	Whether the (web) application uses breadcrumbs	None
content_security_policy	str	The content security policy of the application	None
dynamic_options_url	str	A URL to a JSON object with dynamic content options	None
global_title	str	The global title of the application	None
legacy	bool	Whether the (web) application is of legacy type	None
right_drawer	bool	Whether the (web) application uses the right hand context menu	None
upgrade	bool	Whether the (web) application uses both Angular and AngularJS	None

create() -> Self async

Create the Application within the database.

Returns:

Type	Description
Self	A fresh Application object representing what was
Self	created within the database (including the ID).

delete(**_) -> None async

Delete the Application within the database.

resolve_tenant_option_category() -> str | None

Resolve the tenant option category.

The application's tenant option category is defined by the application's settings category (as defined in its manifest), the application's name (as defined in its manifest), or the application's context path. The function chooses the first defined.

Returns:

Type	Description
str | None	The application's tenant option category.

See also https://cumulocity.com/api/core/#operation/postOptionCollectionResource, Encrypted credentials

update(copy: bool = False) -> Self async

Update the Application within the database.

Note: This will only send changed fields to increase performance.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated Application. By default this is self; if copy=True,
Self	a fresh instance.

ApplicationSubscription

Represent current application subscriptions within Cumulocity.

Instances of this class are returned by functions of the Applications API.

See also: https://cumulocity.com/api/core/#tag/Current-application

TenantOption

Represents a tenant option within the database.

Instances of this class are returned by functions of the corresponding Tenant Options API. Use this class to create new or update options.

See also: https://cumulocity.com/api/core/#tag/Options

__init__(c8y: CumulocityRestClient | None = None, *, category: str | None = None, key: str | None = None, value: str | None = None, encrypted: bool | None = None)

create() -> Self async

Create a new representation of this option within the database.

Returns:

Type	Description
Self	A fresh TenantOption instance representing the created option.

delete() -> None async

Remove the option from the database.

reload(copy: bool = False) -> Self async

Reload this option from the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

update(copy: bool = False) -> Self async

Write changes to the database.

Parameters:

Name	Type	Description	Default
copy	bool	If True, return a fresh instance with the server's state and leave self unchanged; default False (mutate self).	False

Returns:

Type	Description
Self	The updated TenantOption. By default this is self; if copy=True,
Self	a fresh instance.

AuditRecord

Represents an Audit Record object within Cumulocity.

Instances of this class are returned by functions of the corresponding Audits API. Use this class to create new AuditRecord objects.

See also: https://cumulocity.com/api/core/#tag/Audits

__init__(c8y: CumulocityRestClient | None = None, *, type: str | None = None, time: str | datetime | None = None, source: str | None = None, activity: str | None = None, text: str | None = None, changes: list[Change] | None = None, severity: str | None = None, application: str | None = None, user: str | None = None, **kwargs)

create() -> Self async

Create the AuditRecord within the database.

Returns:

Type	Description
Self	A fresh AuditRecord object representing what was created within the database.

Change

Change details fragment within an audit log.

__init__(data: dict | None = None, *, attribute: str | None = None, new_value: str | None = None, previous_value: str | None = None, type: str | None = None)