Manage Your Fleet with Viam's Fleet Management API

Parameters:

• None

Returns:

• (List[viam.proto.app.Organization]): A list of the organization or organizations of which the user is an authorized owner.

org_list = await fleet.list_organizations()

For more information, see the Python SDK Docs.

Parameters:

• None

Returns:

• (Tuple[List[viam.proto.app.OrganizationMember]], List[viam.proto.app.OrganizationInvite]): A tuple containing two lists:
  • The first ([0]) is a list of organization members.
  • The second ([1]) is a list of organization invites.

member_list, invite_list = await fleet.list_organization_members()

For more information, see the Python SDK Docs.

Parameters:

• public_namespace (string): The organization namespace to check. Namespaces can only contain lowercase alphanumeric and dash characters.

Raises:

• GRPCError: This error is raised if an invalid namespace (for example, "") is provided.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• email (string): Email of the user the invite was sent to.
• add_authorizations (Optional[List[viam.proto.app.Authorization]]): Optional list of authorizations to add to the invite.
• remove_authorizations (Optional[List[viam.proto.app.Authorization]]): Optional list of authorizations to remove from the invite.

Raises:

• GRPCError: This error is raised 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).

Returns:

• (OrganizationInvite): The updated invitation.

from viam.proto.app import Authorization

authorization_to_add = Authorization(
    authorization_type="some type of auth",
    authorization_id="identifier",
    resource_type="abc",
    resource_id="resource-identifier123",
    identity_id="id12345",
    organization_id="org_id_123"
)

update_invite = await fleet.update_organization_invite_authorizations(
    email="notarealemail@viam.com",
    add_authorizations=[authorization_to_add]
)

For more information, see the Python SDK Docs.

Parameters:

• name (string): Name of the new location.
• parent_location_id (Optional[string]): Optional parent location to put the location under. Defaults to creating a location in your organization at root level if you do not provide a location ID.

Raises:

• GRPCError: This error is raised if an invalid name (such as “”) or invalid parent location ID is passed.

Returns:

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

my_new_location = await fleet.create_location(name="Robotville",
                                              parent_location_id="111ab12345")

For more information, see the Python SDK Docs.

Parameters:

• location_id (Optional[string]): ID of the location to get. Defaults to the location ID provided at AppClient instantiation.

Raises:

• GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

• (viam.proto.app.Location): The location corresponding to the provided ID.

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

For more information, see the Python SDK Docs.

Parameters:

• location_id (string): ID of the location to update.
• name Optional(string): Optional new name to update the location name to. If nothing is passed, the name is not changed.
• parent_location_id Optional(string): Optional ID of the new location to move the location to. If nothing is passed, the location does not move. If an empty string is passed, the location moves up to the top level.

Raises:

• GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

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

# 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 fleet.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 fleet.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 fleet.update_location(
    location_id="abc12abcde",
    name="",
    parent_location_id=""
)

For more information, see the Python SDK Docs.

Parameters:

• location_id (string): ID of the location to delete.

Raises:

• GRPCError: This error is raised if an invalid location ID is passed.

Returns:

• None

await fleet.delete_location(location_id="abc12abcde")

For more information, see the Python SDK Docs.

Parameters:

• None

Returns:

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

locations = await fleet.list_locations()

For more information, see the Python SDK Docs.

Parameters:

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

Raises:

• GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• location_id (Optional[string]): ID of the location to generate a new secret for. Defaults to the location ID provided at AppClient instantiation.

Raises:

• GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

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

new_loc_auth = await fleet.create_location_secret()

For more information, see the Python SDK Docs.

Parameters:

• location_id (string): ID of the location to delete the secret from. Defaults to the location ID provided at AppClient instantiation.
• secret_id (string): The id of the secret to delete (not the secret string itself).

Raises:

• GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

await fleet.delete_location_secret(
    secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz")

For more information, see the Python SDK Docs.

Parameters:

• robot_id (string): ID of the machine to get.

Raises:

• GRPCError: This error is raised if an invalid robot ID is passed.

Returns:

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

robot = await fleet.get_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")

For more information, see the Python SDK Docs.

Parameters:

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

Raises:

• GRPCError: This error is raised if an invalid robot ID is passed.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to get.
• dest (Optional[string]): Optional filepath to write the machine part’s config in JSON format to.
• indent (int): Size (in number of spaces) of indent when writing the JSON config to dest. Defaults to 4.

Returns:

• (viam.app.app_client.RobotPart): The machine part.

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to get logs from. See Find part ID for instructions on retrieving this value.
• filter (Optional[string]): Only include logs with messages that contain the string filter. Defaults to empty string "", meaning no filter.
• dest (Optional[string]): Optional filepath to write the log entries to.
• errors_only (bool): (Optional) Specifies whether to limit returned log messages to error logs only. Defaults to True, including only error-level messages by default.
• num_log_entries (int): 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.

Raises:

• GRPCError: This error is raised if an invalid robot part ID is passed.

Returns:

• (string): The list of log entries.

part_logs = await fleet.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 (string): ID of the machine part to retrieve logs from.
• errors_only (bool): (Optional) Specifies whether to limit returned log messages to error logs only. Defaults to True, including only error-level messages by default.
• filter (Optional[string]): Only include logs with messages that contain the string filter. Defaults to empty string "", meaning no filter.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to retrieve history from. See Find part ID for instructions on retrieving this value.

Raises:

• GRPCError: This error is raised if an invalid machine part ID is passed.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to update. See Find part ID for instructions on retrieving this value.
• name (string): New name to be updated on the machine part.
• robot_config (Mapping[str, Any]): Optional new config represented as a dictionary to be updated on the machine part. The machine part’s config remains unchanged if a new robot_config is not passed.

Raises:

• GRPCError: This error is raised if an invalid machine part ID, name, or config is passed.

Returns:

• (viam.app.app_client.RobotPart): The newly updated machine part.

my_robot_part = await fleet.update_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

Parameters:

• robot_id (string): ID of the machine to create a new part for.
• part_name (Optional[string]): Name of the new part.

Raises:

• GRPCError: This error is raised if an invalid machine ID is passed.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

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

Raises:

• GRPCError: This error is raised if an invalid machine part ID is passed.

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to mark as main. See Find part ID for instructions on retrieving this value.

Raises:

• GRPCError: This error is raised if an invalid machine part ID is passed.

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to mark for restart. See Find part ID for instructions on retrieving this value.

Raises:

• GRPCError: This error is raised if an invalid machine part ID is passed.

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to create a secret for. See Find part ID for instructions on retrieving this value.

Raises:

• GRPCError: This error is raised if an invalid machine part ID is passed.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• robot_part_id (string): ID of the machine part to delete the secret from. See Find part ID for instructions on retrieving this value.
• secret_id (Optional[string]): ID of the secret to delete.

Raises:

• GRPCError: This error is raised if an invalid machine part ID or secret ID is passed.

await fleet.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 (string): ID of the location to retrieve the machines from.

Raises:

• GRPCError: This error is raised if an invalid location ID is passed.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• name (string): Name of the new machine.
• location_id (Optional[string]): ID of the location to create the new machine in. Defaults to the current authorized location.

Raises:

• GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

• (string): The new machine’s ID.

new_machine_id = await fleet.new_robot(name="beepboop")

For more information, see the Python SDK Docs.

Parameters:

• robot_id (string): ID of the machine to update.
• name (string): New name for the machine.
• location_id (Optional[string]): ID of the location in which the machine exists. Defaults to the location ID provided at AppClient instantiation.

Raises:

• GRPCError: This error is raised if an invalid machine ID, name, or location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation. Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• robot_id (string): ID of the machine to delete.

Raises:

• GRPCError: This error is raised if an invalid machine ID is passed.

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

For more information, see the Python SDK Docs.

Parameters:

• show_public (bool): (Optional) Specify whether to only show public fragments. If True, only public fragments will be returned. If False, only private fragments will be returned. Default: True.

Returns:

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

fragments_list = await fleet.list_fragments(show_public=False)

For more information, see the Python SDK Docs.

Parameters:

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

Raises:

• GRPCError: This error is raised if an invalid fragment ID is passed.

Returns:

• (viam.app.app_client.Fragment): The fragment.

# Get a fragment and print its name and when it was created.
the_fragment = await fleet.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:

• name (string): Name of the new fragment.
• config (Optional[Mapping[str, Any]]): Dictionary representation of the new config to assign to the fragment. Can be assigned by updating the fragment.

Raises:

• GRPCError: This error is raised if an invalid name is passed.

Returns:

• (viam.app.app_client.Fragment): The newly created fragment.

new_fragment = await fleet.create_fragment(
  name="cool_smart_machine_to_configure_several_of")

For more information, see the Python SDK Docs.

Parameters:

• fragment_id (string): ID of the fragment to update.
• name (string): New name to associate with the fragment.
• config (Optional[Mapping[str, Any]]): Dictionary representation of the new config to assign to the fragment. Not passing this parameter will leave the fragment’s config unchanged.
• public (bool): Specify whether the fragment is public. Default: False (private).

Raises:

• GRPCError: This error is raised if an invalid fragment ID, name, or config is passed.

Returns:

• (viam.app.app_client.Fragment): The newly updated fragment.

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

For more information, see the Python SDK Docs.

Parameters:

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

Raises:

• GRPCError: This error is raised if an invalid fragment ID is passed.

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

For more information, see the Python SDK Docs.

Parameters:

• identity_id (string): ID of the entity the role belongs to (for example, a user ID).
• role (string): The role to add (either "owner" or "operator").
• resource_type (string): 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 (string): ID of the resource the role applies to (the ID of either an organization, location, or machine.)

Raises:

• GRPCError: This error is raised if an invalid identity ID, role, resource type, or resource ID is passed.

await fleet.add_role(
  identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
  role="owner",
  resource_type="location",
  resource_id="111ab12345")

For more information, see the Python SDK Docs.

Parameters:

• identity_id (string): ID of the entity the role belongs to (for example, a user ID).
• role (string): The role to remove (either "owner" or "operator").
• resource_type (string): The type of the resource to remove the role from (either "organization", "location", or "robot"). Must match the type of the resource_id’s resource.
• resource_id (string): ID of the resource the role applies to (the ID of either an organization, location, or machine.)

Raises:

• GRPCError: This error is raised if an invalid identity ID, role, resource type, or resource ID is passed.

await fleet.remove_role(
  identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
  role="owner",
  resource_type="location",
  resource_id="111ab12345")

For more information, see the Python SDK Docs.

Parameters:

• resource_ids (Optional[List(string)]): IDs of the resources to retrieve authorizations from. Defaults to none.

Raises:

• GRPCError: This error is raised if an invalid resource ID is passed.

Returns:

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

list_of_auths = await fleet.list_authorizations(
  resource_ids=["1a123456-x1yz-0ab0-a12xyzabc"])

For more information, see the Python SDK Docs.

Parameters:

• name (string): The name of the module. Must be unique within your organization.

Raises:

• GRPCError: This error is raised if an invalid name (for example, "") is passed.

Returns:

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

new_module = await fleet.create_module(name="cool_new_hoverboard_module")
print("Module ID:", new_module[0])

For more information, see the Python SDK Docs.

Parameters:

• module_id (string): ID of the module being updated, containing module name (for example, "my-module") or namespace and module name (for example, "my-org:my-module").
• url (string): The URL to reference for documentation and code (not the URL of the module itself).
• description (string): A short description of the module that explains its purpose.
• models (Optional[List[viam.proto.app.Model]]): List of models that are available in the module.
• entrypoint (string): The executable to run to start the module program.
• public (bool): Set the visibility of the module. Defaults to False (private).

Raises:

• GRPCError: This error is raised if an invalid module ID, URL, list of models, or organization ID is passed.

Returns:

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

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

For more information, see the Python SDK Docs.

Parameters:

• module_file_info (Optional[viam.proto.app.ModuleFileInfo]): Relevant metadata.
• file (bytes): Bytes of file to upload.

Returns:

• (string): ID of the uploaded file.

file_id = await fleet.upload_module_file(file=b"<file>")

For more information, see the Python SDK Docs.

Parameters:

• module_id (string): ID of the module being retrieved, containing module name (for example, "my-module") or namespace and module name (for example, "my-org:my-module").

Raises:

• GRPCError: This error is raised if an invalid module ID is passed.

Returns:

• (string): The module.

the_module = await fleet.get_module(module_id="my-cool-modular-base")

For more information, see the Python SDK Docs.

Raises:

• GRPCError: This error is raised if an invalid machine ID is passed.

Returns:

• (string): The list of modules.

modules_list = await fleet.list_modules()

For more information, see the Python SDK Docs.

Create an organization invite and send it by email.

Parameters:

• email (str): The email address to send the invite to.
• authorizations (Optional[List[viam.proto.app.Authorization]]): Authorizations to include in the invite. If not provided, full owner permissions will be granted.

Returns:

• None.

Raises:

• GRPCError: This error is raised if an invalid email is provided, or if the user is already a member of the org.

await fleet.create_organization_invite("youremail@email.com")

For more information, see the Python SDK Docs.

Remove a member from the organization you are currently authenticated to.

Parameters:

• user_id (str): The ID of the user to remove.

Returns:

• None.

member_list, invite_list = await fleet.list_organization_members()
first_user_id = member_list[0].user_id

await fleet.delete_organization_member(first_user_id)

For more information, see the Python SDK Docs.

Delete a pending organization invite to the organization you are currently authenticated to.

Parameters:

• email (str): The email address the pending invite was sent to.

Returns:

• None.

Raises:

• GRPCError: This error is raised if no pending invite is associated with the provided email address.

await fleet.delete_organization_invite("youremail@email.com")

For more information, see the Python SDK Docs.

Resend a pending organization invite email.

Parameters:

• email (str): The email address associated with the invite.

Returns:

• None.

Raises:

• GRPCError: This error is raised if no pending invite is associated with the provided email address.

await fleet.resend_organization_invite("youremail@email.com")

For more information, see the Python SDK Docs.

Return a list of rover rental robots within an organization.

Parameters:

• None.

Returns:

• (List[viam.proto.app.RoverRentalRobot]): The list of rover rental robots.

rental_robots = await fleet.get_rover_rental_robots()

For more information, see the Python SDK Docs.

Check if the organization, location, or robot your ViamClient is authenticated to is permitted to perform some action or set of actions on the resource you pass to the method.

Parameters:

• permissions (List[viam.proto.app.AuthorizedPermissions]): A list containing the resource type and ID, followed by the resource permissions to check.

Returns:

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

Raises:

• GRPCError: This error is raised if the list of permissions to validate is empty.

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="organization-identifier123",
                                     permissions=["control_robot",
                                                  "read_robot_logs"])]

filtered_permissions = await fleet.check_permissions(permissions)

For more information, see the Python SDK Docs.

Create a new API key.

Parameters:

• authorizations (List[APIKeyAuthorization]): A list of authorizations to associate with the key.
• name (Optional[str]): 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: This error is raised if the authorizations list is empty.

from viam.app.app_client import APIKeyAuthorization

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

api_key, api_key_id = fleet.create_key([auth], "my_key")

For more information, see the Python SDK Docs.

Create a new API key with an existing key’s authorizations.

Parameters:

• id (str): The ID of the API key to duplicate authorizations from.

Returns:

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

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

For more information, see the Python SDK Docs.

List all keys for the organization that you are currently authenticated to.

Parameters:

• None.

Returns:

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

keys = fleet.list_keys()

For more information, see the Python SDK Docs.