Manage Your Fleet with Viam's Fleet Management API

Parameters:

• email (str) (required): The email of the user.

Returns:

• (str): The ID of the user.

Example:

id = await cloud.get_user_id_by_email("youremail@email.com")

For more information, see the Python SDK Docs.

Parameters:

• name (str) (required): The name of the organization.

Returns:

• (viam.proto.app.Organization): The created organization.

Example:

organization = await cloud.create_organization("name")

For more information, see the Python SDK Docs.

Parameters:

• None.

Returns:

• (List[viam.proto.app.Organization]): The list of organizations.

Example:

org_list = await cloud.list_organizations()

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (required): The ID of the location.

Returns:

• (List[viam.proto.app.OrganizationIdentity]): The list of organizations.

Example:

org_list = await cloud.get_organizations_with_access_to_location("location-id")

For more information, see the Python SDK Docs.

Parameters:

• user_id (str) (required): The ID of the user. You can retrieve this with the get_user_id_by_email() method.

Returns:

• (List[viam.proto.app.OrgDetails]): The list of organizations.

Example:

org_list = await cloud.list_organizations_by_user("<YOUR-USER-ID>")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to query. You can retrieve this from the organization settings page.

Returns:

• (viam.proto.app.Organization): The requested organization.

Raises:

• (GRPCError): If the provided org_id is invalid, or not currently authed to.

Example:

org = await cloud.get_organization("<YOUR-ORG-ID>")

For more information, see the Python SDK Docs.

Parameters:

• public_namespace (str) (required): Organization namespace to check. Namespaces can only contain lowercase alphanumeric and dash characters.

Returns:

• (bool): True if the provided namespace is available.

Raises:

• (GRPCError): If an invalid namespace (for example, “”) is provided.

Example:

available = await cloud.get_organization_namespace_availability(
    public_namespace="my-cool-organization")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to update.
• name (str) (optional): If provided, updates the org’s name.
• public_namespace (str) (optional): If provided, sets the org’s namespace if it hasn’t already been set.
• region (str) (optional): If provided, updates the org’s region.
• cid (str) (optional): If provided, update’s the org’s CRM ID.

Returns:

• (viam.proto.app.Organization): The updated organization.

Raises:

• (GRPCError): If the org’s namespace has already been set, or if the provided namespace is already taken.

Example:

organization = await cloud.update_organization(
    org_id="<YOUR-ORG-ID>",
    name="Artoo's Org",
    public_namespace="artoo"
)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization. You can obtain your organization ID from the Viam app’s organization settings page.

Returns:

• None.

Example:

await cloud.delete_organization("<YOUR-ORG-ID>")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to list members of. You can obtain your organization ID from the Viam app’s organization settings page.

Returns:

• (Tuple[List[app.OrganizationMember], List[app.OrganizationInvite]]): A tuple containing two lists; the first [0] of organization members, and the second [1] of organization invites.

Example:

member_list, invite_list = await cloud.list_organization_members("<YOUR-ORG-ID>")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to create an invite for. You can obtain your organization ID from the Viam app’s organization settings page.
• email (str) (required): The email address to send the invite to.
• authorizations (List[viam.proto.app.Authorization]) (optional): Specifications of the authorizations to include in the invite. If not provided, full owner permissions will be granted.
• send_email_invite (bool) (required): Whether or not an email should be sent to the recipient of an invite. The user must accept the email to be added to the associated authorizations. When set to false, the user automatically receives the associated authorization on the next login of the user with the associated email address.

Returns:

• (app.OrganizationInvite): The organization invite.

Raises:

• (GRPCError): if an invalid email is provided, or if the user is already a member of the org.

Example:

await cloud.create_organization_invite("<YOUR-ORG-ID>", "youremail@email.com")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization that the invite is for. You can obtain your organization ID from the Viam app’s organization settings page.
• email (str) (required): Email of the user the invite was sent to.
• add_authorizations (List[viam.proto.app.Authorization]) (optional): Optional list of authorizations to add to the invite.
• remove_authorizations (List[viam.proto.app.Authorization]) (optional): Optional list of authorizations to remove from the invite.

Returns:

• (app.OrganizationInvite): The updated invite.

Raises:

• (GRPCError): If no authorizations are passed or if an invalid combination of authorizations is passed (for example an authorization to remove when the invite only contains one authorization).

Example:

from viam.proto.app import Authorization

auth = Authorization(
    authorization_type="role",
    authorization_id="location_owner",
    resource_type="location", # "robot", "location", or "organization"
    resource_id="012456lni0", # machine id, location id or org id
    identity_id="",
    organization_id="<YOUR-ORG-ID>",
    identity_type=""
)

update_invite = await cloud.update_organization_invite_authorizations(
    org_id="<YOUR-ORG-ID>",
    email="notarealemail@viam.com",
    add_authorizations=[auth]
)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the org to remove the user from. You can obtain your organization ID from the Viam app’s organization settings page.
• user_id (str) (required): The ID of the user to remove.

Returns:

• None.

Example:

member_list, invite_list = await cloud.list_organization_members(org_id="<YOUR-ORG-ID>")
first_user_id = member_list[0].user_id

await cloud.delete_organization_member(org_id="org_id", user_id=first_user_id)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization that the invite to delete was for. You can obtain your organization ID from the Viam app’s organization settings page.
• email (str) (required): The email address the pending invite was sent to.

Returns:

• None.

Raises:

• (GRPCError): If no pending invite is associated with the provided email address.

Example:

await cloud.delete_organization_invite("<YOUR-ORG-ID>", "youremail@email.com")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization that the invite to resend was for. You can obtain your organization ID from the Viam app’s organization settings page.
• email (str) (required): The email address associated with the invite.

Returns:

• (app.OrganizationInvite): The organization invite sent.

Raises:

• (GRPCError): If no pending invite is associated with the provided email address.

Example:

org_invite = await cloud.resend_organization_invite("<YOUR-ORG-ID>", "youremail@email.com")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to create the location under. You can obtain your organization ID from the Viam app’s organization settings page.
• name (str) (required): Name of the location.
• parent_location_id (str) (optional): Optional parent location to put the location under. Defaults to a root-level location if no location ID is provided.

Returns:

• (viam.proto.app.Location): The newly created location.

Raises:

• (GRPCError): If either an invalid name (for example, “”), or parent location ID (for example, a nonexistent ID) is passed.

Example:

my_new_location = await cloud.create_location(org_id="<YOUR-ORG-ID>", name="Robotville", parent_location_id="111ab12345")

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (optional): ID of the location to get. Defaults to the location ID provided at AppClient instantiation.

Returns:

• (viam.proto.app.Location): The location.

Raises:

• (GRPCError): If an invalid location ID is passed or if one isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

location = await cloud.get_location(location_id="123ab12345")

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (required): ID of the location to update. Must be specified.
• name (str) (optional): Optional new name to be updated on the location. Defaults to the empty string “” (that is, the name doesn’t change).
• parent_location_id (str) (optional): Optional ID of new parent location to move the location under. Defaults to the empty string “” (that is, no new parent location is assigned).

Returns:

• (viam.proto.app.Location): The newly updated location.

Raises:

• (GRPCError): If either an invalid location ID, name, or parent location ID is passed.

Example:

# The following line takes the location with ID "abc12abcde" and moves it to be a
# sub-location of the location with ID "xyz34xxxxx"
my_updated_location = await cloud.update_location(
    location_id="abc12abcde",
    name="",
    parent_location_id="xyz34xxxxx",
)

# The following line changes the name of the location without changing its parent location
my_updated_location = await cloud.update_location(
    location_id="abc12abcde",
    name="Land Before Robots"
)

# The following line moves the location back up to be a top level location without changing its name
my_updated_location = await cloud.update_location(
    location_id="abc12abcde",
    name="",
    parent_location_id=""
)

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (required): ID of the location to delete. Must be specified.

Returns:

• None.

Raises:

• (GRPCError): If an invalid location ID is passed.

Example:

await cloud.delete_location(location_id="abc12abcde")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the org to list locations for. You can obtain your organization ID from the Viam app’s organization settings page.

Returns:

• (List[viam.proto.app.Location]): The list of locations.

Example:

locations = await cloud.list_locations("<YOUR-ORG-ID>")

For more information, see the Python SDK Docs.

Parameters:

• organization_id (str) (required): The ID of the organization.
• location_id (str) (required): The ID of the location.

Returns:

• None.

Example:

await cloud.share_location("<YOUR-ORG-ID>", "<YOUR-LOCATION-ID>")

For more information, see the Python SDK Docs.

Parameters:

• organization_id (str) (required): The ID of the organization.
• location_id (str) (required): The ID of the location.

Returns:

• None.

Example:

await cloud.unshare_location("<YOUR-ORG-ID>", "<YOUR-LOCATION-ID>")

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (optional): ID of the location to retrieve LocationAuth from. Defaults to the location ID provided at AppClient instantiation.

Returns:

• (viam.proto.app.LocationAuth): The LocationAuth containing location secrets.

Raises:

• (GRPCError): If an invalid location ID is passed or if one isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

loc_auth = await cloud.location_auth(location_id="123xy12345")

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (optional): ID of the location to generate a new secret for. Defaults to the location ID provided at AppClient instantiation.

Returns:

• (viam.proto.app.LocationAuth): The specified location’s LocationAuth containing the newly created secret.

Raises:

• (GRPCError): If an invalid location ID is passed or one isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

new_loc_auth = await cloud.create_location_secret(location_id="123xy12345")

For more information, see the Python SDK Docs.

Parameters:

• secret_id (str) (required): ID of the secret to delete.
• location_id (str) (optional): ID of the location to delete secret from. Defaults to the location ID provided at AppClient instantiation.

Returns:

• None.

Raises:

• (GRPCError): If either an invalid location ID or secret ID is passed or a location ID isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

await cloud.delete_location_secret(
    secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz",
    location_id="123xy12345"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_id (str) (required): ID of the machine to get. You can copy this value from the URL of the machine’s page.

Returns:

• (viam.proto.app.Robot): The machine.

Raises:

• (GRPCError): If an invalid machine ID is passed.

Example:

machine = await cloud.get_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")

For more information, see the Python SDK Docs.

Parameters:

• robot_id (str) (required): The ID of the machine.

Returns:

• (List[viam.proto.app.APIKeyWithAuthorizations]): The list of API keys.

Example:

api_keys = await cloud.get_robot_api_keys(robot_id="robot-id")

For more information, see the Python SDK Docs.

Parameters:

• robot_id (str) (required): ID of the machine to get parts from.

Returns:

• (List[RobotPart]): The list of machine parts.

Raises:

• (GRPCError): If an invalid machine ID is passed.

Example:

list_of_parts = await cloud.get_robot_parts(
    robot_id="1a123456-x1yz-0ab0-a12xyzabc"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to get. You can retrieve this value by navigating to the machine’s page, clicking on the part status dropdown, and clicking the copy icon next to Part ID.
• dest (str) (optional): Optional filepath to write the machine part’s config file in JSON format to.
• indent (int) (required): Size (in number of spaces) of indent when writing config to dest. Defaults to 4.

Returns:

• (RobotPart): The machine part.

Raises:

• (GRPCError): If an invalid machine part ID is passed.

Example:

my_robot_part = await cloud.get_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to get logs from.
• filter (str) (optional): Only include logs with messages that contain the string filter. Defaults to empty string “” (that is, no filter).
• dest (str) (optional): Optional filepath to write the log entries to.
• log_levels (List[str]) (required): List of log levels for which entries should be returned. Defaults to empty list, which returns all logs.
• num_log_entries (int) (required): Number of log entries to return. Passing 0 returns all logs. Defaults to 100. All logs or the first num_log_entries logs will be returned, whichever comes first.

Returns:

• (List[LogEntry]): The list of log entries.

Raises:

• (GRPCError): If an invalid robot part ID is passed.

Example:

part_logs = await cloud.get_robot_part_logs(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22",
    num_log_entries=20
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to retrieve logs from.
• errors_only (bool) (required): Boolean specifying whether or not to only include error logs. Defaults to True.
• filter (str) (optional): Only include logs with messages that contain the string filter. Defaults to empty string “” (that is, no filter).

Returns:

• (viam.app._logs._LogsStream[List[LogEntry]]): The asynchronous iterator receiving live machine part logs.

Example:

logs_stream = await cloud.tail_robot_part_logs(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to retrieve history from.

Returns:

• (List[RobotPartHistoryEntry]): The list of the machine part’s history.

Raises:

• (GRPCError): If an invalid machine part ID is provided.

Example:

part_history = await cloud.get_robot_part_history(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the robot part to update.
• name (str) (required): New name to be updated on the robot part.
• robot_config (Mapping[str, Any]) (optional): Optional new config represented as a dictionary to be updated on the machine part. The machine part’s config will remain as is (no change) if one isn’t passed.

Returns:

• (RobotPart): The newly updated robot part.

Raises:

• (GRPCError): If either an invalid machine part ID, name, or config is passed.

Example:

my_machine_part = await cloud.update_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_id (str) (required): ID of the machine to create a new part for. See Find machine ID for instructions on retrieving this value.
• part_name (str) (required): Name of the new part.

Returns:

• (str): The new machine part’s ID.

Raises:

• (GRPCError): If either an invalid machine ID or name is passed.

Example:

new_part_id = await cloud.new_robot_part(
    robot_id="1a123456-x1yz-0ab0-a12xyzabc", part_name="myNewSubPart"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to delete. See Find part ID for instructions on retrieving this value.

Returns:

• None.

Raises:

• (GRPCError): If an invalid machine part ID is passed.

Example:

await cloud.delete_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to mark as main.

Returns:

• None.

Raises:

• (GRPCError): If an invalid machine part ID is passed.

Example:

await cloud.mark_part_as_main(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to mark for restart.

Returns:

• None.

Raises:

• (GRPCError): If an invalid machine part ID is passed.

Example:

await cloud.mark_part_for_restart(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to create a secret for.

Returns:

• (RobotPart): The machine part the new secret was generated for.

Raises:

• (GRPCError): If an invalid machine part ID is passed.

Example:

part_with_new_secret = await cloud.create_robot_part_secret(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (str) (required): ID of the machine part to delete the secret from.
• secret_id (str) (required): ID of the secret to delete.

Returns:

• None.

Raises:

• (GRPCError): If an invalid machine part ID or secret ID is passed.

Example:

await cloud.delete_robot_part_secret(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22",
    secret_id="123xyz12-abcd-4321-12ab-12xy1xyz12xy")

For more information, see the Python SDK Docs.

Parameters:

• location_id (str) (optional): ID of the location to retrieve the machines from. Defaults to the location ID provided at AppClient instantiation.

Returns:

• (List[viam.proto.app.Robot]): The list of robots.

Raises:

• (GRPCError): If an invalid location ID is passed or one isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

list_of_machines = await cloud.list_robots(location_id="123ab12345")

For more information, see the Python SDK Docs.

Parameters:

• name (str) (required): Name of the new machine.
• location_id (str) (optional): ID of the location under which to create the machine. Defaults to the current authorized location.

Returns:

• (str): The new robot’s ID.

Raises:

• (GRPCError): If an invalid location ID is passed or one isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

new_machine_id = await cloud.new_robot(name="beepboop", location_id="my-location-id")

For more information, see the Python SDK Docs.

Parameters:

• robot_id (str) (required): ID of the machine to update. See Find machine ID for instructions on retrieving this value.
• name (str) (required): New name to be updated on the machine.
• location_id (str) (optional): ID of the location under which the machine exists. Defaults to the location ID provided at AppClient instantiation.

Returns:

• (viam.proto.app.Robot): The newly updated machine.

Raises:

• (GRPCError): If either an invalid machine ID, name, or location ID is passed or a location ID isn’t passed and there was no location ID provided at AppClient instantiation.

Example:

updated_robot = await cloud.update_robot(
    robot_id="1a123456-x1yz-0ab0-a12xyzabc",
    name="Orange-Robot",
    location_id="23ab12345"
)

For more information, see the Python SDK Docs.

Parameters:

• robot_id (str) (required): ID of the machine to delete. See Find machine ID for instructions on retrieving this value.

Returns:

• None.

Raises:

• (GRPCError): If an invalid machine ID is passed.

Example:

await cloud.delete_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to list fragments for. You can obtain your organization ID from the Viam app’s organization settings page.
• show_public (bool) (required): Optional boolean specifying whether or not to only show public fragments. If True, only public fragments will return. If False, only private fragments will return. Defaults to True. Deprecated since version 0.25.0: Use visibilities instead.
• visibilities (List[Fragment]) (optional): List of FragmentVisibilities specifying which types of fragments to include in the results. If empty, by default only public fragments will be returned.

Returns:

• (List[Fragment]): The list of fragments.

Example:

fragments_list = await cloud.list_fragments(org_id="org-id", visibilities=[])

For more information, see the Python SDK Docs.

Parameters:

• machineId (string) (required): The machine ID used to filter fragments defined in a machine’s parts. Also returns any fragments nested within the fragments defined in parts.
• additionalFragmentIds (string) (optional): Additional fragment IDs to append to the response. Useful when needing to view fragments that will be provisionally added to the machine alongside existing fragments.

Returns:

• (Promise<Fragment[]>): The list of top level and nested fragments for a machine, as well as additionally specified fragment IDs.

For more information, see the TypeScript SDK Docs.

Parameters:

• fragment_id (str) (required): ID of the fragment to get.

Returns:

• (Fragment): The fragment.

Raises:

• (GRPCError): If an invalid fragment ID is passed.

Example:

# Get a fragment and print its name and when it was created.
the_fragment = await cloud.get_fragment(
    fragment_id="12a12ab1-1234-5678-abcd-abcd01234567")
print("Name: ", the_fragment.name, "\nCreated on: ", the_fragment.created_on)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to create the fragment within. You can obtain your organization ID from the Viam app’s organization settings page.
• name (str) (required): Name of the fragment.
• config (Mapping[str, Any]) (optional): Optional Dictionary representation of new config to assign to specified fragment. Can be assigned by updating the fragment.

Returns:

• (Fragment): The newly created fragment.

Raises:

• (GRPCError): If an invalid name is passed.

Example:

new_fragment = await cloud.create_fragment(org_id="org-id", name="cool_smart_machine_to_configure_several_of")

For more information, see the Python SDK Docs.

Parameters:

• fragment_id (str) (required): ID of the fragment to update.
• name (str) (required): New name to associate with the fragment.
• config (Mapping[str, Any]) (optional): Optional Dictionary representation of new config to assign to specified fragment. Not passing this parameter will leave the fragment’s config unchanged.
• public (bool) (optional): Boolean specifying whether the fragment is public. Not passing this parameter will leave the fragment’s visibility unchanged. A fragment is private by default when created. Deprecated since version 0.25.0: Use visibility instead.
• visibility (Fragment) (optional): Optional FragmentVisibility list specifying who should be allowed to view the fragment. Not passing this parameter will leave the fragment’s visibility unchanged. A fragment is private by default when created.

Returns:

• (Fragment): The newly updated fragment.

Raises:

• (GRPCError): if an invalid ID, name, or config is passed.

Example:

updated_fragment = await cloud.update_fragment(
    fragment_id="12a12ab1-1234-5678-abcd-abcd01234567",
    name="better_name")

For more information, see the Python SDK Docs.

Parameters:

• fragment_id (str) (required): ID of the fragment to delete.

Returns:

• None.

Raises:

• (GRPCError): If an invalid fragment ID is passed.

Example:

await cloud.delete_fragment(
    fragment_id="12a12ab1-1234-5678-abcd-abcd01234567")

For more information, see the Python SDK Docs.

Parameters:

• id (str) (required): ID of the fragment to fetch history for.
• page_token (str | None) (optional): the page token for the fragment history collection.
• page_limit (int) (optional): the number of fragment history documents to return in the result. The default page limit is 10.

Returns:

• (List[FragmentHistoryEntry]): A list of documents with the fragment history.

Raises:

• (GRPCError): if an invalid fragment id, page token or page limit is passed.

Example:

fragment_history = await cloud.get_fragment_history(
    id = "12a12ab1-1234-5678-abcd-abcd01234567",
    page_token = "pg-token",
    page_limit = 10
)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to create the role in. You can obtain your organization ID from the Viam app’s organization settings page.
• identity_id (str) (required): ID of the entity the role belongs to (for example, a user ID).
• role (Literal[‘owner’] | Literal[‘operator’]) (required): The role to add (either "owner" or "operator").
• resource_type (Literal[‘organization’] | Literal[’location’] | Literal[‘robot’]) (required): The type of the resource to add the role to (either "organization", "location", or "robot"). Must match the type of the resource_id’s resource.
• resource_id (str) (required): ID of the resource the role applies to (the ID of either an organization, location, or machine.).

Returns:

• None.

Raises:

• (GRPCError): If either an invalid identity ID, role ID, resource type, or resource ID is passed.

Example:

await cloud.add_role(
    org_id="<YOUR-ORG-ID>",
    identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
    role="owner",
    resource_type="location",
    resource_id="111ab12345"
)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization the role exists in. You can obtain your organization ID from the Viam app’s organization settings page.
• identity_id (str) (required): ID of the entity the role belongs to (for example, a user ID).
• role (Literal[‘owner’] | Literal[‘operator’]) (required): The role to remove.
• resource_type (Literal[‘organization’] | Literal[’location’] | Literal[‘robot’]) (required): Type of the resource the role is being removed from. Must match resource_id.
• resource_id (str) (required): ID of the resource the role applies to (that is, either an organization, location, or robot ID).

Returns:

• None.

Raises:

• (GRPCError): If either an invalid identity ID, role ID, resource type, or resource ID or is passed.

Example:

await cloud.remove_role(
    org_id="<YOUR-ORG-ID>",
    identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
    role="owner",
    resource_type="location",
    resource_id="111ab12345"
)

For more information, see the Python SDK Docs.

Parameters:

• organization_id (str) (required): ID of the organization.
• old_identity_id (str) (required): ID of the entity the role belongs to (for example, a user ID).
• old_role (Literal[‘owner’] | Literal[‘operator’]) (required): The role to be changed.
• old_resource_type (Literal[‘organization’] | Literal[’location’] | Literal[‘robot’]) (required): Type of the resource the role is added to. Must match old_resource_id.
• old_resource_id (str) (required): ID of the resource the role applies to (that is, either an organization, location, or robot ID).
• new_identity_id (str) (required): New ID of the entity the role belongs to (for example, a user ID).
• new_role (Literal[‘owner’] | Literal[‘operator’]) (required): The new role.
• new_resource_type (Literal[‘organization’] | Literal[’location’] | Literal[‘robot’]) (required): Type of the resource to add role to. Must match new_resource_id.
• new_resource_id (str) (required): New ID of the resource the role applies to (that is, either an organization, location, or robot ID).

Returns:

• None.

Example:

await cloud.change_role(
    organization_id="<YOUR-ORG-ID>",
    old_identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
    old_role="operator",
    old_resource_type="location",
    old_resource_id="111ab12345",
    new_identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
    new_role="owner",
    new_resource_type="organization",
    new_resource_id="abc12345"
)

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to list authorizations for.
• resource_ids (List[str]) (optional): IDs of the resources to retrieve authorizations from. If None, defaults to all resources.

Returns:

• (List[viam.proto.app.Authorization]): The list of authorizations.

Raises:

• (GRPCError): If an invalid resource ID is passed.

Example:

list_of_auths = await cloud.list_authorizations(
    org_id="<YOUR-ORG-ID>",
    resource_ids=["1a123456-x1yz-0ab0-a12xyzabc"])

For more information, see the Python SDK Docs.

Parameters:

• permissions (List[viam.proto.app.AuthorizedPermissions]) (required): the permissions to validate (for example, “read_organization”, “control_robot”).

Returns:

• (List[viam.proto.app.AuthorizedPermissions]): The permissions argument, with invalid permissions filtered out.

Raises:

• (GRPCError): If the list of permissions to validate is empty.

Example:

from viam.proto.app import AuthorizedPermissions

# Check whether the entity you're currently authenticated to has permission to control and/or
# read logs from robots in the "organization-identifier123" org
permissions = [AuthorizedPermissions(resource_type="organization",
                                     resource_id="<YOUR-ORG-ID>",
                                     permissions=["control_robot",
                                                  "read_robot_logs"])]

filtered_permissions = await cloud.check_permissions(permissions)

Valid arguments for permissions are as follows:

"read_organization"
"write_organization"
"read_fragment"
"write_fragment"
"read_location"
"write_location"
"read_location_secret"
"read_robot_secret"
"read_robot"
"read_robot_config"
"read_robot_logs"
"write_robot"
"control_robot"
"read_organization_data_management"
"read_location_data_management"
"read_robot_data_management"
"write_organization_data_management"
"write_location_data_management"
"write_robot_data_management"
"read_robot_history"
"read_mapping_sessions"
"create_maps"
"write_private_registry_item"
"write_public_registry_item"
"read_private_registry_item"
"train_models"
"read_packages"
"write_packages"
"delete_packages"
"configure_database_user"
"get_database_connection"
"create_dataset"
"list_dataset"
"rename_dataset"
"delete_dataset"

For more information about managing permissions, see Role-Based Access Control.

For more information, see the Python SDK Docs.

Parameters:

• item_id (str) (required): The ID of the registry item. This is the namespace and name of the item in the form namespace:name. For example, Viam’s csi-cam-pi module’s item ID would be viam:csi-cam-pi. You can also use org-id:name. For example, abc01234-0123-4567-ab12-a11a00a2aa22:training-script.

Returns:

• (viam.proto.app.RegistryItem): The registry item.

Example:

item = await cloud.get_registry_item("item-id")

For more information, see the Python SDK Docs.

Parameters:

• organization_id (str) (required): The organization to create the registry item under.
• name (str) (required): The name of the registry item, which must be unique within your org.
• type (viam.proto.app.packages.PackageType.ValueType) (required): The type of the item in the registry.

Returns:

• None.

Example:

from viam.proto.app.packages import PackageType

await cloud.create_registry_item("<YOUR-ORG-ID>", "name", PackageType.PACKAGE_TYPE_ML_MODEL)

For more information, see the Python SDK Docs.

Parameters:

• item_id (str) (required): The ID of the registry item, containing either the namespace and module name (for example, my-org:my-module) or organization ID and module name (org-id:my-module).
• type (viam.proto.app.packages.PackageType.ValueType) (required): The type of the item in the registry.
• description (str) (required): The description of the registry item.
• visibility (viam.proto.app.Visibility.ValueType) (required): The visibility of the registry item.

Returns:

• None.

Example:

from viam.proto.app.packages import PackageType
from viam.proto.app import Visibility

await cloud.update_registry_item(
    "your-namespace:your-name",
    PackageType.PACKAGE_TYPE_ML_TRAINING,
    "description",
    Visibility.VISIBILITY_PUBLIC
)

For more information, see the Python SDK Docs.

Parameters:

• organization_id (str) (required): The ID of the organization to return registry items for.
• types (List[viam.proto.app.packages.PackageType.ValueType]) (required): The types of registry items.
• visibilities (List[viam.proto.app.Visibility.ValueType]) (required): The visibilities of registry items.
• platforms (List[str]) (required): The platforms of registry items.
• statuses (List[viam.proto.app.RegistryItemStatus.ValueType]) (required): The types of the items in the registry.
• search_term (str) (optional): The search term of the registry items.
• page_token (str) (optional): The page token of the registry items.

Returns:

• (List[viam.proto.app.RegistryItem]): The list of registry items.

Example:

from viam.proto.app.packages import PackageType
from viam.proto.app import Visibility, RegistryItemStatus

# List private, published ml training scripts in your organization
registry_items = await cloud.list_registry_items(
    organization_id="<YOUR-ORG-ID>",
    types=[PackageType.PACKAGE_TYPE_ML_TRAINING],
    visibilities=[Visibility.VISIBILITY_PRIVATE],
    platforms=[""],
    statuses=[RegistryItemStatus.REGISTRY_ITEM_STATUS_PUBLISHED]
)

# List public, published linux modules in all organizations
registry_items = await cloud.list_registry_items(
    organization_id="",
    types=[PackageType.PACKAGE_TYPE_MODULE],
    visibilities=[Visibility.VISIBILITY_PUBLIC],
    platforms=["linux/any"],
    statuses=[RegistryItemStatus.REGISTRY_ITEM_STATUS_PUBLISHED]
)

For more information, see the Python SDK Docs.

Parameters:

• item_id (str) (required): The ID of the deleted registry item, containing either the namespace and module name (for example, my-org:my-module) or organization ID and module name (org-id:my-module).

Returns:

• None.

Example:

await cloud.delete_registry_item("your-namespace:your-name")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to create the module under. You can obtain your organization ID from the Viam app’s organization settings page.
• name (str) (required): The name of the module. Must be unique within your organization.

Returns:

• (Tuple[str, str]): A tuple containing the ID [0] of the new module and its URL [1].

Raises:

• (GRPCError): If an invalid name (for example, “”) is passed.

Example:

new_module = await cloud.create_module(org_id="org-id", name="cool_new_hoverboard_module")
print("Module ID:", new_module[0])

For more information, see the Python SDK Docs.

Parameters:

• module_id (str) (required): ID of the module being updated, containing either the namespace and module name (for example, my-org:my-module) or organization ID and module name (org-id:my-module).
• url (str) (required): The url to reference for documentation and code (NOT the url of the module itself).
• description (str) (required): A short description of the module that explains its purpose.
• models (List[viam.proto.app.Model]) (optional): list of models that are available in the module.
• entrypoint (str) (required): The executable to run to start the module program.
• public (bool) (required): The visibility that should be set for the module. Defaults to False (private).

Returns:

• (str): The URL of the newly updated module.

Raises:

• (GRPCError): If either an invalid module ID, URL, list of models, or organization ID is passed.

Example:

from viam.proto.app import Model

model = Model(
    api="rdk:component:base",
    model="my-group:cool_new_hoverboard_module:wheeled"
)

url_of_my_module = await cloud.update_module(
    module_id="my-group:cool_new_hoverboard_module",
    url="https://docsformymodule.viam.com",
    models=[model],
    description="A base to support hoverboards.",
    entrypoint="exec"
)

For more information, see the Python SDK Docs.

Parameters:

• module_file_info (viam.proto.app.ModuleFileInfo) (optional): Relevant metadata.
• file (bytes) (required): Bytes of file to upload.

Returns:

• (str): URL of uploaded file.

Example:

from viam.proto.app import ModuleFileInfo

module_file_info = ModuleFileInfo(
    module_id = "sierra:cool_new_hoverboard_module",
    version = "1.0.0",
    platform = "darwin/arm64"
)

file_id = await cloud.upload_module_file(
    module_file_info=module_file_info,
    file=b"<file>"
)

For more information, see the Python SDK Docs.

Parameters:

• module_id (str) (required): ID of the module being retrieved, containing either the namespace and module name (for example, my-org:my-module) or organization ID and module name (org-id:my-module).

Returns:

• (viam.proto.app.Module): The module.

Raises:

• (GRPCError): If an invalid module ID is passed.

Example:

the_module = await cloud.get_module(module_id="my-group:my-cool-modular-base")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to list modules for. You can obtain your organization ID from the Viam app’s organization settings page.

Returns:

• (List[viam.proto.app.Module]): The list of modules.

Example:

modules_list = await cloud.list_modules("<YOUR-ORG-ID>")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to create the key for. You can obtain your organization ID from the Viam app’s organization settings page.
• authorizations (List[APIKeyAuthorization]) (required): A list of authorizations to associate with the key.
• name (str) (optional): A name for the key. If None, defaults to the current timestamp.

Returns:

• (Tuple[str, str]): The api key and api key ID.

Raises:

• (GRPCError): If the authorizations list is empty.

Example:

from viam.app.app_client import APIKeyAuthorization

auth = APIKeyAuthorization(
    role="owner",
    resource_type="robot",
    resource_id="your-machine-id123"
)

api_key, api_key_id = cloud.create_key(
    org_id="<YOUR-ORG-ID>",
    authorizations=[auth],
    name="my_key"
)

For more information, see the Python SDK Docs.

Parameters:

• id (str) (required): The ID of the API key.

Returns:

• None.

Example:

await cloud.delete_key("key-id")

For more information, see the Python SDK Docs.

Parameters:

• id (str) (required): The ID of the key to be rotated.

Returns:

• (Tuple[str, str]): The API key and API key id.

Example:

id, key = await cloud.rotate_key("key-id")

For more information, see the Python SDK Docs.

Parameters:

• org_id (str) (required): The ID of the organization to list API keys for. You can obtain your organization ID from the Viam app’s organization settings page.

Returns:

• (List[viam.proto.app.APIKeyWithAuthorizations]): The existing API keys and authorizations.

Example:

keys = await cloud.list_keys(org_id="<YOUR-ORG-ID>")

For more information, see the Python SDK Docs.

Parameters:

• id (str) (required): the ID of the API key to duplication authorizations from.

Returns:

• (Tuple[str, str]): The API key and API key id.

Example:

api_key, api_key_id = await cloud.create_key_from_existing_key_authorizations(
    id="INSERT YOUR API KEY ID")

For more information, see the Python SDK Docs.