REST API Connector

The Cumulocity Python API (c8y_api module) provides a convenience wrapper around the standard Cumulocity REST API (see also the OpenAPI documentation).

The CumulocityRestApi class provides the fundamental wrapping around authentication and basic get, post, put, delete commands. The CumulocityApi class is your entrypoint into higher level funct ions, grouped by contexts like inventory, users, and measurements. Each of these contexts is documented in detail within the main-api-classes section.

The CumulocityDeviceRegistry class provides an additional entry point for devices, wrapping the entire bootstrap mechanism. See also the Device integration documentation at Cumulocity.

`CumulocityApi`

Main Cumulocity API.

Provides usage centric access to a Cumulocity instance.

Attributes:

Name	Type	Description
`measurements`	`Measurements`	Provide access to the Measurements API.
`inventory`	`Inventory`	Provide access to the Inventory API.
`group_inventory`	`DeviceGroupInventory`	Provide access to the Device Group Inventory API.
`devicegroups`	`DeviceGroupInventory`	Provide access to the Device Group Inventory API.
`binaries`	`Binaries`	Provide access to the Binary API.
`device_inventory`	`DeviceInventory`	Provide access to the Device Inventory API.
`identity`	`Identity`	Provide access to the Identity API.
`users`	`Users`	Provide access to the Users API.
`global_roles`	`GlobalRoles`	Provide access to the Global Roles API.
`inventory_roles`	`InventoryRoles`	Provide access to the Inventory Roles API.
`applications`	`Applications`	Provide access to the Applications API.
`events`	`Events`	Provide access to the Events API.
`alarms`	`Alarms`	Provide access to the Alarm API.
`operations`	`Operations`	Provide access to the Operation API.
`bulk_operations`	`BulkOperations`	Provide access to the BulkOperation API.
`tenant_options`	`TenantOptions`	Provide access to the Tenant Options API.
`notification2_subscriptions`	`Subscriptions`	Provide access to the Notification 2.0 Subscriptions API.
`notification2_tokens`	`Tokens`	Provide access to the Notification 2.0 Tokens API.
`audit_records`	`AuditRecords`	Provide access to the Audit API.
`tenants`	`Tenants`	Provide access to the Audit API.

`CumulocityRestApi`

Cumulocity base REST API.

Provides REST access to a Cumulocity instance.

`authenticate(base_url: str, tenant_id: str, username: str, password: str, tfa_token: str = None) -> (str, str)` `classmethod`

Authenticate a user using OAI Secure login method.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	Cumulocity base URL, e.g. https://cumulocity.com	required
`tenant_id`	`str`	The ID of the tenant to connect to	required
`username`	`str`	Username	required
`password`	`str`	User password	required
`tfa_token`	`str`	Currently valid two-factor authorization token	`None`

Returns:

Type	Description
`(str, str)`	A string tuple of JWT auth token and corresponding XRSF token.

`delete(resource: str, json: dict = None, params: dict = None)`

Generic HTTP POST wrapper, dealing with standard error returning a JSON body object.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`json`	`dict`	JSON body (nested dict)	`None`
`params`	`dict`	Additional request parameters	`None`

Returns:

Type	Description
	The JSON response (nested dict)

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 200 and 204 are accepted).

`get(resource: str, params: dict = None, accept: str = None, ordered: bool = False) -> dict`

Generic HTTP GET wrapper, dealing with standard error returning a JSON body object.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`params`	`dict`	Additional request parameters	`None`
`accept`	`str \| None`	Custom Accept header to use (default is application/json). Specify '' to send no Accept header.	`None`
`ordered`	`bool`	Whether the result JSON needs to be ordered (default is False)	`False`

Returns:

Type	Description
`dict`	The JSON response (nested dict)

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 200 is accepted).

`get_file(resource: str, params: dict = None) -> bytes`

Generic HTTP GET wrapper.

Used for downloading binary data, i.e. reading binaries from Cumulocity.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`params`	`dict`	Additional request parameters	`None`

Returns:

Type	Description
`bytes`	The binary data as bytes.

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 200 is accepted).

`post(resource: str, json: dict, accept: str = None, content_type: str = None) -> dict`

Generic HTTP POST wrapper, dealing with standard error returning a JSON body object.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`json`	`dict`	JSON body (nested dict)	required
`accept`	`str \| None`	Custom Accept header to use (default is application/json). Specify '' to send no Accept header.	`None`
`content_type`	`str \| None`	Custom Content-Type header to use (default is application/json)	`None`

Returns:

Type	Description
`dict`	The JSON response (nested dict)

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 200 and 201 are accepted).

`post_file(resource: str, file: str | BinaryIO, object: dict = None, accept: str = None, content_type: str = None)`

Generic HTTP POST wrapper.

Used for posting binary data, i.e. creating binary objects in Cumulocity.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`file`	`str \| BinaryIO`	File-like object or a file path	required
`object`	`dict`	File metadata, stored within Cumulocity	`None`
`accept`	`str \| None`	Custom Accept header to use (default is application/json). Specify '' to send no Accept header.	`None`
`content_type`	`str`	Content type of the file sent (default is application/octet-stream)	`None`

Returns:

Type	Description
	The JSON response (nested dict)

Raises:

Type	Description
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 201 is accepted).

`prepare_request(method: str, resource: str, json: dict = None, additional_headers: Dict[str, str] = None) -> requests.PreparedRequest`

Prepare an HTTP request.

Parameters:

Name	Type	Description	Default
`method`	`str`	One of 'GET', 'POST', 'PUT', 'DELETE'	required
`resource`	`str`	Path to the HTTP resource	required
`json`	`dict`	JSON body (nested dict) to send with the request	`None`
`additional_headers`	`dict`	Additional non-standard headers to include in the request	`None`

Returns:

Type	Description
`PreparedRequest`	A PreparedRequest instance

`put(resource: str, json: dict, params: dict = None, accept: str = None, content_type: str = None) -> dict`

Generic HTTP PUT wrapper, dealing with standard error returning a JSON body object.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`json`	`dict`	JSON body (nested dict)	required
`params`	`dict`	Additional request parameters	`None`
`accept`	`str \| None`	Custom Accept header to use (default is application/json). Specify '' to send no Accept header.	`None`
`content_type`	`str \| None`	Custom Content-Type header to use (default is application/json)	`None`

Returns:

Type	Description
`dict`	The JSON response (nested dict)

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 200 is accepted).

`put_file(resource: str, file: str | BinaryIO, accept: str = None, content_type: str = None)`

Generic HTTP PUT wrapper.

Used for put'ing binary data, i.e. updating binaries in Cumulocity.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`file`	`str \| BinaryIO`	File-like object or a file path	required
`accept`	`str \| None`	Custom Accept header to use (default is application/json). Specify '' to send no Accept header.	`None`
`content_type`	`str`	Content type of the file sent (default is application/octet-stream)	`None`

Returns:

Type	Description
	The JSON response (nested dict)

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`SyntaxError`	if the request cannot be processes (5xx)
`ValueError`	if the response is not ok for other reasons (only 201 is accepted).

`CumulocityDeviceRegistry`

Special CumulocityRESTAPI instance handling device registration.

https://cumulocity.com/guides/users-guide/device-management/#connecting-devices

`Credentials` `dataclass`

Bundles authentication information.

`await_connection(device_id: str, timeout: str = '60m', pause: str = '1s') -> CumulocityApi`

Wait for device credentials and build corresponding API connection.

The device must have requested credentials already. This function awaits the request confirmation and returns a CumulocityAPI instance for the device-specific credentials.

Parameters:

Name	Type	Description	Default
`device_id`	`str`	The external ID of the device (i.e. IMEI - NOT the Cumulocity ID)	required
`timeout`	`str`	How long to wait for the request to be confirmed. This is a formatted string in the form , accepted units are 'h' (hours), 'm' (minutes), 's' (seconds) and 'ms' (milliseconds). A reasonable value for this depends on application.	`'60m'`
`pause`	`str`	How long to pause between request confirmation checks This is a formatted string, see `timeout` parameter.	`'1s'`

Returns:

Type	Description
`CumulocityApi`	Device-specific CumulocityAPI instance

Raises:

Type	Description
`TimeoutError`	if the request was not confirmed in time.

See also: https://cumulocity.com/guides/users-guide/device-management/#connecting-devices

`await_credentials(device_id: str, timeout: str = '60m', pause: str = '1s') -> Credentials`

Wait for device credentials.

The device must have requested credentials already. This function awaits the request confirmation and returns the device-specific credentials generated by the Cumulocity platform.

Parameters:

Name	Type	Description	Default
`device_id`	`str`	The external ID of the device (i.e. IMEI - NOT the Cumulocity ID)	required
`timeout`	`str`	How long to wait for the request to be confirmed. This is a formatted string in the form , accepted units are 'h' (hours), 'm' (minutes), 's' (seconds) and 'ms' (milliseconds). A reasonable value for this depends on application.	`'60m'`
`pause`	`str`	How long to pause between request confirmation checks This is a formatted string, see `timeout` parameter.	`'1s'`

Returns:

Type	Description
`Credentials`	Credentials object holding the device credentials

Raises:

Type	Description
`TimeoutError`	if the request was not confirmed in time.

See also: https://cumulocity.com/guides/users-guide/device-management/#connecting-devices

`default()` `classmethod`

Return the default (bootstrap) instance.

REST API Connector

CumulocityApi

CumulocityRestApi

authenticate(base_url: str, tenant_id: str, username: str, password: str, tfa_token: str = None) -> (str, str) classmethod

delete(resource: str, json: dict = None, params: dict = None)

get(resource: str, params: dict = None, accept: str = None, ordered: bool = False) -> dict

get_file(resource: str, params: dict = None) -> bytes

post(resource: str, json: dict, accept: str = None, content_type: str = None) -> dict

post_file(resource: str, file: str | BinaryIO, object: dict = None, accept: str = None, content_type: str = None)

prepare_request(method: str, resource: str, json: dict = None, additional_headers: Dict[str, str] = None) -> requests.PreparedRequest

put(resource: str, json: dict, params: dict = None, accept: str = None, content_type: str = None) -> dict

put_file(resource: str, file: str | BinaryIO, accept: str = None, content_type: str = None)

CumulocityDeviceRegistry

Credentials dataclass

await_connection(device_id: str, timeout: str = '60m', pause: str = '1s') -> CumulocityApi

await_credentials(device_id: str, timeout: str = '60m', pause: str = '1s') -> Credentials

default() classmethod

`CumulocityApi`

`CumulocityRestApi`

`authenticate(base_url: str, tenant_id: str, username: str, password: str, tfa_token: str = None) -> (str, str)` `classmethod`

`delete(resource: str, json: dict = None, params: dict = None)`

`get(resource: str, params: dict = None, accept: str = None, ordered: bool = False) -> dict`

`get_file(resource: str, params: dict = None) -> bytes`

`post(resource: str, json: dict, accept: str = None, content_type: str = None) -> dict`

`post_file(resource: str, file: str | BinaryIO, object: dict = None, accept: str = None, content_type: str = None)`

`prepare_request(method: str, resource: str, json: dict = None, additional_headers: Dict[str, str] = None) -> requests.PreparedRequest`

`put(resource: str, json: dict, params: dict = None, accept: str = None, content_type: str = None) -> dict`

`put_file(resource: str, file: str | BinaryIO, accept: str = None, content_type: str = None)`

`CumulocityDeviceRegistry`

`Credentials` `dataclass`

`await_connection(device_id: str, timeout: str = '60m', pause: str = '1s') -> CumulocityApi`

`await_credentials(device_id: str, timeout: str = '60m', pause: str = '1s') -> Credentials`

`default()` `classmethod`