Manage Your Fleet with Viam's Cloud API

The cloud app API allows you to manage your smart machine fleet with code instead of with the graphical interface of the Viam app. With it you can

create and manage organizations, locations, and individual smart machines
manage permissions and authorization
create and manage fragments

Support Notice

Cloud app API methods are only available in the Python SDK.

Establish a connection

To use the Viam cloud app API, you first need to instantiate a ViamClient and then instantiate an AppClient. See the following example for reference. To find the location secret, go to Viam app, and go to the Code sample tab of any of the robots in the location. Toggle Include secret on and copy the payload. For the URL, use the address of any of the robots in the location (also found on the Code sample tab).

import asyncio

from viam.rpc.dial import DialOptions, Credentials
from viam.app.viam_client import ViamClient


async def connect() -> ViamClient:
    dial_options = DialOptions(
        # The URL of any robot in the location.
        auth_entity='beepboop-main.YOUR LOCATION ID.viam.cloud',
        credentials=Credentials(
            type='robot-location-secret',
            # The location secret
            payload='YOUR LOCATION SECRET'
        )
    )
    return await ViamClient.create_from_dial_options(dial_options)


async def main():

    # Make a ViamClient
    viam_client = await connect()
    # Instantiate an AppClient called "cloud" to run cloud app API methods on
    cloud = viam_client.app_client

    viam_client.close()

if __name__ == '__main__':
    asyncio.run(main())

Once you have instantiated an AppClient, you can run the following API methods against the AppClient object (named cloud in the examples).

API

The cloud API supports the following methods (among others):

Method Name	Description
`ListOrganizations`	List the organizations the user owns.
`GetOrganizationNamespaceAvailability`	Check the availability of an organization namespace.
`ListOrganizationMembers`	List the members and invites of the current organization.
`UpdateOrganizationInviteAuthorizations`	Update the authorizations attached to an organization invite that has already been created.
`CreateLocation`	Create and name a location.
`GetLocation`	Get a location by its ID.
`UpdateLocation`	Change the name of and/or assign a parent location to a location.
`DeleteLocation`	Delete a location.
`ListLocations`	List locations.
`LocationAuth`	Get a location’s authorization (location secrets).
`CreateLocationSecret`	Create a new location secret.
`DeleteLocationSecret`	Delete a location secret.
`GetRobot`	Get a robot by robot ID.
`GetRobotParts`	Get a list of all the parts under a specific robot.
`GetRobotPart`	Get a robot part.
`GetRobotPartLogs`	Get the logs associated with a robot part.
`TailRobotPartLogs`	Get an asynchronous iterator that receives live robot part logs.
`GetRobotPartHistory`	Get a list containing the history of a robot part.
`UpdateRobotPart`	Update the name or configuration of a robot part.
`NewRobotPart`	Create a new robot part.
`DeleteRobotPart`	Delete a robot part.
`NewRobot`	Create a new robot.

ListOrganizations

List the organizations the user is an authorized user of.

Python

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 cloud.list_organizations()

For more information, see the Python SDK Docs.

ListOrganizationMembers

List the members and invites of the organizations that you are currently authenticated to.

Python

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 cloud.list_organization_members()

For more information, see the Python SDK Docs.

GetOrganizationNamespaceAvailability

Check the availability of an organization namespace.

Python

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 cloud.get_organization_namespace_availability(
    public_namespace="my-cool-organization")

For more information, see the Python SDK Docs.

UpdateOrganizationInviteAuthorizations

Update (add or remove) the authorizations attached to an organization invite that has already been created. If an invitation has only one authorization and you want to remove it, delete the invitation instead of using this method.

Python

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 cloud.update_organization_invite_authorizations(
    email="notarealemail@viam.com",
    remove_authorizations=[authorization_to_add]
)

For more information, see the Python SDK Docs.

CreateLocation

Create and name a location under the organization you are currently authenticated to. Optionally, put the new location under a specified parent location.

Python

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 cloud.create_location(name="Robotville",
                                              parent_location_id="111ab12345")

For more information, see the Python SDK Docs.

GetLocation

Get a location by its location ID.

Python

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 cloud.get_location(location_id="123ab12345")

For more information, see the Python SDK Docs.

UpdateLocation

Change the name of a parent location and/or assign it a new location.

Python

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 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.

DeleteLocation

Delete a location.

Python

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 cloud.delete_location(location_id="abc12abcde")

For more information, see the Python SDK Docs.

ListLocations

Get a list of all locations under the organization you are currently authenticated to.

Python

Parameters:

None

Returns:

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

locations = await cloud.list_locations()

For more information, see the Python SDK Docs.

LocationAuth

Get a location’s LocationAuth (location secret or secrets).

Python

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 cloud.location_auth(location_id="123xy12345")

For more information, see the Python SDK Docs.

CreateLocationSecret

Create a new location secret.

Python

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 cloud.create_location_secret()

For more information, see the Python SDK Docs.

DeleteLocationSecret

Delete a location secret.

Python

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 cloud.delete_location_secret(
    secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz")

For more information, see the Python SDK Docs.

GetRobot

Get a robot by its ID.

Python

Parameters:

robot_id (string): ID of the robot to get.

Raises:

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

Returns:

(viam.proto.app.Robot): The robot.

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

For more information, see the Python SDK Docs.

GetRobotParts

Get a list of all the parts under a specific robot.

Python

Parameters:

robot_id (string): ID of the robot 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 robot parts.

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

For more information, see the Python SDK Docs.

GetRobotPart

Get a specific robot part.

Python

Parameters:

robot_part_id (string): ID of the robot part to get.
dest (Optional[string]): Optional filepath to write the robot 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.

Raises:

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

Returns:

(viam.app.app_client.RobotPart): The robot part.

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

For more information, see the Python SDK Docs.

GetRobotPartLogs

Get the logs associated with a specific robot part.

Python

Parameters:

robot_part_id (string): ID of the robot part to get logs from.
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): 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 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.

TailRobotPartLogs

Get an asynchronous iterator that receives live robot part logs.

Python

Parameters:

robot_part_id (string): ID of the robot part to retrieve logs from.
errors_only (bool): 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 robot part logs.

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

For more information, see the Python SDK Docs.

GetRobotPartHistory

Get a list containing the history of a robot part.

Python

Parameters:

robot_part_id (string): ID of the robot part to retrieve history from.

Raises:

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

Returns:

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

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

For more information, see the Python SDK Docs.

UpdateRobotPart

Change the name of and assign an optional new configuration to a robot part.

Python

Parameters:

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

Raises:

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

Returns:

(viam.app.app_client.RobotPart): The newly-updated robot part.

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

For more information, see the Python SDK Docs.

NewRobotPart

Create a new robot part.

Python

Parameters:

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

Raises:

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

Returns:

(string): The new robot part’s ID.

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.

DeleteRobotPart

Delete the specified robot part.

Python

Parameters:

robot_part_id (string): ID of the robot part to delete.

Raises:

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

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

For more information, see the Python SDK Docs.

NewRobot

Create a new robot.

Python

Parameters:

name (string): Name of the new robot.
location_id (Optional[string]): ID of the location to create the new robot 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 robot’s ID.

new_robot_id = await cloud.new_robot(name="beepboop")

For more information, see the Python SDK Docs.

Have questions, or want to meet other people working on robots? Join our Community Discord.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!