DOCS-1088: Document more of the cloud API (#1814)

docs/program/apis/cloud.md

@@ -67,7 +67,7 @@ The cloud API supports the following methods (among [others](https://python.viam
 
 ### ListOrganizations
 
-List the organizations the user is an authorized user of.
+List the {{< glossary_tooltip term_id="organization" text="organizations" >}} the user is an authorized user of.
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -91,7 +91,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 
 ### ListOrganizationMembers
 
-List the members and invites of the organization that you are currently authenticated to.
+List the members and invites of the {{< glossary_tooltip term_id="organization" text="organizations" >}} that you are currently authenticated to.
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -117,7 +117,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 
 ### GetOrganizationNamespaceAvailability
 
-Check the availability of an organization namespace.
+Check the availability of an {{< glossary_tooltip term_id="organization" text="organization" >}} namespace.
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -188,9 +188,289 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 {{% /tab %}}
 {{< /tabs >}}
 
+### CreateLocation
+
+Create and name a {{< glossary_tooltip term_id="location" text="location" >}} under the organization you are currently authenticated to.
+Optionally, put the new location under a specified parent location.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `name` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Name of the new location.
+- `parent_location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): 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)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly created location.
+
+```python {class="line-numbers linkable-line-numbers"}
+my_new_location = await cloud.create_location(name="Robotville", parent_location_id="111ab12345")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.create_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetLocation
+
+Get a {{< glossary_tooltip term_id="location" text="location" >}} by its location ID.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): 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)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.
+
+```python {class="line-numbers linkable-line-numbers"}
+location = await cloud.get_location(location_id="123ab12345")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### UpdateLocation
+
+Change the name of a {{< glossary_tooltip term_id="location" text="parent location" >}} and/or assign it a new location.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to update.
+- `name` [Optional(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional new name to update the location name to.
+If nothing is passed, the name is not changed.
+- `parent_location_id` [Optional(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): 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)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly updated location.
+
+```python {class="line-numbers linkable-line-numbers"}
+# 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](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.update_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### DeleteLocation
+
+Delete a {{< glossary_tooltip term_id="location" text="location" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed.
+
+**Returns:**
+
+- None
+
+```python {class="line-numbers linkable-line-numbers"}
+await cloud.delete_location(location_id="abc12abcde")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.delete_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### ListLocations
+
+Get a list of all {{< glossary_tooltip term_id="location" text="locations" >}} under the organization you are currently authenticated to.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- None
+
+**Returns:**
+
+- (List[[viam.proto.app.Location](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location)]): The list of locations.
+
+```python {class="line-numbers linkable-line-numbers"}
+locations = await cloud.list_locations()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.list_locations).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### LocationAuth
+
+Get a location’s `LocationAuth` (location secret or secrets).
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): 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)](https://python.viam.dev/autoapi/viam/gen/app/v1/app_pb2/index.html#viam.gen.app.v1.app_pb2.LocationAuth): The `LocationAuth` containing location secrets and secret IDs.
+
+```python {class="line-numbers linkable-line-numbers"}
+loc_auth = await cloud.location_auth(location_id="123xy12345")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.location_auth).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### CreateLocationSecret
+
+Create a new location secret.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): 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)](https://python.viam.dev/autoapi/viam/gen/app/v1/app_pb2/index.html#viam.gen.app.v1.app_pb2.LocationAuth): The specified location's `LocationAuth` containing the newly created secret.
+
+```python {class="line-numbers linkable-line-numbers"}
+new_loc_auth = await cloud.create_location_secret()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.create_location_secret).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### DeleteLocationSecret
+
+Delete a location secret.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete the secret from.
+  Defaults to the location ID provided at `AppClient` instantiation.
+- `secret_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): 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.
+
+**Returns:**
+
+- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str):
+
+```python {class="line-numbers linkable-line-numbers"}
+await cloud.delete_location_secret(secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.delete_location_secret).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetRobot
+
+Get a robot by its ID.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot to get.
+
+**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)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The robot.
+
+```python {class="line-numbers linkable-line-numbers"}
+robot = await cloud.get_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_robot).
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ### NewRobot
 
-Create a new robot.
+Create a new {{< glossary_tooltip term_id="robot" text="robot" >}}.
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -213,7 +493,7 @@ Create a new robot.
 new_robot_id = await cloud.new_robot(name="beepboop")
 ```
 
-For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_organization_namespace_availability).
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.new_robot).
 
 {{% /tab %}}
 {{< /tabs >}}

static/include/services/apis/cloud.md

@@ -4,4 +4,13 @@ Method Name | Description
 [`GetOrganizationNamespaceAvailability`](/program/apis/cloud/#getorganizationnamespaceavailability) | Check the availability of an organization namespace.
 [`ListOrganizationMembers`](/program/apis/cloud/#listorganizationmembers) | List the members and invites of the current organization.
 [`UpdateOrganizationInviteAuthorizations`](/program/apis/cloud/#updateorganizationinviteauthorizations) | Update the authorizations attached to an organization invite that has already been created.
-[`NewRobot`](/program/apis/cloud/# ) | Create a new robot.
+[`CreateLocation`](/program/apis/cloud/#createlocation) | Create and name a location.
+[`GetLocation`](/program/apis/cloud/#getlocation) | Get a location by its ID.
+[`UpdateLocation`](/program/apis/cloud/#updatelocation ) | Change the name of and/or assign a parent location to a location.
+[`DeleteLocation`](/program/apis/cloud/#deletelocation ) | Delete a location.
+[`ListLocations`](/program/apis/cloud/#listlocations ) | List locations.
+[`LocationAuth`](/program/apis/cloud/#locationauth ) | Get a location's authorization (location secrets).
+[`CreateLocationSecret`](/program/apis/cloud/#createlocationsecret ) | Create a new location secret.
+[`DeleteLocationSecret`](/program/apis/cloud/#deletelocationsecret ) | Delete a location secret.
+[`GetRobot`](/program/apis/cloud/#getrobot ) | Get a robot by robot ID.
+[`NewRobot`](/program/apis/cloud/#newrobot ) | Create a new robot.