More API Examples

Below are a few more examples of using the Horizon API to perform common asset management operations.

Obtaining the Asset Root ID

When creating or listing assets using the API, you must provide the ID of the parent container as a parameter. It is therefore useful to know the ID of the asset database root so that you can start using these other API functions. The root ID can be obtained with a GET request to /api/user/context. The asset root ID can be found in the response JSON as "rid".

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

json=$(curl "$url/api/user/context" --header "Authorization: Bearer $token" --silent)

echo $json | grep -o '"rid":"[^"]*' | grep -o '[^"]*$'

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$uri = "$url/api/user/context"
$header = @{
    "Authorization" = "Bearer $token"
}

$json = Invoke-RestMethod -Uri $uri -Method Get -Headers $header

Write-Output $json.space.rid

Obtaining Available Asset Type IDs

In addition to the ID of the parent container, creating an asset also requires you to provide the ID for the asset type you would like to create. The IDs for all asset types available within a specified container can be obtained with a GET request to api/asset/listTypes/{parent-id}. The result will include the name and ID for each available asset type.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

parent_id=4d1946f9-8aa3-4e89-8b6a-fa835969fc1d  # ID of the parent container

curl "$url/api/asset/listTypes/$parent_id" --header "Authorization: Bearer $token"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$parentID = "4d1946f9-8aa3-4e89-8b6a-fa835969fc1d"  # ID of the parent container

$uri = "$url/api/asset/listTypes/$parentID"
$header = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri $uri -Method Get -Headers $header

Creating a Container

With the asset ID of the parent container and the type ID of the container asset type, you can create a new container with a POST request to /api/asset/createAsset/{parent-id}/{type-id}. The request body should be a JSON with a name attribute and an optional description attribute. The response of this request will contain the asset ID of the newly created container.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

parent_id=4d1946f9-8aa3-4e89-8b6a-fa835969fc1d  # ID of parent container
type_id=0355211d-7ab0-4990-883b-0fdd24dbf9e3    # ID of the container asset type

name="My Container"
description="A container created with the Horizon REST API"

curl "$url/api/asset/createAsset/$parent_id/$type_id" --request POST --header "Authorization: Bearer $token" --header "Content-Type: application/json" --data "{\"name\": \"$name\",\"description\": \"$description\"}"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$parentID = "4d1946f9-8aa3-4e89-8b6a-fa835969fc1d"  # ID of the parent container
$typeID = "0355211d-7ab0-4990-883b-0fdd24dbf9e3"    # ID of the container asset type

$uri = "$url/api/asset/createAsset/$parentID/$typeID"
$header = @{
    "Authorization" = "Bearer $token"
}

$body = @{
    name = "My Container"
    description = "A container created using the Horizon REST API"
} | ConvertTo-Json -Compress

Invoke-RestMethod -Uri $uri -Method Post -Headers $header -Body $body -ContentType "application/json"

Granting Permissions Within a Container

After creating a container, you may want to grant permissions to one or more users to view and manage the assets within it. To do this, you must first make the permissions of the container unique in order to break permission inheritance from its parent. This is done with a PUT request to /api/permission/makeUniqueAsset/{asset-id}. Next, permissions can be granted to users with a PUT request to /api/permission/grantAssetPermission/{asset-id}.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

asset_id=f34b2f85-eaaa-4587-bc4c-339f395d6d93      # ID of the container

curl "$url/api/permission/makeUniqueAsset/$asset_id" --request PUT --header "Authorization: Bearer $token"

directory_id=61fd6ca1-e65d-4ea7-a3af-f99f1cf95038  # Directory ID of the user
entry_id=2dd66b65-f94b-4ae3-9279-316142d875ec      # Entry ID of the user

# Roles for resources and operations within container; options can be found in Horizon UI
asset_role=AssetManager
container_role=ContainerViewer
execute_role=ExecuteNone

curl "$url/api/permission/grantAssetPermission/$asset_id" --request PUT --header "Authorization: Bearer $token" --header "Content-Type: application/json" --data "{\"directoryId\":\"$directory_id\",\"entryId\":\"$entry_id\",\"roles\":[\"$asset_role\",\"$container_role\",\"$execute_role\"]}"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$assetID = "f34b2f85-eaaa-4587-bc4c-339f395d6d93"         # ID of the container

$uri = "$url/api/permission/makeUniqueAsset/$assetID"
$header = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri $uri -Method Put -Headers $header

$uri = "$url/api/permission/grantAssetPermission/$assetID"

$body = @{
    directoryId = "61fd6ca1-e65d-4ea7-a3af-f99f1cf95038"  # Directory ID of the user
    entryId = "2dd66b65-f94b-4ae3-9279-316142d875ec"      # Entry ID of the user
    roles = @(
        # Roles for resources and operations within container; options can be found in Horizon UI
        "AssetManager"
        "ContainerViewer"
        "ExecuteNone"
    )
} | ConvertTo-Json -Compress

Invoke-RestMethod -Uri $uri -Method Put -Headers $header -Body $body -ContentType "application/json"

Tip

The "directoryId" and "entryId" values for a specific user can be obtained with a GET request to /api/user/search.

Listing Contents of a Container

A list of assets within a container can be obtained with a GET request to /api/asset/assets/{asset-id}. The result will include a list of asset maps with a name, description, asset ID, and additional information for each asset in the specified parent container.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

asset_id=f34b2f85-eaaa-4587-bc4c-339f395d6d93  # ID of the parent container

curl "$url/api/asset/assets/$asset_id" --header "Authorization: Bearer $token"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$assetID = "f34b2f85-eaaa-4587-bc4c-339f395d6d93"  # ID of the parent container

$uri = "$url/api/asset/assets/$assetID"
$header = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri $uri -Method Get -Headers $header

Obtaining Asset Field IDs

Creating an asset of a non-container type requires you to define additional fields associated with the asset type. Each of these asset type fields has an ID which must be known in order to set its value through the API. The IDs for each field of a particular asset type can be obtained with a GET request to /api/asset/assetTypeForCreate/{parent-id}/{type-id}. The result will include the name, field ID, and some other properties of each field associated with the specified asset type.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

parent_id=f34b2f85-eaaa-4587-bc4c-339f395d6d93  # ID of the parent container
type_id=c3b42b89-748a-4e3f-a5d3-e367d548ac0a    # ID of the Unix Host asset type

curl "$url/api/asset/assetTypeForCreate/$parent_id/$type_id" --header "Authorization: Bearer $token"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$parentID = "f34b2f85-eaaa-4587-bc4c-339f395d6d93"  # ID of the parent container
$typeID = "c3b42b89-748a-4e3f-a5d3-e367d548ac0a"    # ID of the Unix Host asset type

$uri = "$url/api/asset/assetTypeForCreate/$parentID/$typeID"
$header = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri $uri -Method Get -Headers $header

Creating an Asset

After obtaining the field IDs for the appropriate asset type, you can create a new asset with a POST request to /api/asset/createAsset/{parent-id}/{type-id}. The request body should include the name, description, and all required field values for the asset that will be created. The response of this request will contain the asset ID of the newly created asset.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

parent_id=f34b2f85-eaaa-4587-bc4c-339f395d6d93  # ID of the parent container
type_id=c3b42b89-748a-4e3f-a5d3-e367d548ac0a    # ID of the Unix Host asset type

name="My Unix Host"
description="A Unix Host asset created with the Horizon REST API"

# "Host" field
host_field_id=3dceed39-7da2-4e8e-a6d9-d16275aa05f9
host_value=host.ztna

# "User" field
user_field_id=e629566e-40cd-40ee-a19e-43261f63d0a7
user_value=administrator

# "Password" field
password_field_id=7dbf3780-3b23-4b91-a76f-1dc33c7f109c
password_value=Passw0rd

# "Tags" field
tags_field_id=2d5de4b7-5d52-4992-b409-a54bffe2fb05
tags_value=5cdf8f8e-b863-43da-85ec-e1cea4618a3e # Term ID for Component::Server::Linux

curl "$url/api/asset/createAsset/$parent_id/$type_id" --request POST --header "Authorization: Bearer $token" --header "Content-Type: application/json" --data "{\"name\": \"$name\",\"description\": \"$description\",\"fields\": [{\"field\": {\"id\": \"$host_field_id\"},\"values\": [{\"stringValue\": \"$host_value\"}]},{\"field\": {\"id\": \"$user_field_id\"},\"values\": [{\"stringValue\": \"$user_value\"}]},{\"field\": {\"id\": \"$password_field_id\"},\"values\": [{\"stringValue\": \"$password_value\"}]},{\"field\": {\"id\": \"$tags_field_id\"},\"values\": [{\"stringValue\": \"$tags_value\"}]}]}"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$parentID = "f34b2f85-eaaa-4587-bc4c-339f395d6d93"  # ID of the parent container
$typeID = "c3b42b89-748a-4e3f-a5d3-e367d548ac0a"    # ID of the Unix Host asset type

$uri = "$url/api/asset/createAsset/$parentID/$typeID"
$header = @{
    "Authorization" = "Bearer $token"
}

$body = @{
    name = "My Unix Host"
    description = "A Unix Host asset created with the Horizon REST API"
    fields = @(
        @{
            # "Host" field
            field = @{ id = "3dceed39-7da2-4e8e-a6d9-d16275aa05f9" }
            values = @(@{ stringValue = "host.ztna" })
        },
        @{
            # "User" field
            field = @{ id = "e629566e-40cd-40ee-a19e-43261f63d0a7" }
            values = @(@{ stringValue = "administrator" })
        },
        @{
            # "Password" field
            field = @{ id = "7dbf3780-3b23-4b91-a76f-1dc33c7f109c" }
            values = @(@{ stringValue = "Passw0rd" })
        },
        @{
            # "Tags" field
            field = @{ id = "2d5de4b7-5d52-4992-b409-a54bffe2fb05" }
            values = @(@{ stringValue = "5cdf8f8e-b863-43da-85ec-e1cea4618a3e" }) # Term ID for Component::Server::Linux
        }
    )
} | ConvertTo-Json -Compress -Depth 5

Invoke-RestMethod -Uri $uri -Method Post -Headers $header -Body $body -ContentType "application/json"

Tip

When defining the "Tags" field of an asset, taxonomy terms must be referenced by their term IDs. These can be obtained with a GET request to /api/taxonomy/search/{taxonomy-id}.

Updating an Asset

An existing asset can be updated with a PUT request to /api/asset/updateAsset/{asset-id}. The request body should match the format of the one used when creating an asset, though only the modified fields need to be provided.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

asset_id=2ae7ce47-179e-40b3-a2de-2e8ca01341fc  # ID of the asset

name="My Modified Unix Host"

# "Host" field
host_field_id=3dceed39-7da2-4e8e-a6d9-d16275aa05f9
host_value=newhost.ztna

curl "$url/api/asset/updateAsset/$asset_id" --request PUT --header "Authorization: Bearer $token" --header "Content-Type: application/json" --data "{\"name\": \"$name\",\"fields\": [{\"field\": {\"id\": \"$host_field_id\"},\"values\": [{\"stringValue\": \"$host_value\"}]}]}"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$assetID = "2ae7ce47-179e-40b3-a2de-2e8ca01341fc"  # ID of the asset

$uri = "$url/api/asset/updateAsset/$assetID"
$header = @{
    "Authorization" = "Bearer $token"
}

$body = @{
    name = "My Modified Unix Host"
    fields = @(
        @{
            # "Host" field
            field = @{ id = "3dceed39-7da2-4e8e-a6d9-d16275aa05f9" }
            values = @(@{ stringValue = "newhost.ztna" })
        }
    )
} | ConvertTo-Json -Compress -Depth 5

Invoke-RestMethod -Uri $uri -Method Put -Headers $header -Body $body -ContentType "application/json"

Promoting an Asset Version

After creating or updating an asset, it can be promoted to its next major version with a POST request to /api/asset/promote/{asset-id}.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

asset_id=2ae7ce47-179e-40b3-a2de-2e8ca01341fc  # ID of the asset

curl "$url/api/asset/promote/$asset_id" --request POST --header "Authorization: Bearer $token"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$assetID = "2ae7ce47-179e-40b3-a2de-2e8ca01341fc"  # ID of the asset

$uri = "$url/api/asset/promote/$assetID"
$header = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri $uri -Method Post -Headers $header

Deleting an Asset

An asset can be deleted with a DELETE request to /api/asset/deleteAsset/{asset-id}.

ShellPowerShell

#!/bin/sh

url=https://horizon.host:6443/ztna/mytenant/root
token=eyJhbGciOiJIUzI1...

asset_id=2ae7ce47-179e-40b3-a2de-2e8ca01341fc  # ID of the asset

curl "$url/api/asset/deleteAsset/$asset_id" --request DELETE --header "Authorization: Bearer $token"

$url = "https://horizon.host/ztna/mytenant/root"
$token = "eyJhbGciOiJIUzI1..."

$assetID = "2ae7ce47-179e-40b3-a2de-2e8ca01341fc"  # ID of the asset

$uri = "$url/api/asset/deleteAsset/$assetID"
$header = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri $uri -Method Delete -Headers $header