Admin Documentation

Contents

Admin Documentation#

General users should NOT use this API directly and instead should use pingthings.Client. Only use this API directly if you have a specific purpose in mind.

Client#

class pingthings.admin.AdminClient#

Bases: object

add_group(name)#
add_streams_to_my_collection(my_collection_id, stream_uuids)#

Adds streams to a My Collection. If any of the provided streams are already in the collection, they will be ignored.

add_user_to_group(username, group)#
authenticate_user(username, password)#
authenticate_user_by_key(apikey)#
clear_event_type_enforcement(group)#

Clears event type enforcement for a group.

Parameters:

group – The group to clear enforcement for.

create_api_key(username, description, expires=None, delete_on_expiry=None)#
create_event(start_time, end_time=None, stream_uuids=None, group_names=None, source=None, type=None, message=None, title=None)#

Creates an event.

Parameters:

  • start_time – The start time of the event (datetime.datetime or int representing nanoseconds since epoch)

  • end_time – The end time of the event (optional, datetime.datetime or int representing nanoseconds since epoch).

  • stream_uuids – List of stream UUIDs (optional)

  • group_names – List of group names (optional). If not provided, the event will be visible to all groups that the user creating the event is a member of.

  • source – What created/identified the event? (optional)

  • type – What kind of event? (optional)

  • message – Longer form description of the event (optional)

  • title – A short title for the event (optional)

Returns:

A dictionary representing the created event.

create_event_type(group, name, description=None)#

Creates an event type.

Parameters:

  • group – The group the event type belongs to.

  • name – The name of the event type.

  • description – A description of the event type (optional).

Returns:

A dictionary representing the created event type.

create_my_collection(name, description=None, parent_my_collection_uuid=None)#

Creates a new My Collection for the currently authenticated user.

Parameters:

  • name – The name of the collection

  • description – An optional description of the collection

  • parent_my_collection_uuid – An optional UUID of a different my collection to use as the parent of the new collection

Returns:

A dictionary representing the newly created My Collection. It will contain the following keys:

  • uuid: The UUID of the collection

  • name: The name of the collection

  • description: The description of the collection

  • parent_my_collection_uuid: The UUID of the parent collection, or an empty

    string if there is no parent

  • stream_uuids: A list of UUIDs of streams that are in the collection

create_service_account(username, comment)#
create_user(username, full_name, email, comment, password)#
delete_api_key(username, key_id)#
delete_event(id)#

Deletes an event by its ID.

Parameters:

event_id – The ID of the event to delete.

delete_event_type(id)#

Deletes an event type by its ID.

Parameters:

id – The ID of the event type to delete.

delete_group(name)#
delete_my_collection(uuid)#

Deletes a My Collection and all of its child collections. Streams that are contained in the collection or any of its children will NOT be deleted.

delete_user(username)#
extend_api_key(username, key_id, days)#
get_all_groups()#
get_all_users()#
get_api_key(username)#
get_builtin_user(username)#
get_event(id)#

Retrieves an event by its ID.

Parameters:

event_id – The ID of the event to retrieve.

Returns:

A dictionary representing the event, or None if not found.

get_event_type(id)#

Retrieves an event type by its ID.

Parameters:

id – The ID of the event type to retrieve.

Returns:

A dictionary representing the event type.

get_group(name)#
get_identity_provider()#
get_public_user()#
get_self_builtin_user()#
list_api_keys(username)#
list_event_types(group=Ellipsis)#

Lists event types, optionally filtered to a single group.

Parameters:

group – If provided, only return event types for this group. When empty, event types for all of the caller’s groups are returned.

Returns:

A tuple (event_types, enforce) where event_types is a list of event type dictionaries and enforce is the group’s enforcement flag (a bool) when a group filter is given, or None when no group filter is provided.

list_events(start_time=None, end_time=None, source_contains=None, type_contains=None, message_contains=None, limit=100, offset=0, sort_by=Ellipsis, sort_desc=False, title_contains=None, created_by_contains=None, full_text_search=None, stream_uuids=None, include_stream_geos=False)#

Return all events that match the given criteria paginated by offset and limit.

Parameters:

  • start_time – Events must start at this time or greater than this time.

  • end_time – Events must end at this time or before this time.

  • source_contains – Substring case-insensitive filter for the event source.

  • type_contains – Substring case-insensitive filter for the event type.

  • message_contains – The event must contain this string subset, this uses a case-insensitive substring search.

  • limit – How many events to return at once

  • offset – Pagination offset

  • sort_by – What event parameter to sort by?

  • sort_desc – Should the results be returned descending order by the sort_by parameter?

  • title_contains – Substring case-insensitive filter for the event title.

  • created_by_contains – Substring case-insensitive filter for the user that created the event.

  • full_text_search – Substring case-insensitive filter across all text fields (title, message, source, type, created_by).

  • stream_uuids – If provided, only return events associated with at least one of these stream UUIDs.

  • include_stream_geos – If True, populate stream_geos on each returned event with the unique GeoJSON coordinates of associated streams. Defaults to False.

Returns:

A tuple containing the list of events matching the given criteria and the total count of matching events.

Examples

Find all events that contain the word ‘voltage’ (case insensitive):

>>> AdminClient.list_events(message_contains="voltage")
list_my_collections()#

Return all custom collections you have created.

Returns:

All custom collections you have created.

list_service_accounts()#
migrate_api_keys()#
remove_streams_from_my_collection(my_collection_id, stream_uuids)#

Removes streams from a My Collection. If any of the provided streams are not in the collection, they will be ignored.

remove_user_from_group(username, group)#
reset_api_key(username)#
rotate_api_key(username, key_id, grace_period)#
send_account_creation_email(username, fullname=Ellipsis, email=Ellipsis, password=Ellipsis, apikey=Ellipsis)#
set_event_type_enforcement(group, enforce)#

Enables or disables event type enforcement for a group. When enforcement is enabled, events created for the group must use one of the group’s defined event types.

Parameters:

  • group – The group to set enforcement for.

  • enforce – Whether to enforce event types for the group.

set_identity_provider(provider)#
set_user_password(username, password)#
update_api_key(username, key_id, description, delete_on_expiry, expires=None)#
update_event_type(id, name=None, description=None)#

Updates an event type.

Parameters:

  • id – The ID of the event type to update.

  • name – The new name of the event type. When omitted or None, the existing name is left unchanged.

  • description – The new description of the event type. When omitted or None, the existing description is left unchanged; pass "" to clear it.

The underlying RPC is a full replacement, so omitted fields are filled in by first fetching the current event type (a read-modify-write).

Returns:

A dictionary representing the updated event type.

update_my_collection(my_collection_id, patch)#

Updates a My Collection with the provided patch.

Parameters:

  • my_collection_uuid – The UUID of the collection to update

  • patch –

    A dictionary of fields to update. Only fields contained in the dictionary will be updated; all other fields will remain unchanged.

    The list of fields that can be updated are:

    • name: Must be set to a non-empty string

    • description: Can be set to any string or None

    • parent_my_collection_uuid: Can be set to a UUID of a different

      My Collection, or None to make the collection top-level

Returns:

A dictionary representing the updated My Collection. It will contain the same keys as the create_my_collection method.

update_service_account(username, comment)#
update_user(username, full_name, email, comment)#
user_exists(username)#
Contents