CloudHealth API Guide logo

Getting Started

Welcome

Welcome to the CloudHealth API Guide. Here you’ll find API services that programmatically retrieve data from the CloudHealth Platform.

The CloudHealth API is organized around REST. The API has predictable, resource-oriented URLs, and it uses HTTP response codes to indicate API errors. All API responses, including errors, return JSON.

This API continues to be under development and will evolve. CloudHealth sends information on additions and changes to the API in the Product Updates emails that go out to all customers.

For user guides, FAQs, and product updates, visit the CloudHealth Help Center.

How to Use the CloudHealth API

The goal of the CloudHealth API is to let you write your own applications that leverage and extend CloudHealth functionality.

The CloudHealth API provides programmatic access to functionalities in the CloudHealth platform using REST-based arguments and JSON-formatted responses.

You send REST API requests to various endpoints to retrieve and update data from the CloudHealth Platform. Different API functionality can be found at different endpoints. Here are some example endpoints.

  • https://chapi.cloudhealthtech.com/olap_reports/cost/history
  • https://chapi.cloudhealthtech.com/v1/perspective_schemas

Using the API, you can query the following areas of the CloudHealth Platform.

  • Reporting
  • Asset
  • Account
  • Metrics
  • Tagging
  • Perspectives
  • Partner
  • Partner Customer Provisioning
  • Partner AWS Account Assignment
  • Customer Statement

Anatomy of a Request

Here’s a REST-based request that uses the CloudHealth API.

curl -H 'Authorization: Bearer XXXXX98900000YYYY' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly'

Let’s break down this request.

  • cURL is a command-line REST client (https://curl.haxx.se).
  • The -H flags represent the headers that you need to pass with each request. There are two headers that each request must contain:
    • -H 'Authorization: Bearer XXXXX98900000YYYY' is the authorization header. It attaches your unique API key to the request. Here, XXXXX98900000YYYY is your API Key. See How CloudHealth Validates API Requests.
    • - H 'Accept: application/json' is the communication header. You can also specify this header as -H 'Content-Type:application/json'.
    • The optional header Accept-Encoding:gzip compresses the communication with GZIP compression.
  • https://chapi.cloudhealthtech.com/olap_reports/cost/history is the REST endpoint. In this example, the endpoint returns data for the Standard Cost History Report.
  • If you prefer to pass your API key as a query parameter, instead of using an authorization header, use api_key=XXXXX98900000YYYY to attach your unique API key with the request. Here, XXXXX98900000YYYY is your API Key.
  • interval=monthly is a query parameter that you append to the REST endpoint. Query parameters allow you to constrain the data returned from a request. You can attach multiple query parameter as long as each parameter is separated from the next by the & symbol.
  • A URI string is made up of the REST endpoint and all the query parameters attached to it. In this example, this is the URI string.
    https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly
    

    The maximum permissible length of a URI string is 4000 characters.

Types of Requests

  • GET requests retrieve data from the CloudHealth Platform.
    curl 'https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly'
      -H 'Authorization: Bearer XXXXX98900000YYYY'
      -H 'Accept: application/json'
    
  • POST requests send data to the CloudHealth Platform. They include a JSON-formatted message body, which contains the data that should be sent. Here, the message body is specified as a parameter following the -d flag.
    curl 'https://chapi.cloudhealthtech.com/v1/perspective_schemas'
      -H 'Authorization: Bearer XXXXX98900000YYYY'
      -H 'content-type: application/json'
      -d '{
        "schema":{
          "name":"Environment-API",
          "rules":[{"type":"categorize","asset":"AwsAsset","tag_field":["cht_env"],"ref_id":"206159110488","name":"Env"}],
          "merges":[],
          "constants":[…]}
        }'
    
This area displays code examples that you can copy and paste into a terminal. Before running these examples, make sure you replace placeholder values enclosed within angle brackets <> with actual values.
For example, all API queries must include your unique API Key in the authorization header. The value of this key is indicated as <your_api_key> in these code examples. Replace this placeholder value with your actual API Key.

Getting Your API Key

Instructions on how to get your unique API Key for authenticating CloudHealth API calls.

How CloudHealth Validates API Requests

You need an API Key in order to make authenticated requests to the CloudHealth API service.

An API Key is a globally unique identifier (GUID) that CloudHealth generates for each user in the platform. When you make an API request, this GUID uniquely identifies and authenticates you as the originator of the request.

To request an API key, click on My Profile in your user settings.

In your profile settings, scroll to the API Key section and click Get API Key. Then click Save Profile Changes.

Include this GUID with each API request to authenticate into the CloudHealth platform.

Periodic Key Rotation

While securing your API Key is important, it is also essential to periodically rotate your API key for security reasons. To update your key, return to your profile settings and click Get API Key to create a new one. Then click Save Profile Changes. When you generate an API Key, the previous key becomes invalid.

The API enforces all the same authentication and authorization checks as the CloudHealth Platform. Therefore, users in an organization can only see data scoped to their organization. Additionally, the API enforces any restrictions to user roles.

Error Codes

Types of response codes that indicate the success or failure of a CloudHealth API request.

CloudHealth uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the rare 5xx range indicate an error with CloudHealth’s servers.

Code Name Description
200 OK Success
201 OK Success
204 OK Success
400 Bad Request Header missing
401 Unauthorized Currently logged out
403 Forbidden Bad API Key
404 Not Found Bad endpoint
422 Unprocessable Entity Input format error
429 Too many requests Exceeding post rate limit
500 Internal Service Error General error
503 Service not available Back end capped out

All errors return JSON in the following format:

{
  "error": "error message here"
}

AWS Accounts in CloudHealth

Enable AWS Account

Enable an AWS Account in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/aws_accounts

Parameters

  • namerequired

    String that specifies the unique display name of an AWS account.

  • authenticationrequired

    JSON field that specifies how to authenticate with your AWS accounts. Use IAM Role (recommended) or IAM User (less secure) to authenticate.

    • protocolrequired

      Authentication protocol. Specify access_key or assume_role

    • access_keyrequired

      Access Key for IAM User

    • secret_keyrequired

      Access Key for IAM User

    • assume_role_arnrequired

      Role ARN for IAM Role

    • assume_role_external_idrequired

      External ID generated by CloudHealth. See How to get External ID.

  • billing

    JSON field that specifies the location of the AWS Detailed Billing Record (DBR).

    • bucketrequired

      Name of S3 bucket containing the DBR

  • cloudtrail

    JSON field that specifies whether CloudHealth should collect CloudTrail Trails and the location of Trail files.

    • enabledrequired

      Should CloudHealth collect CloudTrail trails? Default value is False

    • bucketrequired

      Name of S3 bucket containing the files

    • prefixrequired

      Prefix of Trail files

  • aws_config

    JSON field that specifies whether CloudHealth should collect AWS Config files and the location of the files.

    • enabledrequired

      Should CloudHealth collect AWS Config files? Default value is False

    • bucketrequired

      Name of S3 bucket containing the files

    • prefixrequired

      Prefix of files

  • cloudwatch

    JSON field that specifies whether CloudHealth should collect CloudWatch data.

    • enabledrequired

      Should CloudHealth collect AWS Config files? Default value is True

  • tags

    JSON array that specifies key-value pairs for tags. When you use this field, The API restricts queries to AWS accounts that are tagged with these key-value pairs.

    • keyrequired

      Tag key

    • valuerequired

      Tag value

  • hide_public_fields

    Boolean field that specifies whether CloudHealth should store public DNS and IP. Default value is True

  • region

    JSON field that specifies the type of AWS Account. Value can be global (default) or govcloud.

Result header contains Location: https://chapi.cloudhealthtech.com/v1/aws_accounts/1

{
  "name": "Production Account",
  "authentication": {
    "protocol": "assume_role",
    "assume_role_arn": "arn:aws:iam::XCXXXXXXXXXZ:role/CloudHealth-IAM-Role",
    "assume_role_external_id": "ABCDEFGH1234"
  },
  "billing": {
    "bucket": "my-billing-bucket"
  },
  "cloudtrail": {
    "enabled": true,
    "bucket": "my-cloudtrail-bucket"
  },
  "aws_config": {
    "enabled" :true,
    "bucket": "my-aws-config-bucket",
    "prefix": "foo"
  },
  "tags": [
    {"key": "Environment", "value": "Production"}
  ]
}
{
  "id": 1,
  "name": "Production Account",
  "hide_public_fields": false,
  "region": "global",
  "created_at": "2015-12-16T23:03:49Z",
  "updated_at": "2015-12-16T23:03:49Z",
  "account_type": "Unknown",
  "status": {
    "level": "unknown"
  },
  "authentication": {
    "protocol": "assume_role",
    "assume_role_arn": "arn:aws:iam::XCXXXXXXXXXZ:role/CloudHealth-IAM-Role",
    "assume_role_external_id": "ABCDEFGH1234"
  },
  "billing": {
    "bucket": "my-billing-bucket",
    "is_consolidated": false
  },
  "cloudtrail": {
    "enabled": true,
    "bucket": "my-cloudtrail-bucket"
  },
  "aws_config": {
    "enabled": true,
    "bucket": "my-aws-config-bucket",
    "prefix": "foo"
  },
  "cloudwatch": {
    "enabled": true
  },
  "tags": [
  {
    "key": "Environment",
    "value": "production"
  }
  ],
  "_links": {
    "self": {
      "href": "/v1/aws_accounts/1"
    }
  }
}
curl -d
  '{
    "name": "Production Account",
    "authentication": {
      "protocol": "access_key",
      "access_key": "AKIAQQQQQQQQQQQ",
      "secret_key": "S87345j34lkj3l45lkj+2342"
    },
    "billing": {
      "bucket": "my-billing-bucket"
    },
    "cloudtrail": {
      "enabled": true,
      "bucket": "my-cloudtrail-bucket"
    },
    "aws_config": {
      "enabled" :true,
      "bucket": "my-aws-config-bucket",
      "prefix": "foo"
    },
    "tags": [{
      "key": "Environment",
      "value": "Production"
    }]
  }'
  -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' --request POST 'https://chapi.cloudhealthtech.com/v1/aws_accounts'

AWS Accounts in CloudHealth

Get a list of all AWS Accounts that are enabled in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/aws_accounts

Parameters

  • page

    Specify the page number for results

  • per_page

    Specify how many results should be displayed per page. Default value is 30.

The results of this API call are paginated.

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts"
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts?page=2"
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts?page=3&per_page=100"

Single AWS Account

Get information on a single AWS Account that is enabled in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/aws_accounts/:id

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts/<account_ID>"

Update Existing AWS Account

Update the attributes of an AWS Account that is already enabled in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/aws_accounts/:id

Parameters

  • namerequired

    String that specifies the unique display name of an AWS account.

  • authenticationrequired

    JSON field that specifies how to authenticate with your AWS accounts. Use IAM Role (recommended) or IAM User (less secure) to authenticate.

    • protocolrequired

      Authentication protocol. Specify access_key or assume_role

    • access_keyrequired

      Access Key for IAM User

    • assume_role_arnrequired

      Role ARN for IAM Role

    • assume_role_external_idrequired

      External ID generated by CloudHealth

  • billing

    JSON field that specifies the location of the AWS Detailed Billing Record (DBR) or the AWS Cost and Usage Report (CUR).

    • bucketrequired

      Name of S3 bucket containing the DBR and CUR

  • cloudtrail

    JSON field that specifies whether CloudHealth should collect CloudTrail Trails and the location of Trail files.

    • enabledrequired

      Should CloudHealth collect CloudTrail trails? Default value is False

    • bucketrequired

      Name of S3 bucket containing the files

    • prefixrequired

      Prefix of Trail files

  • aws_config

    JSON field that specifies whether CloudHealth should collect AWS Config files and the location of the files.

    • enabledrequired

      Should CloudHealth collect AWS Config files? Default value is False

    • bucketrequired

      Name of S3 bucket containing the files

    • prefixrequired

      Prefix of files

  • cloudwatch

    JSON field that specifies whether CloudHealth should collect CloudWatch data.

    • enabledrequired

      Should CloudHealth collect AWS Config files? Default value is True

  • tags

    JSON field that specifies key-value pairs for tags. When you use this field, The API restricts queries to AWS accounts that are tagged with these key-value pairs.

    • keyrequired

      Tag key

    • valuerequired

      Tag value

  • hide_public_fields

    Boolean field that specifies whether CloudHealth should store public DNS and IP. Default value is True

  • region

    JSON field that specifies the type of AWS Account. Value can be global (default) or govcloud.

{
  "name": "Production Engineering Account",
  "tags": [
  {
    "key": "Environment",
    "value": "production"
  },
  {
    "key": "Owner",
    "value": "Engineering"
  }
  ]
}
curl -d '{"authentication":{"protocol":"assume_role","assume_role_arn":"arn:123","assume_role_external_id":"61a1XXXXXXXXXXXXXXXXXXXXX5d8c6"},"name":"Tools 123"}' -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' --request PUT 'https://chapi.cloudhealthtech.com/v1/aws_accounts/<account_id>'

Delete AWS Account

Delete an AWS Account from the CloudHealth Platform

https://chapi.cloudhealthtech.com/v1/aws_accounts/:id

curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/aws_accounts/:id'

Get External ID

Generate your unique customer External ID so that you can configure an IAM Role in the AWS Console.

https://chapi.cloudhealthtech.com/v1/aws_accounts/:id/generate_external_id

You cannot generate and specify your own External ID as the value of the assume_role_external_id parameter.

CloudHealth generates a unique External ID for each customer. You can only use this ID as the value of the assume_role_external_id parameter. Because the CloudHealth-generated ID is unique to you, you can reuse it across all your accounts.

To get your External ID, log into the CloudHealth Platform. From the left menu, select Setup > Accounts > AWS and click New Account. The account setup form displays the generated External ID.

You can also get your API key through an endpoint.

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts/:id/generate_external_id"

Perspectives

Introduction to Perspectives API

An introduction to the Perspectives API.

The Perspectives API allows you to manipulate a schema file that defines the rules for grouping assets in a Perspective. Use the following endpoint:

https://chapi.cloudhealthtech.com/v1/perspective_schemas

Using a schema file as a payload, you can perform these operations:

  • Create Perspectives
  • Modify rules that govern how Perspective Groups are created
  • Merge Groups
  • Reorder Groups
  • Delete Perspectives

Understand Format of Perspectives Schema

Learn about the Perspective Schema Format.

Parameters

  • name

    String that specifies the name of the Perspective. The name need not match the name of an existing (active or archived) Perspective.

  • include_in_reports

    Boolean that specifies whether the Perspective is included in CloudHealth Reports. Specify as true (default) or false.

  • rules

    An array of rules (objects) that govern Perspective membership. The ordering of the rules matters. Rules are evaluated in order starting from the first one in the array. This parameter simplifies the process of reordering a Group. Run a read operation to get the schema of a Perspective, change the order in the schema in a text editor, and upload the modified schema to the same Perspective.

  • merges

    List of merge objects, which can be of type Dynamic Group or Dynamic Group Block. The Dynamic Group merge allows for two Groups to merged and the Dynamic Block Group is to merge two entire blocks of Groups. Each merge specifies a list of source objects and a single target object (Groups or blocks), where the sources are to be merged into the target.

  • constants

    List of reference objects that refer to Groups, blocks, and assets that are specified in rules. When a schema is retrieved through a GET operation, every Group (dynamic and static) is listed in the this section. Although meant mainly for reference, constants can be modified to change the name of Groups and blocks. The full list of potential constant types is provided below.

Constant Types can either be Dynamic Group, Static Group, or an asset type listed below.

Expansion types such as AwsAsset or AzureTaggableAsset are not included.

  • AwsAccount
  • AwsAvailabilityZone
  • AwsGroup
  • AwsImage
  • AwsInstance
  • AwsInstanceReservation
  • AwsInstanceStatus
  • AwsInstanceType
  • AwsRdsInstance
  • AwsRegion
  • AwsSecurityGroup
  • AwsSecurityGroupRule
  • AwsSnapshot
  • AwsSpotRequest
  • AwsTag
  • AwsUser
  • AwsVolume
  • ChefAccount
  • ChefCookbook
  • ChefCookbookVersion
  • ChefNode
  • AwsS3Bucket
  • AwsCloudFormationStack
  • AwsCloudFormationResource
  • ChefCookbookConstraint
  • ChefEnvironment
  • AwsRdsSnapshot
  • AwsVpc
  • AwsRedshiftCluster
  • AwsRedshiftSnapshot
  • AwsRedshiftReservedNode
  • AwsVpcSubnet
  • AwsLoadBalancer
  • AwsDynamoDbTable
  • AwsCacheCluster
  • InstanceAttributeHash
  • InstanceFileSystem
  • AwsRdsInstanceReservation
  • AwsRdsSecurityGroup
  • AwsRdsSecurityGroupRule
  • AwsRdsSubnetGroup
  • AwsInstanceReservationModification
  • AwsInstanceReservationModificationItem
  • AwsEmrCluster
  • AwsEmrClusterInstanceGroup
  • AwsEmrClusterInstance
  • AwsInstanceReservationListing
  • PagerdutyAccount
  • PagerdutyIncident
  • AwsNaclTable
  • AwsNaclRule
  • AwsCustomerGateway
  • AwsVpnGateway
  • AwsVpnConnection
  • AwsInternetGateway
  • AwsEni
  • AwsElasticIp
  • AwsEipPrivateIp
  • Alert
  • GcpComputeRegion
  • GcpComputeZone
  • GcpComputeProject
  • GcpComputeMachineType
  • GcpComputeInstance
  • GcpComputeDiskType
  • GcpComputeDisk
  • GcpComputeSnapshot
  • GcpComputeImage
  • GcpComputeAttachedDisk
  • GcpComputeMachineTypeProfile
  • GcpTag
  • GcpBillingStatement
  • GcpBillingStatementItem
  • GcpUsageStatement
  • GcpStorageBucket
  • VmwareAccount
  • VmwareFolder
  • VmwareDatacenter
  • VmwareHost
  • VmwareDatastore
  • VmwareVirtualMachine
  • VmwareCustomField
  • DockerImage
  • DockerContainer
  • DelegatedAction
  • CloudFrontDistribution
  • CloudFrontOrigin
  • DataCenterAccount
  • DataCenterServer
  • DataCenterServerFileSystem
  • AzureEnrollment
  • AzureBillingStatementItem
  • AzureStoredBill
  • AzureVm
  • DataCenterServerNetworkInterface
  • DataCenterServerCpu
  • DataCenterServerBlockDevice
  • AlertlogicAccount
  • AwsRoute53HostedZone
  • AnsibleAccount
  • AnsibleNode
  • AwsConfigRule
  • AwsConfigRuleEvaluationResult
  • AwsElasticacheReservedNode
  • DatadogAccount
  • DatadogHost
  • DatadogTag
  • AzureSubscription
  • AzureTag
  • AwsLambdaFunction
  • AzureAccount
  • AzureDepartment
  • AzureCostCenter
  • NewrelicAccount
  • NewrelicServer
  • IntegrationTag
  • AzureZone
  • AzureRegion
  • AzureResourceGroup
  • AzureServicePrincipal
  • AzureVmFileSystem
  • AzureVmNetworkInterface
  • AzureVmCpu
  • AzureVmVirtualDisk
  • AzureVmSize
  • AzureCatalog
  • AzureVmRate
  • AzureOffer
  • AzureRateCard
  • AzureStoredUsage
  • AwsIamPolicy
  • AwsIamRole
  • AwsIamServerCertificate
  • AwsAdsAgentStat
  • AwsAdsServer
  • AwsAccountRegionAttribute
  • AwsAdsProcess
  • AwsAdsConnection
  • DataCenterTag
  • CustomerTag
  • AwsIamCredentialReport
  • AzureCloudService
  • AzureSecurityGroup
  • AzureSecurityRule
  • AzureIpAddress
  • AwsIamPasswordPolicy
  • AzureStorage
  • AzureVmScaleSet
  • AwsCloudtrailTrail
  • AzureSqlServer
  • AzureSqlDatabase
  • AzurePartnerCenter
  • AzureRedisCache
  • JiraAccount
  • IntegrationOauthAccount
  • AzurePartnerCustomer
  • IntegrationMetadata
  • AzureVirtualNetworkGateway
  • AzureAppServicePlan
  • AzureServiceBusNamespace
  • AzureVirtualNetwork
  • AzureBatchAccount
  • AzureBackupVault
  • AzureRecoveryServicesVault
  • AzureHdInsightCluster
  • AzureSearchService
  • AzureSqlDataWarehouse
  • AzureStorSimpleDeviceManager
  • AzureAppService
  • AzureLogAnalyticsWorkspace
  • AzureExpressRouteCircuit
  • AzureCdnProfile
  • AwsNatGateway
  • AzureSnapshot
  • AzureNetworkInterface
  • AzureManagedDisk
  • AzureAppInsight
  • AwsElasticFileSystem
  • AzureDocumentDb
  • AzureKeyVault
  • AwsElasticsearchDomain
  • AwsElasticsearchInstance
  • AwsElasticsearchVolume
  • AwsDedicatedHost
  • AzureApplicationGateway
  • AwsConfigSetting
  • AwsWorkspace
  • AzureAppServiceEnvironment
  • AwsAutoScalingGroup
  • AwsKinesisStream
  • AzureVmReservationRate
  • AzureReservationOrder
  • AzureReservation
  • AzureVmRiQuote

How to Get Perspective ID

In order to perform Get, Put, and Post operations using this API, you need to provide the ID of the Perspective that you want to manipulate.

You can get the ID of a Perspective from the CloudHealth Platform. From the left menu, select Setup > Perspectives and click the Perspective that you want to manipulate. The ID of the Perspective appears in the browser URL. Here’s an example URL:

https://apps.cloudhealthtech.com/perspectives/35261XXX012

Here, 35261XXX012 is the Perspective ID.

Retrieve All Perspectives

Retrieve a list of all Perspectives you have created in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/perspective_schemas

Parameters

  • active_only

    Boolean that specifies whether only active Perspectives are returned in the response.

The response contains the list in the form of a hash that includes the Perspective ID, Perspective name, and a flag field that indicates whether the Perspective is active.

curl -s -H "Accept: application/json" "https://chapi.cloudhealthtech.com/v1/perspective_schemas?api_key=<api key>"
{
  "206159639971": { "name": "DDE Test", "active": false  },
  "206159351171": { "name": "Environment ", "active": true  },
  "206159659286": { "name": "Environment-tmp", "active": false  },
  "206159657643": { "name": "Efe Test", "active": false  },
  "206159708697": { "name": "Sidd test", "active": true  },
  "181": { "name": "Function", "active": true  },
  "650": { "name": "Finance Costs", "active": true  }
}

Retrieve Perspective Schema

Retrieve the schema that defines a specific Perspective. Identify the specific Perspective by its ID. See How to Get Perspective ID.

https://chapi.cloudhealthtech.com/v1/perspective_schemas/:perspective-id

Parameters

  • include_version

    Boolean that defines whether the current version of the perspective is returned in the response.

curl -s -H "Accept: application/json" "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>"
{
  "schema": {
    "name": "Environment",
    "include_in_reports": "true",
    "rules": [
      {
        "type": "categorize",
        "asset": "AwsAsset",
        "tag_field": [
          "cht_env"
        ],
        "ref_id": "5841XXXXXXX853",
        "name": "AWS Assets"
      },
      {...}
    ],
    "merges": [
      {
        "type": "Group",
        "to": "584XXXXX39263",
        "from": [
          "584YYYYYY9283"
        ]
      },
      {...}
    ],
    "constants": [
      {
        "type": "Dynamic Group Block",
        "list": [
          {
            "ref_id": "ABCDEFG522853",
            "name": "AWS Assets"
          },
          {...}
        ]
      },
      {...}
    ]
  }
}
curl -s -H "Accept: application/json" "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>" | python -m json.tool

Create Perspective Schema

Create a schema and associate it with a specific Perspective. Identify the specific Perspective by its ID. See How to Get Perspective ID.

https://chapi.cloudhealthtech.com/v1/perspective_schemas/

Parameters

  • include_version

    Boolean that defines whether the current version of the perspective is returned in the response.

How to Duplicate a Perspective

To duplicate a Perspective, retrieve the schema from the source Perspective (e.g., Perspective A) and POST that schema with a new name (e.g., Perspective B) to create a duplicate of Perspective A. All references in the schema rules to existing groups and blocks in Perspective A are seen as directives to create corresponding groups in Perspective B. Perspective A and its Groups remain unchanged.

How to Add a Perspective Group

When creating a Perspective, if your schema contains a reference to a Group that does not exist within the Perspective, the POST call creates that Group in the Perspective. Therefore, if there are rules in your schema that reference a Group that does not exist in the Perspective, the POST call creates that new Group and associates those rules with the newly created Group.

For example, this POST call creates a Perspective:

curl -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/v1/perspective_schemas?api_key=<api_key>" -d '{"schema":{"name":"Test 1000002","rules":[{"type":"filter","asset":"AwsInstance","to":"new group 1","condition":{"clauses":[{"field":["Active?"],"op":"=","val":"true"}]}},{"type":"filter","asset":"AwsInstance","to":"new group 1","condition":{"clauses":[{"field":["First Discovered"],"op":">","val":"2016-01-04T23:19:34+00:00"}]}}],"constants":[],"merges":[]}'

When you make a subsequent GET call to retrieve this schema, a new group (Group-1) is created and displayed in the response. All references to new group 1 in the schema are converted into references to the newly created group.

curl -s -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/v1/perspective_schemas/?api_key=<api_key>" -d '{"schema": {"name": "Environment","include_in_reports": "true",
"rules": [{"type": "categorize","asset": "AwsAsset","tag_field": ["cht_env"],"ref_id": "5841XXXXXXX853","name": "AWS Assets"}],
"merges": [{"type": "Group","to": "584XXXXX39263","from": ["584YYYYYY9283"]}],
"constants": [{"type": "Dynamic Group Block","list": [{"ref_id": "ABCDEFG522853","name": "AWS Assets"}],
}}'

Update Perspective Schema

Modify a Perspective based on rules posted through a schema.

https://chapi.cloudhealthtech.com/v1/perspective_schemas/:perspective-id

Parameters

  • check_version

    Number that specifies the version of the Perspective schema that should be updated.

  • include_version

    Boolean that defines whether the current version of the perspective is returned in the response.

If the schema contains references to Groups that do no exist in the Perspective, the PUT operation creates those Groups in the Perspective.

You can specify both to and from fields in rules that reference target Groups. The from field is optional. When it is not present, the Other (Assets Not Allocated) group is considered to be the from Group.

When you create a group-to-group rule, the update/create calls verify that the source group already has at least one rule higher in the rule that targets it.

How to Avoid Conflicts during Concurrent Updates

Use the check_version parameter to ensure that a concurrent update is not overwritten.

curl -s -H 'Content-Type: application/json' -XPUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>&check_version=3"

If the Perspective was updated, and therefore version-incremented, since the last GET operation, the update request returns a 400 error.

curl -s -H 'Content-Type: application/json' -XPUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
  ?api_key=<api_key>" -d '{"schema":<schema JSON>}'

Delete Perspective Schema

Remove a specific Perspective from the CloudHealth Platform. You can perform a soft (default), forced, or hard deletion.

https://chapi.cloudhealthtech.com/v1/perspective_schemas/:perspective-id

Parameters

  • force

    Boolean that specifies whether the Force Delete option is exercised. See Force Delete.

  • hard_delete

    Boolean that specifies whether the Hard Delete option is exercised. See Hard Delete.

There are three levels of Perspective deletion.

Soft Delete (default)

This option deletes the Perspective and archives it only if there are no Perspective dependencies such as Policies and Report Subscriptions. You can restore the deleted Perspective.

curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>"

Force Delete

This option deletes and archives the Perspective irrespective of whether any dependencies exist in Policies or Report Subscriptions. You can restore the deleted Perspective, but you will need to recreate the Policies and Report Subscriptions that depended on the Perspective.

curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
  ?api_key=<api_key>
  &force=true"
Hard Delete

This option deletes the Perspective without archiving it. You cannot restore a Perspective that was deleted using this option.

curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective id>
  ?api_key=<api_key>
  &force=true
  &hard_delete=true"
curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
  ?api_key=<api_key>"

Get Perspective Version

Include the version of a Perspective in the response.

curl -s -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json'
  "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
  ?&include_version=true"
{
  "type": "Version",
  "list": [
    {
      "ref_id": 181,
      "val": 2
    }
  ]
}

Reporting

Introduction to Reporting API

An introduction to the Reporting API and common terminology.

The Reporting API allows REST-based access to data presented in OLAP CloudHealth Reports through this endpoint.

https://chapi.cloudhealthtech.com/olap_reports

Which Reports are Queryable

You can only retrieve data presented in OLAP reports. These are reports that are:

  • available at the /olap_reports endpoint (including the Container Cost History report), and
  • present data visually through charts and graphs

Reporting Terminology

Familiarize yourself with the terminology specific to this API.

  • Report name: The display name of the report (e.g., Instance Usage).
  • Dimensions: Available members for the X-axis and categorization (e.g. by Days categorized by Reservation Type).
  • Intervals: The granularity of the report (e.g., monthly, weekly, or hourly).
  • Measures: Selected measures (e.g. # Instances).
  • Filters: User-defined filters for the report.
  • Data: The data that is returned when requesting a report.

See how these terms match to elements of the Report interface in the CloudHealth Platform.

Understand Report Data Format

Familiarize yourself with the format of the response that a Standard Report query returns.

When you query a Standard Report, the response you receive has the following general structure.

{
  "report":"Instance Usage",
  "dimensions":[
    {
      "time":[...]
    },
    {
      "EC2-Reservation-Execution-Mode":[...]
    }
  ],
  "measures":[
    {
      "name":"usage_quantity",
      "label":"# Instances"
    }
  ],
  "interval":"daily",
  "filters":[...],
  "updated_at":"2018-02-05T03:08:40+00:00",
  "data":[
    [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
    [...],
  ],
  "status":"ok"
}

Let’s break down this response.

  • report is a string that contains the display name of the report (e.g., Instance Usage).
  • dimensions is an array that contains the available members for the X-axis and categorization (e.g., by Days categorized by Reservation Type).
  • measures is an array that contains the selected measures for the report (e.g. # Instances)
  • interval is a string that contains the granularity of the report (e.g., monthly, weekly, or hourly)
  • filters is an array that contains all the filters selected for the report
  • data is an array that contains the report data

See how these fields match to elements of the Report interface in the CloudHealth Platform.

Among these fields, the data field deserves some more explanation. The structure of this field depends on the structure and content of the dimensions field.

Let’s say that the dimensions field contains the following array.

"dimensions": [
  {
    "Past-12-Months": [
      {"label": "Total", "name": "total"},
      {"label": "2013-10", "name": "2013-10"},
      {"label": "2013-11", "name": "2013-11"},
      ...
    ]
  },
  {
    "AWS-Service-Category": [
      {"label": "Total", "name": "total"},
      { "label": "EC2 - Compute", "name": "ec2_compute" },
      { "label": "EC2 - Transfer", "name": "ec2_transfer" },
      ...
    ]
  }
]

Then the corresponding data field might contain the following array.

"data": [
  [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
  [[30, 20, 10], [20, 10, 10], [10, 0, nil], ...],
  [[70, 40, 30], [40, 20, 20], [30, 20, 10], ...],
]

Each row in data corresponds to time periods in the first subarray inside dimensions.

Let’s only consider the first row in data and correlate it with the structure of dimensions.

[[100, 40, 60], [60, 20, 40], [40, 20, 20], ...]

Within this row is the data specific to the second subarray inside dimensions, namely AWS-Service-Category.

Putting it all together, each row in data combines one or more dimensions.

If a cell contains 0, there was data for the specified dimension member in the underlying data analyzed, but the aggregate total was 0. If a cell contains null, there was no data for this dimension member in the underlying data analyzed.

List of Queryable Reports

Retrieve a list of Standard OLAP reports that you can query.

https://chapi.cloudhealthtech.com/olap_reports

The response to this query contains a list of endpoints that provide Standard CloudHealth reports of specific types. The following endpoints are returned.

  • /cost
  • /custom
  • /performace
  • /usage

These endpoints are hierarchical. For example the /cost endpoint branches out into specific reports of that type

Branch Report name in CloudHealth Platform
history Cost History
current Current Cost
instance EC2 Instance Cost
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' https://chapi.cloudhealthtech.com/olap_reports' | python -m json.tool
{
  "links": {
    "cost": {
      "href": "https://chapi.cloudhealthtech.com/olap_reports/cost"
    },
    "custom": {
      "href": "https://chapi.cloudhealthtech.com/olap_reports/custom"
    },
    "performance": {
      "href": "https://chapi.cloudhealthtech.com/olap_reports/performance"
    },
    "usage": {
      "href": "https://chapi.cloudhealthtech.com/olap_reports/usage"
    }
  }
}

List Reports of Specific Type

Retrieve the list of available Standard OLAP reports of a specify type.

https://chapi.cloudhealthtech.com/olap_reports/:report-type

Retrieving a list of all reports of a specific type, such as /cost, /custom, /performance, or /usage is a two-step process.

  1. Get the endpoints for all types of Standard reports.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'

    This query returns the following response.

    {
      "links": {
        "cost": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost"
        },
        "custom": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/custom"
        },
        "performance": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/performance"
        },
        "usage": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/usage"
        }
      }
    }
    
  2. Query the endpoint for the type of report from this response and get a list of all reports of that type.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost'

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost'`
{
  "links": {
      "amortized": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/amortized"
      },
      "current": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/current"
      },
      "history": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/history"
      },
      "instance": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/instance"
      },
      "rds": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/rds"
      },
      "ri_amortization": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/ri_amortization"
      },
      "s3": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/s3"
      },
      "volume": {
          "href": "https://chapi.cloudhealthtech.com/olap_reports/cost/volume"
      }
  }
}

Data for Standard Report

Retrieve the data for a specific Standard report.

https://chapi.cloudhealthtech.com/olap_reports/:report-type/:report-id

Parameters

  • dimensions

    Array that specifies the members to use for Categorization and the X-Axis.

  • measures

    Array that specifies the Y-axis measures to use for the report.

  • interval

    String that specifies the granularity of report data.

  • filters

    Array that specifies the filters to use for constraining report data.

Retrieving the data for a specific Standard report, such as /cost/history, /cost/current, or /usage/instance involves the following steps.

  1. Get the endpoints for all types of Standard reports.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'

    This query returns the following response.

    {
    "links": {
      "cost": {
       "href": "https://chapi.cloudhealthtech.com/olap_reports/cost"
      },
      "custom": {
       "href": "https://chapi.cloudhealthtech.com/olap_reports/custom"
      },
      "performance": {
       "href": "https://chapi.cloudhealthtech.com/olap_reports/performance"
      },
      "usage": {
       "href": "https://chapi.cloudhealthtech.com/olap_reports/usage"
      }
     }
    }
    
  2. Query the endpoint for the type of report from this response and get a list of all reports of that type. This example request queries the /usage endpoint to get a list of all Standard Usage Reports.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage'

    This query returns the following response, which has been truncated here for simplification.

    Note: Only those reports that have /olap_reports in their endpoint are accessible through the API.

    {  
    "links":{
       [...]
       "usage/instance":{  
         "href":"https://chapi.cloudhealthtech.com/olap_reports/usage/instance"
       },
       "usage/volume":{  
         "href":"https://chapi.cloudhealthtech.com/olap_reports/volume"
       },
       [...]
     }
    }
    
  3. Query the endpoint for the specific report to get its data. This example request queries the /usage/instance endpoint to get the data for the EC2 Instance Usage report.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance'

    This query returns the following response, which has been truncated here for simplification.

     {
       "report":"Instance Usage",
       "dimensions":[
         {
           "time":[...]
         },
         {
           "EC2-Reservation-Execution-Mode":[...]
         }
       ],
       "measures":[
         {
           "name":"usage_quantity",
           "label":"# Instances"
         }
       ],
       "interval":"daily",
       "filters":[...],
       "updated_at":"2018-02-05T03:08:40+00:00",
       "data":[
         [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
         [...],
       ],
       "status":"ok"
     }
    

    Depending on which Standard Report you query, the response might vary in structure. However, all responses have common elements. See Understand Report Data Format.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance'`
{
  "report":"Instance Usage",
  "dimensions":[
    {
      "time":[...]
    },
    {
      "EC2-Reservation-Execution-Mode":[...]
    }
  ],
  "measures":[
    {
      "name":"usage_quantity",
      "label":"# Instances"
    }
  ],
  "interval":"daily",
  "filters":[...],
  "updated_at":"2018-02-05T03:08:40+00:00",
  "data":[
    [[100, 40, 60],
    [60, 20, 40],
    [40, 20, 20], ...],
    [...],
  ],
  "status":"ok"
}

Data for Custom Report

Retrieve the data for a custom Standard report.

https://chapi.cloudhealthtech.com/olap_reports/custom/:report-id

Parameters

  • dimensions

    Array that specifies the members to use for Categorization and the X-Axis.

  • measures

    Array that specifies the Y-axis measures to use for the report.

  • interval

    String that specifies the granularity of report data.

  • filters

    Array that specifies the filters to use for constraining report data.

Custom reports are saved versions of Standard Reports. Retrieving the data for a specific saved report involves the following steps.

  1. Get the ID of the custom report.

    In the CloudHealth Platform, from the left menu, click Reports > Saved Reports. Click the View Report icon next to the report you want to retrieve.

    The URL in your browser contains the ID of the selected report.

  2. Query the endpoint for the specific report to get its data.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/custom/<Report-ID>'

    This query returns a response similar to this truncated one.

     {
       "report":"Cost History",
       "dimensions":[
         {
           "time":[...]
         },
         {
           "AWS-Service-Category":[...]
         }
       ],
       "measures":[
         {
           "name":"cost",
           "label":"Cost ($)"
         }
       ],
       "interval":"weekly",
       "filters":[...],
       "updated_at":"2018-02-05T03:08:40+00:00",
       "data":[
         [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
         [...],
       ],
       "status":"ok"
     }
    

    Depending on which saved report you query, the response might vary in structure. However, all responses have common elements. See Understand Report Data Format.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/custom/<Report-ID>'
{
  "report":"Cost History",
  "dimensions":[
    {
      "time":[...]
    },
    {
      "AWS-Service-Category":[...]
    }
  ],
  "measures":[
    {
      "name":"cost",
      "label":"Cost ($)"
    }
  ],
  "interval":"weekly",
  "filters":[...],
  "updated_at":"2018-02-05T03:08:40+00:00",
  "data":[
    [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
    [...],
  ],
  "status":"ok"
}

Report Dimensions and Measures

Get dimensions and measures for a report so that you can build granular report queries

https://chapi.cloudhealthtech.com/olap_reports/:report-type/:report-id/new

You can build granular report queries by passing dimensions and measures into the query string. In order to build detailed queries, first discover which dimensions and measures are available at the endpoint for each report.

Each report has a /new endpoint that returns the dimensions and measures available for that report.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance/new'
{
  "dimensions": [
  {
    "label": "Owner Perspective",
    "name": "Groupset-998"
    "members": [
      {
        "label": "Joe",
        "name": "1392"
      },
      {
        "label": "Sue",
        "name": "1388"
      },
      {
        "label": "No Owner Found",
        "name": "1386"
      }
    ],
  },
  {
    "label": "Function Perspective",
    "name": "Groupset-999"
    "members": [
      {
          "label": "Zookeeper",
          "name": "27715"
      },
      {
          "label": "Databases",
          "name": "27716"
      },
      ...
    ],
  },
  {
    "label": "Availability Zones",
    "name": "AWS-Availaibility-Zones"
    "members": [
      {
          "label": "us-east-1a",
          "name": "us-east-1a"
      },
      {
          "label": "us-east-1b",
          "name": "us-east-1b"
      },
      {
          "label": "us-east-1d",
          "name": "us-east-1d"
      }
    ],
  },
  {
    "label": "Days",
    "name": "time"
    "members": [
      {
          "label": "2014-08-27",
          "name": "1"
      },
      {
          "label": "2014-08-28",
          "name": "2"
      },
      ...
    ],
  }
  ...
],
"measures": [
  {
    "label": "# Instances",
    "name": "usage_quantity"
  },
  {
    "label": "Total Cost ($)",
      "name": "cost"
  },
  {
      "label": "Compute Cost ($)",
      "name": "ec2_cost_compute"
  },
  {
      "label": "Transfer Cost ($)",
      "name": "ec2_cost_transfer"
  },
  {
      "label": "# Reservations",
      "name": "count"
  },
  {
      "label": "On-Demand Cost ($)",
      "name": "ec2_cost_on_demand"
  },
  {
      "label": "# Instance Hours",
      "name": "instance_hours"
  }
]
}

Get Query for a Report

Retrieve the query string and parameters that produce a Standard or Custom OLAP report.

Each CloudHealth report is produced by a combination of parameters that together compose a query string. You can retrieve the query string that produces a Standard or Custom report.

Because the response is JSON, meta characters are Unicode encoded.

curl -v -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/custom/{report-id}?get_query=true'
{
  "query":"report=My Saved Report?dimensions[]=AWS-Account&dimensions[]=AWS-Service-Category&measures[]=cost&measures[]=cost_recurring&interval=monthly&filters[]=time:select:-1"
}

Add Dimensions and Measures to Report Query

Customize the granularity of report data by building complex queries that employ measures, dimensions, and filters. This example shows how to build a complex query to get the EC2 Compute Cost by Availability Zone for a monthly granularity.

  1. Retrieve the list of available measures and dimensions of for the EC2 Instance Report. curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' "https://chapi.cloudhealthtech.com/olap_reports/usage/instance/new"

    This query returns a response that looks like this.

    {
    "dimensions": [
       {
           "label": "Owner Perspective",
           "name": "Groupset-998"
           "members": [...],
       },
       {
           "label": "Function Perspective",
           "name": "Groupset-999"
           "members": [...],
      },
      {
           "label": "Availability Zones",
           "name": "AWS-Availaibility-Zones"
           "members": [
               {
                   "label": "us-east-1a",
                   "name": "us-east-1a"
               },
               ...
           ],
       },
       {
           "label": "Days",
           "name": "time"
           "members": [
               {
                   "label": "2018-01-10",
                   "name": "1"
               },
               ...
           ],
       }
       ...
      ],
      "measures": [
       {
           "label": "# Instances",
           "name": "usage_quantity"
       },
       {
           "label": "Total Cost ($)",
           "name": "cost"
       },
       {
           "label": "Compute Cost ($)",
           "name": "ec2_cost_compute"
       },
       {
           "label": "Transfer Cost ($)",
           "name": "ec2_cost_transfer"
       },
       {
           "label": "# Reservations",
           "name": "count"
       },
       {
           "label": "On-Demand Cost ($)",
           "name": "ec2_cost_on_demand"
       },
       {
           "label": "# Instance Hours",
           "name": "instance_hours"
       }
     ]
      }
    
  2. Build a complex query that gets the EC2 Compute Cost by Availability Zone for a monthly granularity.

    For each dimension, add a query parameter called dimensions[] and for each measure add a parameter called measures[]. For each of these parameters, specify one or more values that you received when querying the /new endpoint. In general, the dimensions available are hourly, daily, weekly, and monthly.

    curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance?
     dimensions[]=time
     &dimensions[]=AWS-Availaibility-Zones
     &measures[]=ec2_cost_compute
     &interval=monthly'
    

Add Filters to Report Query

Use filters in conjunction with dimensions and measures to build complex queries.

Report filters help you reduce the data that is returned by a report query. You can use filters in conjunction with dimensions and measures to build complex queries.

For example, to get the EC2 Compute Cost in us-east-1a, you can apply a filter in this way.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance?
  dimensions\[\]=time
  &dimensions\[\]=AWS-Availaibility-Zones
  &measures\[\]=ec2_cost_compute
  &filters\[\]=AWS-Availaibility-Zones:select:us-east-1a
  &interval=monthly'

In the query, each filter is represented using the filters[] parameter. this parameter has the this structure. dimension-name:select|reject:member-name,member-name

The select operator indicates which dimension members that you want to include and the reject, the dimension members that you want to exclude.

For example, to get the EC2 Compute Costs for all Availability Zones except us-east-1b and us-east-1d, you can apply a filter in this way.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance
  ?dimensions\[\]=time
  &dimensions\[\]=AWS-Availaibility-Zones
  &measures\[\]=ec2_cost_compute
  &filters\[\]=AWS-Availaibility-Zones:reject:us-east-1b,us-east-1d
  &interval=monthly'

For more information on how to filter by time, see Understand Time Filters.

Understand Time Filters

Familiarize yourself with how time filters work when used with the Reporting API.

Filtering on the time dimension is a common technique for reducing the data returned from a report query. For example, you might want to get report data for last month, this quarter, or the previous year.

The time dimension is unique because it is ordinal. So one way to filter by this dimension is to provide an index value that indicates position. You can specify an Absolute Time Index (positive integers) or a Relative Time Index (negative integers).

Example: Get Data for Current Month

  • Using Relative Time Index
    &interval=monthly&filters[]=time:select:-1
    
  • Using Absolute Time Index
    &interval=monthly&filters[]=time:select:12
    

Example: Get Data for Past Three Months

  • Using Relative Time Index
    &interval=monthly&filters[]=time:select:-1,-2,-3
    
  • Using Absolute Time Index
    &interval=monthly&filters[]=time:select:12,11,10
    

If you are only select-ing months (not weeks, days, or hours) and not reject-ing months, you can specify the dimension as a date string instead of an index. The date string has the format YYYY-MM. You can use this approach to filter out all months except for the current month.

&interval=monthly&filters[]=time:select:2014-12

You cannot mix and match date strings and indexes in a single filter.

Weekly, daily, and hourly (for reports that provide this interval) intervals work similarly. However, the amount of data retrieved for each interval is different.

Interval Units Relative Index
monthly 12 months -1 returns Current month
weekly 52 weeks -1 returns the previous full week
daily 31 days -1 returns the previous full day
hourly 84 hours -1 returns from 10 PM to 11:59 PM UTC the day before (each member has two hours of data)

Assets

Introduction to Assets API

An introduction to the Assets API.

The Assets API allows you to retrieve information on AWS, Azure, Data Center, and Google Cloud assets in your environment. The API supports the following operations:

  • Retrieve the API names of all AWS, Azure, Data Center, and Google Cloud asset objects that you can query in the CloudHealth Platform.
  • Retrieve the attributes of an asset, including the Perspective Groups to which the asset belongs, as well as assets related to the queried asset.
  • Query objects of a specific type, filter objects by attribute, and list specific fields of assets in the response.

List of Queryable Assets

Retrieve the API names of all AWS, Azure, Data Center, and Google Cloud asset objects that you can query in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/api

The response to this query contains a list of JSON objects that represent all the AWS, Azure, Data Center, and Google Cloud assets that CloudHealth has discovered in your environment.

curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api'

[  
  "AwsInstanceType",
  ...
  "AwsCloudtrailTrail",
  "AwsConfigRuleEvaluationResult",
  "AwsConfigRule",
  "AwsIamRole",
  "AwsIamServerCertificate",
  ...
  "IntegrationNode",
  "IntegrationTag",
  "JiraAccount",
  "NewrelicAccount",
  "GcpComputeInstance",
  ...
  "AzureResourceGroup",
  "AzureSearchService",
  "AzureSqlDatabase",
  "AzureSqlServer",
  "AzureStorSimpleDeviceManager",
  ...
  "AlertlogicAccount",
  "DataCenterServerCpu",
  "DataCenterTag",
  "VmwareHost",
  "VmwareVirtualMachine",
  ...
  "AwsInstanceReservationListing",
  "AwsInstanceReservationModificationItem",
  "AwsInstanceReservationModification",
  "AwsInstanceReservation",
  ...
]

Attributes of Single Asset

Retrieve the attributes and related assets for a single asset object.

https://chapi.cloudhealthtech.com/api/:asset

The response to this query contains two arrays: attributes and relations.

The first array, attributes, lists the primary attributes of the AWS, Azure, Data Center, or Google Cloud asset that you want to explore. For example, an AWS Instance has attributes such as Account ID, Instance ID, Public IP, and Private IP. The attributes array also includes the Perspective Groups to which the AWS Instance belongs.

The relations array contains related assets. In the case of an AWS Instance, the relations array lists objects such as AwsAccount, AWSInstanceType, AwsAvailabilityZone, and ChefNode objects.

curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api/AwsInstance'

{
  "name":"AwsInstance",
  "attributes":[
    { "name":"id" },
    { "name":"instance_id" },
    { "name":"public_ip" },
    ...
    { "name":"usage_percentage_per_month" },
    ...
    {
      "name": "attr_group__XXXXX3562234",
      "perspective_name": "Environment"
    },
    {
      "name": "attr_group__XXXXX3562234",
      "perspective_name": "Owner"
    },
    ...
    {
      "name": "attr_group__XXXXX35623434",
      "perspective_name": "Team"
    }
  ],
  "relations":[
    {  
      "name": "account",
      "object_type": "AwsAccount",
      "has_many": false
    },
    {  
      "name": "instance_type",
      "object_type": "AwsInstanceType",
      "has_many": false
    },
    ...
    {  
      "name": "auto_scaling_group",
      "object_type": "AwsAutoScalingGroup",
      "has_many": false
    },
    ...
  ]

Search for Assets

Build a search query that retrieves assets that match specific criteria.

https://chapi.cloudhealthtech.com/api/search

Parameters

  • namerequired

    String that specifies the type asset object to query, for example, AWSInstance

  • queryrequired

    Criteria for finding assets of a particular asset object type. Criteria are specified as query=[field value][operator][value]. For example, query=name='MyAccount'+and+is_private=0

  • include

    String that specifies the name of a related asset object to include when returning a response. You cannot use both the include parameter and the fields parameter in the same GET query.

  • api_version

    Integer that specifies the API version to use. Possible values are 1 (default) and 2. Version 1 queries only return assets are are active. Version 2 queries return both active and inactive assets.

    • fields

      Only available when api_version=2. Comma-separated list that specifies the specific fields to return when querying the asset object.

    • page

      Only available when api_version=2. Integer that specifies the page to display when results run over multiple pages. Default value is 1. If this parameter is missing, the query returns all results, even if the per_page parameter is specified.

    • per_page

      Only available when api_version=2. Integer that specifies the number of assets to return per page. Default value is 100 and maximum value is 1000.

    • query

      Only available when api_version=2. Filter query results based on one or more field values. For example, return only active assets by setting this parameter to is_active=1.

See Asset Query Examples.

curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api/search?
  &api_version=2
  &page=1
  &per_page=5
  &name=AwsVolume
  &query=is_active=1
  &fields=in_use,attr_group__XXXXX,account.name

[
  {
  "in_use": true,
  "attr_group__XXXXXXYY": "Other",
  "account": {
    "name": "Primary Account",
    "id": 90
    },
  "id": XXXXXXYY
  },
  {
  "in_use": false,
  "attr_group__XXXXXXYY": "Other",
  "account": {
    "name": "Staging Account",
    "id": 90
    },
  "id": XXXXXXYYZZ
  },
  ...
  {
  "in_use": true,
  "attr_group__XXXXXXYY": "Other",
  "account": {
    "name": "Testing Account",
    "id": 1511828488197
    },
  "id": XXXXXXYYDD
  }
]

Asset Query Examples

Multiple examples that demonstrate how you can use the Asset API.

List API names for all asset types

curl -H 'Authorization: Bearer <your_api_key>'
  "https://chapi.cloudhealthtech.com/api"

List available fields for AWS RDS Instances

curl -H 'Authorization: Bearer <your_api_key>'
  "https://chapi.cloudhealthtech.com/api/AwsRdsInstance"

List available fields for Azure Virtual Machines

curl -H 'Authorization: Bearer <your_api_key>'
  "https://chapi.cloudhealthtech.com/api/AzureVm"

List available fields for AWS Load Balancer

curl -H 'Authorization: Bearer <your_api_key>'
  "https://chapi.cloudhealthtech.com/api/AwsLoadBalancer"

Filter AWS Load Balancers by name

curl -H 'Authorization: Bearer <your_api_key>' "https://chapi.cloudhealthtech.com/api/search?
  &name=AwsLoadBalancer
  &query=name='a45075XXXXXXYYYYYYZZZZZ96f99'"

Filter RDS Instances by instance ID and only display the instance IDs in the response

curl -H 'Authorization: Bearer <your_api_key>' "https://chapi.cloudhealthtech.com/api/search?
  &name=AwsRdsInstance
  &api_version=2
  &fields=instance_id
  &instance_id=<instance_id>"

List active AWS Volumes and only display their Perspective Groups and Accounts in the response

curl -H 'Authorization: Bearer <your_api_key>' https://chapi.cloudhealthtech.com/api/search?
  &api_version=2
  &page=1
  &per_page=5
  &query=is_active=1
  &name=AwsVolume
  &fields=in_use,attr_group__33XXSSDDYYYY,account.name
curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api/search?
  &api_version=2
  &page=1
  &per_page=5
  &name=AwsVolume
  &include=instance

Metrics

Introduction to Metrics API

An introduction to the Metrics API and its limitations.

The Metrics API allows REST-based access to performance metrics, such as CPU, Memory, and Disk for AWS assets.

The Metrics API allows you to read and write various performance metrics at this endpoint.

https://chapi.cloudhealthtech.com/metrics/v1

Once you have uploaded metrics, you have improved insight into the health and performance of your cloud environment. In addition, the CloudHealth Platform is able to generate better rightsizing recommendations based on these metrics.

Limitations

  • You can only post CPU, memory, and file system metrics.
  • You can only post up to 8 days of historical metrics data.
  • Metrics must have an hourly resolution.
  • An active AWS Instance associated with the metrics must already be present and active in the CloudHealth Platform and not be Chef-managed.
  • Metric retrieval is for individual assets only, that is, for AWS EC2 Instances or file systems of AWS EC2 Instances.
  • The payload can contain a max of 1000 data points. If there are more than 1000 data points, the entire request is rejected with a 422 response.
  • When posting to file systems, the associated instance must be present and active. However, if a file system object does not currently exist, a new one is automatically created and linked to the instance.

Rate Limits

Understand rate limits when making requests to the Metrics API.

CloudHealth limits the rate at the user, namely API key, level.

  • A total of 60 POST requests are allowed per minute.
  • Read requests are not throttled.
  • A 429 HTTP status code is returned if the request is throttled. The client should be written to handle this response and retry with an exponential backoff.
  • Since a payload can contain up to 1000 data points, a single client can push 60,000 data points per minute.

Understand Format of Metrics Payload

Learn how to format the payload for uploading metric to the CloudHealth Platform.

Familiarize yourself with the format of the payload that you can post through the Metrics API.

You can send metrics as a collection of datasets. Each dataset describes a single asset type, either instance or file system and consists of these components.

  • a metadata header describing the data being sent
  • an array of values that represent the actual metrics data

One or more datasets are bound up in a hash rooted with the metrics element.

"metrics": {
  "datasets": []
}

Here’s an example of the payload.

{
  "metrics": {
    "datasets": [
      {
        "metadata": {
          "assetType": "aws:ec2:instance",
          "granularity": "hour",
          "keys": [
            "assetId",
            "timestamp",
            "memory:free:bytes.avg",
            "memory:free:bytes.max",
            "memory:free:bytes.min"
            "memory:size:bytes.avg",
            "memory:size:bytes.max",
            "memory:size:bytes.min"
            "memory:used:percent.avg",
            "memory:used:percent.max",
            "memory:used:percent.min"
          ]
        },
        "values": [
          [
            "us-east-1:12345678:i-99999999",
            "2015-06-03T01:00:00+00:00",
            53687391300,
            107374182400,
            26843545600,
            322122547200,
            322122547200,
            322122547200,
            16.67,
            33.33,
            8.33
          ],
          [
            "us-east-1:12345678:i-88888888",
            "2015-06-03T02:00:00+00:00",
            53687391300,
            107374182400,
            26843545600,
            322122547200,
            322122547200,
            322122547200,
            16.67,
            33.33,
            8.33
          ]
        ]
      }
    ]
  }
}

Let’s take a look at the metadata array, which describes the data you are sending. It consists of these components:

  • an asset type
  • the granularity of the included data
  • an array of keys that describes the type of each element in the values array
"metadata": {
  "assetType": 'aws:ec2:instance',
  "granularity": 'hour',
  "keys" [
    "assetId",
    "timestamp",
    "memory:free:bytes.avg",
    "memory:free:bytes.max",
    ...
  ]
}

The metadata array contains the assetType, granularity, and keys fields, which can take specific values.

Field: assetType

Supported Values keys Field
aws:ec2:instance cpu:used:percent.avg
  cpu:used:percent.min
  cpu:used:percent.max
  memory:free:bytes.avg
  memory:free:bytes.min
  memory:free:bytes.max
  memory:size:bytes.avg
  memory:size:bytes.min
  memory:size:bytes.max
  memory:used:percent.avg
  memory:used:percent.min
  memory:used:percent.max
  assetId
  timestamp
aws:ec2:instance:fs fs:size:bytes.avg
  fs:size:bytes.min
  fs:size:bytes.max
  fs:used:bytes.avg
  fs:used:bytes.min
  fs:used:bytes.max
  assetId
  timestamp

Field: granularity Supported Values: hour

The values array has an entry for each series of metrics you want to post. Each entry is itself an array of metrics corresponding to the elements in the keys array, that is, in the same order and of the same length.

Each entry array consists of these components.

  • Instance specification using a compact form of the AWS ARN format (<region>:<account-number>:<AWS-instance-ID>) or file system specification using a compact form of the AWS ARN format (<region>:<account-number>:<AWS-instance-ID>:<file-system-mount-point>)
  • UTC-based timestamp that is on the hourly boundary specified in ISO-8601 format

An entry for instance might look like this.

"values": [
  [ "us-east-1:12345678:i-a99a99a9", "2015-06-03T00:01:00+00:00", 200, 400, ...],
  [ "us-east-1:12345678:i-a99a99a9", "2015-06-03T00:02:00+00:00", 100, 300, ...],
]

While an entry for a file system might look like this.

"values": [
  [ "us-east-1:12345678:i-a99a99a9:/opt", "2015-06-03T00:01:00+00:00", 200, 400, ...],
  [ "us-east-1:12345678:i-a99a99a9:/opt", "2015-06-03T00:02:00+00:00", 100, 300, ...],
]

Once you build the payload, you can use a cURL command to post it to the /metrics/v1 endpoint.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/metrics/v1" -d '{"metrics":{"datasets":[{"metadata":{"assetType":"aws:ec2:instance","granularity":"hour","keys":["assetId","timestamp","memory:usedPercent.avg","memory:usedPercent.max","memory:usedPercent.min"]},"values":[["us-east-1:12345678:i-99999999","2015-06-03T01:00:00+00:00",100.0,200.0,50.0],["us-east-1:12345678:i-88888888","2015-06-03T02:00:00+00:00",25.5,45.2,15.0]]}]}}'

Metrics for Single Asset

Retrieve CPU, memory, and performance metrics for a specific asset

https://chapi.cloudhealthtech.com/v1/metrics

Parameters

  • assetrequired

    String that specifies the AWS ARN that identifies the asset. The format is arn:aws:ec2:<region>:<owner-id>:instance/<AWS-instance-ID>. For example, arn:aws:ec2:us-east-1:123456789012:instance/i-01a1234b56cdef7g8.

  • granularity

    String that specifies the resolution at which data should be returned. Possible values are hour (default), day, week, and month.

  • from

    Date in YYYY-MM-DD format that specifies the start date from which you want to see metrics for the asset. You can use this parameter in conjunction with the to parameter to specify a custom date range for metrics retrieval.

  • to

    Date in YYYY-MM-DD format that specifies the end date up to which you want to see metrics for the asset. You can use this parameter in conjunction with the from parameter to specify a custom date range for metrics retrieval.

  • time_range

    String that specifies the time range limit to use when returning data. Possible values are yesterday (default), mtd, last_month, last_3_months, last_6_months, last_12_months, wtd, last_week, last_2_weeks, last_4_weeks, last_52_weeks, today, yesterday, last_2_days, last_7_days, last_14_days, and last_31_days

  • page

    Integer that specifies the page to display when results run over multiple pages. Default value is 1. If this parameter is missing, the query returns all results, even if the per_page parameter is specified.

  • per_page

    Integer between 1 and 500 that specifies the number of assets to return per page. Default value is 100 and maximum value is 1000.

By default, the request returns hourly sets of metric points for the previous day. If there are more than 100 data value sets, a next link to the next page of value sets is also returned

The response format is not wrapped in the metrics object. The response also contains a next link that can be followed to retrieve the next 100 metrics. The next attribute is null if there are no more records to retrieve.

time_range and granularity Considerations

Ensure that the value of the time_range parameter is large enough to encompass the requested granularity. For example, asking for yesterday’s data at a monthly resolution returns no rows, not an error. Requesting yesterday’s data with a granularity of day returns one row.

In addition, rollups are calculated daily. You will not receive today’s data at any granularity other than hourly, which is the default value.

curl 'https://chapi.cloudhealthtech.com/metrics/v1/?
  &asset=arn:aws:ec2:<region>:<owner-id>:instance/<AWS-instance-ID>'
  -H 'Authorization: Bearer <your_api_key>'
{
  "datasets": [
    "metadata" : {
      "assetType" : "aws:ec2:instance",
      "granularity" : "hour",
      "keys" : [
        "assetId",
        "timestamp",
        "cpu:used:percent.avg",
        "cpu:used:percent.max",
        "cpu:used:percent.min",
        "memory:free:bytes.avg",
        "memory:free:bytes.max",
        "memory:free:bytes.min",
        "memory:used:percent.avg",
        "memory:used:percent.max",
        "memory:used:percent.min"
      ]
    },
    "values" : [
      [ "us-east-1:12345678:i-99999999", "2017-10-22T05:00:00Z", 76, 99, 51, null, null, null, 22.5, 52.2, 18.1 ],
      [ "us-east-1:12345678:i-99999999", "2017-10-22T06:00:00Z", 91, 99, 81, null, null, null, 25.2, 53, 19.7 ]
    ]
  ]
}

Upload Metrics for Single Asset

Post metrics for an individual asset, including historical metrics data.

https://chapi.cloudhealthtech.com/v1/metrics

Parameters

  • JSON documentrequired

    Payload containing the metrics that you want to post. See Understand Format of Metrics Payload.

  • dryrun

    Test a POST operation without triggering a database change. Specified as true or false (default).

You can only post up to 8 days of historical metrics data.

The format of the response payload is similar to this one.

"succeeded": <The total number of rows that were successfully processed.>,
"failed": <The total number of rows that were rejected.>,
"errors": [
  "<A textual description of all errors that prevented the entire payload or an entire dataset from being processed.>"
]

# Datasets provide details of failures at the row level within each dataset.
"datasets": [
{
  "succeeded": <Count of all rows in this dataset that were successfully added to the system.>,
  "errors": [
      "<Textual representation of any errors that prevented all data in this dataset from being processed.>"
  ],
  "failures": [
    {
      "error": "<Textual representation of any parsing errors that prevented a single row of data from being accepted.>"
      "row:" <The original row data that was passed in>
    }
  ]
}
Response code Meaning
200 Success / Partial failure
400 No data was processed. Possibly malformed JSON document.
429 Request was throttled
500 Error with CloudHealth servers. Do not resend request immediately.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/metrics/v1" -d '{"metrics":{"datasets":[{"metadata":{"assetType":"aws:ec2:instance","granularity":"hour","keys":["assetId","timestamp","memory:usedPercent.avg","memory:usedPercent.max","memory:usedPercent.min"]},"values":[["us-east-1:12345678:i-99999999","2015-06-03T01:00:00+00:00",100.0,200.0,50.0],["us-east-1:12345678:i-88888888","2015-06-03T02:00:00+00:00",25.5,45.2,15.0]]}]}}'
{
  succeeded: 198,
  failed:    2,
  errors:    0,
  datasets:  [
    {
      "succeeeded": 100,
      "errors": [],
      "failures": []
    },
    {
      "succeeeded": 98,
      "errors": [],
      "failures": [
      {
        "error": "Number of values (6) must equal number of keys (5).",
        "row": [
          "us-east-1:12345678:i-99999999",
          "2015-06-03T02:00:00+00:00",
          100,
          75,
          50,
          111
        ]
      },
      {
        "error": "Percentage value (101) is greater than 100.",
        "row": [
          "us-east-1:12345678:i-88888888",
          "2015-06-03T03:00:00+00:00",
          101,
          75,
          50
        ]
      },
    ]
  },
  ]
}

Tagging

Introduction to Tagging API

An introduction to the Tagging API and its limitations.

The Tagging API allows you to add tags (key-value pairs) to objects in the CloudHealth Platform, including taggable AWS assets, AWS accounts, taggable Azure assets, taggable GCP assets, and Data Center servers. These tags are completely independent of your cloud provider tags.

When you tag objects using this API, the resources are only tagged in the CloudHealth Platform. The tags do not cascade down to your cloud provider (AWS, Azure, GCP, or Data Center). CloudHealth continues to pull tags from both your cloud provider.

The Tagging API allows you to add tags at this endpoint.

https://chapi.cloudhealthtech.com/v1/custom_tags

Limitations

  • No more than 100 instances per request
  • No more than 100 tags per instance
  • Tag keys must be between 1 and 127 characters long
  • Tag values must be no longer than 255 characters long
  • Tag values must be scalar. Lists and objects are not allowed. Numbers will be converted to strings.
  • Tag value will be stripped of leading and trailing whitespace

How Tags are Processed

Understand the process through which CloudHealth updates tags.

You can use the Tagging API to add new tags as well update existing ones. For either operation, you pass a tagging payload with the API request. Here is an example of the payload structure.

{
  "tag_groups": [
    {
      "asset_type": "AwsAccount",
      "ids": [12345, 56789],
      "tags": [{"key": "owner", "value": "Fred"}]
    },
    {
      "asset_type": "AwsInstance",
      "ids": [1511831925873],
      "tags": [{"key": "environment", "value": "Test"}, {"key": "owner", "value": "Mary"}]
    },
    {
      "asset_type": "AwsRdsInstance",
      "ids": [206158446754],
      "tags": [{"key": "environment", "value": "Production"}, {"key": "owner", "value": "Mary"}]
    }
  ]
}
  • asset_type is an asset that you can tag in the CloudHealth Platform.
  • ids is a list of CloudHealth IDs
  • tags is a list of key-value tag pairs

CloudHealth runs through the following process when it receives the payload. The entire payload is processed. If failures occur, they are identified and processing continues.

Update Tags for Single Asset

Add, remove, or update tags that are associated with an asset.

https://chapi.cloudhealthtech.com/v1/custom_tags

Parameters

The response to the post request is JSON.

  • Each successful update is shown to the updates array in the response.
  • Each partial failure is returned with an indication of which object or tag failed. Where possible, a descriptive message is also provided.
  • If there is a mix of updates and errors, the HTTP response code will still be 200 OK.
curl -H 'Authorization: Bearer <your_api_key>' -H "Accept: application/json" -H 'Content-Type: application/json' -XPOST 'https://chapi.cloudhealthtech.com/v1/custom_tags'
  -d '{
    "tag_groups":[
      {
        "asset_type": "AwsAccount",
        "ids": [90],
        "tags": [
          {
            "key": "testtag1",
            "value": null
          }
        ]
      }
    ]
  }'
{
  "updates": [
    {
      "asset_type": "AwsAccount",
      "asset_id": 12345,
      "tag_key": "owner",
      "tag_value": "Fred"
    },
    {
      "asset_type": "AwsAccount",
      "asset_id": 56789,
      "tag_key": "owner",
      "tag_value": "Fred"
    },
    {
      ...
    }
  ],
  "errors": [
    {
      "message": "Asset does not exist or user does not have access",
      "asset_type": "AwsRdsInstance",
      "asset_id": 206158446754
    }
  ]
}

Partner

Introduction to Partner API

An introduction to the Partner API.

Partners and their customers are organized as tenants in a hierarchical, multi-tenant system in the Partner Platform. Customer tenants are subordinates of their corresponding Partner Tenant.

The Partner API allows partners to get reports, metrics, and assets for their customers. In order to use the Partner API, you need to include an additional parameter, the client_api_id, with each request. CloudHealth generates a unique ID for each partner customer. See How to Get Client API ID.

How to Get Client API ID

In order to use the Partner API, you need to include an additional parameter, the client_api_id, with each request. CloudHealth generates a unique ID for each partner customer.

You can get the Client API ID for a customer from the CloudHealth Platform. From the left menu, select Partner > Customer > List. If the Client API Id column is not visible in the report, add it by clicking the Edit Columns button.

Specific Customer Report

Retrieve a specific Standard Report for a specific customer tenant.

https://chapi.cloudhealthtech.com/olap_reports/:report-type/:report-id

Parameters

  • client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.

Refer to Data for Standard Report for more information on retrieving data from a standard report.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost/history?client_api_id=<customer_api_id>'
#!/usr/bin/env ruby

require "rubygems"
require "net/https"
require "uri"
require "json"

API_ENDPOINT = "https://chapi.cloudhealthtech.com/olap_reports/cost/history"
API_KEY = "<your api key>"
CLIENT_API_ID = "<api id for client>"

# Returns json for requested assets.
def get_report(api_key, client_api_id, interval, query = "")
uri = URI(API_ENDPOINT) + URI.escape("?api_key=#{api_key}&client_api_id=#{client_api_id}&interval=#{interval}&query=#{query}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
response = http.request(request)
raise "Server returned error #{response.code} processing your API request" if response.code != "200"
JSON.parse(response.body)
end

# Fetch all CostHistory objects for the current month
month = Time.now.strftime '%Y-%m-01'
cost_history = get_report(API_KEY, CLIENT_API_ID, 'monthly')
months = cost_history["dimensions"][0]["time"].collect{ |t| t["label"] }
puts "| Month:\tCost"
puts "|----------------------------------|"
months.each_with_index do | month, i |
costs =  cost_history["data"].collect{ |month_cost| month_cost[0][0] }
row = "| %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s |"
puts "| #{month}:\t#{cost_history["data"][i][0][0]}"
end

Assets for Specific Customer

Retrieve a list of assets associated with a specific partner customer.

https://chapi.cloudhealthtech.com/api/search.json?api_version=2

Parameters

  • client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID

  • namerequired

    String that specifies the unique display name of the customer’s AWS account.

curl 'https://chapi.cloudhealthtech.com/api/search.json?api_version=2&client_api_id=<customer_api_id>
  &name=AwsAccount'
  -H 'Authorization: Bearer <your_api_key>'

Create Partner Customer

Add a partner customer tenant in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/customers

Parameters

  • namerequired

    String that specifies the unique display name of the customer’s AWS account.

  • addressrequired

    JSON field that specifies the customer’s mailing address.

    • street1required

      Line 1 of street address

    • street2required

      Line 2 of street address. Can be blank.

    • cityrequired

      City specified as a string

    • staterequired

      State specified in abbreviated form. For example, specify Massachusetts as MA. For non-US countries, use the full, ASCII-transliterated state names. For example, for Australian state names, specify Australian Capital Territory, New South Wales, Northern Territory, and so on.

    • zipcoderequired

      Zipcode specified as a number

    • countryrequired

      Country specified a string

  • classification

    String that specifies the level of access the customer has in the CloudHealth Platform. Specify as managed_without_access (managed customer that does not directly access the CloudHealth Platform) or managed_with_access (managed customer that directly accesses the CloudHealth Platform).

  • trial_expiration_date

    Date specified in ISO8601 format that indicates a date in the future when the customer’s trial expires. Beyond this date, users belonging to the customer are unable to access the CloudHealth Platform.

  • billing_contact

    String that specifies the email address of customer contact.

  • partner_billing_configuration

    Composite JSON field that specifies the configuration for the partner billing engine.

    • enabledrequired

      Boolean field that specifies whether partner billing is enabled. Default value is false.

    • folder

      String that specifies the prefix of the S3 folder that contains processed customer bills.

  • tags

    JSON array that specifies key-value pairs for tags to attach to the customer. Each customer can be assigned a maximum of 20 tags.

    • keyrequired

      Tag key

    • valuerequired

      Tag value

{
  "name": "Acme Corp",
  "classification": "managed_without_access",
  "billing_contact": "john.doe@acmecorp.com",
  "trial_expiration_date": "2016-09-22T00:00:00Z",
  "partner_billing_configuration": {
    "enabled": "true",
    "folder": ""
  },
  "address": {
    "street1": "1 Main St",
    "city": "Springfield",
    "state": "MA",
    "zipcode": "01234",
    "country": "US"
  },
  "tags": [{
    "key": "customer_id", "value": "973532"
  },
  {
    "key": "service_package", "value": "basic_managed"
  }]
}
{
  "id": 3947,
  "name": "Acme Corp",
  "classification": "managed_without_access",
  "billing_contact": "john.doe@acmecorp.com",
  "margin_percentage": 0.0,
  "created_at": "2016-09-15T18:17:04Z",
  "updated_at": "2016-09-15T18:17:04Z",
  "generated_external_id": "1a2b3c4d5e6f",
  "partner_billing_configuration": {
      "enabled": false,
      "folder": ""
  },
  "address": {
      "street1": "1 Main St",
      "city": "Springfield",
      "state": "MA",
      "zipcode": "01234",
      "country": "US"
  },
  "tags": [{
            "key": "customer_id", "value": "973532"
          },
          {
            "key": "service_package", "value": "basic_managed"
          }
  ],
  "_links": {
      "self": {
       "href": "/v1/customers/3947"
    }
  }
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "name": "Acme Corp",
    "classification": "managed_without_access",
    "billing_contact": "john.doe@acmecorp.com",
    "trial_expiration_date": "2016-09-22T00:00:00",
    "partner_billing_configuration": {
        "enabled": "false",
        "folder": ""
    },
    "address": {
      "street1": "1 Main St",
      "city": "Springfield",
      "state": "MA",
      "zipcode": "01234",
      "country": "US"
      }
    }'
    'https://chapi.cloudhealthtech.com/v1/customers'

Modify Existing Customer

Modify a partner customer tenant that already exists in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/customers/:customer_id

{
  "name": "Acme Corporation",
  "classification": "managed_with_access"
}
{
  "id": XXXX,
  "name": "Acme Corporation",
  "classification": "managed_with_access",
  "billing_contact": "john.doe@acmecorp.com",
  "margin_percentage": 0.0,
  "created_at": "2016-09-15T13:10:47Z",
  "updated_at": "2016-09-15T16:46:34Z",
  "generated_external_id": "1a2b3c4d5e6f",
  "partner_billing_configuration": {
      "enabled": true,
      "folder": ""
  },
  "address": {
     "street1": "1 Main St",
     "street2": "",
     "city": "Springfield",
     "State": "MA",
     "zipcode": "01234",
     "Country": "US"
  },
  "_links": {
      "self": {
          "href": "/v1/customers/XXXX"
      }
  }
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
  "name": "Acme Corporation",
  "classification": "managed_with_access"
}'
'https://chapi.cloudhealthtech.com/v1/customers/<customer_id>'

Delete Existing Customer

Delete a partner customer tenant from the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/customers/:customer_id

curl -X "DELETE" 'https://chapi.cloudhealthtech.com/v1/customers/<customer_id>'
  -H 'Authorization: Bearer <your_api_key>'

Get Single Customer

Retrieve a specific customer tenant.

https://chapi.cloudhealthtech.com/v1/customers/:customer_id

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customers/<customer_id>'

Get All Customers

Retrieve a list of all customer tenants.

https://chapi.cloudhealthtech.com/v1/customers

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customers'

Statement for Single Customer

Retrieve the billing statement for a specific partner customer.

https://chapi.cloudhealthtech.com/v1/customer_statements

Parameters

  • client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customer_statements?client_api_id=<client_api_id>'
{
  customer_id : 1211,
  billing_period : "2016-08",
  total_amount : 211,523.09,
  status : "estimated",
  detailed_billing_records_generation_time : "2016-08-23 23:59:11",
  statement_generation_time : "2016-08-23 23:59:41",
  statement_summary_generation_time : "2016-08-23 23:59:53",
  currency: {
    name: "USD",
    symbol: "$"
  }
}

Statements for All Customers

Retrieve billing statements for all partner customers.

https://chapi.cloudhealthtech.com/v1/customer_statements

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customer_statements'
{
  customer_id : 1211,
  billing_period : "2016-08",
  total_amount : 211,523.09,
  status : "estimated",
  detailed_billing_records_generation_time : "2016-08-23 23:59:11",
  statement_generation_time : "2016-08-23 23:59:41",
  statement_summary_generation_time : "2016-08-23 23:59:53",
  currency: {
    name: "USD",
    symbol: "$"
  }
}

Connect GovCloud Commercial Account to GovCloud Asset Account

Link a GovCloud account that receives the Detailed Billing Record with the GovCloud account that owns AWS assets.

https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages

Parameters

GovCloud Commercial Account: The proxy account that contains the costs for the account in the Detailed Billing Record.

GovCloud Asset Account: The account that owns the AWS assets.

The CloudHealth Platform validates the relationship between these two accounts as expressed by the JSON payload by using these considerations.

  • Both accounts are owned by the customer associated with the logged in user.
  • Neither account is in an existing GovCloud relation
  • The GovCloud Asset Account specified must have is_govcloud set to true, indicating that it is associated with a GovCloud region.
  • The GovCloud Commercial account is the opposite, must not be in the AWS GovCloud Region.

If any of these validations fails, a list of errors is returned.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages?
client_api_id=<customer_api_id>' -d
{
  "govcloud_acct_id": 1,
  "commercial_acct_id": 2
}
'{
  "id": 8,
  "customer_id": XXXX,
  "govcloud_acct": 1,
  "commercial_acct": 2,
  "created_at": "2018-05-16T20:18:58Z",
  "updated_at": "2018-05-16T20:18:58Z"
}'

List All GovCloud Linkages Owned by Current Customer

Get all GovCloud linkages that are owned by the current customer.

https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages

Parameters

  • client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages?
client_api_id=<customer_api_id>'
[
  {
    "id": 8,
    "customer_id": XXXX,
    "govcloud_acct": 1,
    "commercial_acct": 2,
    "created_at": "2018-05-16T20:18:58Z",
    "updated_at": "2018-05-16T20:18:58Z"
  },
  {
    "id": 17,
    "customer_id": YYYY,
    "govcloud_acct": 3,
    "commercial_acct": 6,
    "created_at": "2018-05-16T20:18:58Z",
    "updated_at": "2018-05-16T20:18:58Z"
  },
  {
    "id": 25,
    "customer_id": ZZZZ,
    "govcloud_acct": 5,
    "commercial_acct": 8,
    "created_at": "2018-05-16T20:18:58Z",
    "updated_at": "2018-05-16T20:18:58Z"
  }
]

Details of Single GovCloud Linkage

Get details for a specific GovCloud linkage.

https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/:id

Parameters

  • client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/25?
client_api_id=<customer_api_id>
{
    "id": 25,
    "customer_id": ZZZZ,
    "govcloud_acct": 5,
    "commercial_acct": 8,
    "created_at": "2018-05-16T20:18:58Z",
    "updated_at": "2018-05-16T20:18:58Z"
}

Update Single GovCloud Linkage

Update a specific relationship between a GovCloud Commercial Account and GovCloud Asset Account.

https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/:id

Parameters

  • client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/25?
client_api_id=<customer_api_id>' -d
'{
  "govcloud_acct_id": 17,
  "commercial_acct_id": 25
}'
{
    "id": 25,
    "customer_id": ZZZZ,
    "govcloud_acct": 17,
    "commercial_acct": 25,
    "created_at": "2018-05-16T20:18:58Z",
    "updated_at": "2018-05-16T20:18:58Z"
}

Understand Format of GovCloud Linkage Payload

Learn how to format the relationship that establishes a GovCloud linkage.

Familiarize yourself with the format of the payload that you can post to define the linkage between a GovCloud Commercial Account and a GovCloud Asset Account.

GovCloud Commercial Account: The proxy account that contains the costs for the account in the Detailed Billing Record.

GovCloud Asset Account: The account that owns the AWS assets.

Express a linkage between two of these accounts in the following format:

{
  "govcloud_acct_id": 1,
  "commercial_acct_id": 2
}

In order to get the values of govcloud_acct_id and commercial_acct_id use these steps:

  1. Make a GET request as shown in AWS Accounts in CloudHealth.
  2. From the response, which contains all AWS accounts associated with the customer, isolate the GovCloud Commercial Account and the GovCloud Asset Account.
  3. Copy the value of the id field for both accounts.
  4. Use the id of the GovCloud Commercial Account as the value of govcloud_acct_id and the id of the GovCloud Asset Account as the value of commercial_acct_id.

Partner AWS Account Assignment

Introduction to Partner AWS Account Assignment API

An introduction to the Account Assignment API.

Use this API to administer AWS Accounts that belong to CloudHealth Partners and to assign AWS accounts to Partner Customers for partner-generated billing purposes.

Partner AWS Account Assignment API is available in two versions:

  • Version 2: This API supports partner billing blocks and allows partners to assign AWS accounts in billing blocks to partner customers programmatically. Once you have assigned AWS accounts to a partner customer using Version 2 API, you can no longer use Version 1 API to assign, modify, get, or delete account assignments for that partner customer.
  • Version 1: This legacy API was created prior to the release of the partner billing block feature, which allows partners to quickly and easily assign multiple accounts in different billing configurations to partner customers at the same time. Consequently, Version 1 API does not support billing blocks.

CloudHealth recommends using Version 2 API to create new account assignments for partner customers and switching Version 1 partner customers to Version 2.

How AWS Account Assignments are Validated (Version 2)

Understand the criteria through which CloudHealth validates Partner AWS Account assignments.

CloudHealth uses the following criteria to validate AWS Account assignments.

  • The owner_id matches the owner_id of an AWS account in the partner’s CloudHealth account.
  • The owner_id is assigned to only one target_client_api_id.
  • You cannot merge two or more AWS accounts into one Partner Generated Billing account in CloudHealth.
  • When creating a family billing block, if you enter the owner_id of a consolidated AWS account, all AWS accounts linked to the consolidated account are also assigned to the specified target_client_api_id.

Create AWS Account Assignment (Version 2)

Assign AWS accounts to Partner Customers in billing blocks for partner-generated billing purposes.

https://chapi.cloudhealthtech.com/v2/aws_account_assignments

Parameters

  • target_client_api_idrequired

    String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.

  • billing_block_name

    String that specifies the unique name of the billing block.

  • billing_block_typerequired

    JSON field that specifies whether the bill generation type of the billing block is Family, Consolidated, or Standalone.

  • owner_idrequired

    The owner ID of the AWS account in the billing block. For family billing blocks, enter the owner ID of the billing family. For consolidated and standalone billing blocks, enter a comma-separated list of the owner IDs of all the AWS accounts in the billing block.

  • payer_account_owner_id

    For consolidated billing blocks, specify the owner ID of the designated payer account.

If the corresponding AWS account does not exist in the customer’s CloudHealth account, it is created. If there is an error associated with one AWS account, none of the accounts in the request are assigned.

Response Code Description
200 OK Operation was successful
422 Unprocessable Entity Unprocessable entity
{
  "aws_account_assignments": [
    {
      "target_client_api_id": 123,
      "billing_block_name": "block name1",
      "billing_block_type": "Family",
      "owner_id": "000000000001"
    },
    {
      "target_client_api_id": 1234,
      "billing_block_name": "block name2",
      "billing_block_type": "Consolidated",
      "owner_id": [
        "000000000002",
        "000000000003"
      ],
    "payer_account_owner_id": "000000000002"
    },
    {
      "target_client_api_id": 1234,
      "billing_block_name": "block name3",
      "billing_block_type": "Standalone",
      "owner_id": [
        "000000000004"
      ]
    }
  ]
}
{
  "aws_account_assignments": [
    {
      "id": 123333333333,
      "owner_id": "000000000001",
      "target_client_api_id": 123,
      "payer_account_owner_id": "000000000001",
      "billing_block_type": "Family",
      "billing_block_name": "block name1",
      "errors": {}
    },
    {
      "id": 123333333334,
      "owner_id": "000000000002",
      "target_client_api_id": 1234,
      "payer_account_owner_id": "000000000002",
      "billing_block_type": "Consolidated",
      "billing_block_name": "block name2",
      "errors": {}
    },
    {
      "id": 123333333335,
      "owner_id": "000000000003",
      "target_client_api_id": 1234,
      "payer_account_owner_id": "000000000002",
      "billing_block_type": "Consolidated",
      "billing_block_name": "block name2",
      "errors": {}
    },
    {
      "id": 123333333336,
      "owner_id": "000000000004",
      "target_client_api_id": 1234,
      "payer_account_owner_id": "000000000004",
      "billing_block_type": "Standalone",
      "billing_block_name": "block name3",
      "errors": {}
    }
  ]
}
curl --request POST
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'
  -d\
  '{
    "aws_account_assignments": [
      {
        "target_client_api_id": 123,
        "billing_block_name": "block name1",
        "billing_block_type": "Family",
        "owner_id": "000000000001"
      },
      {
        "target_client_api_id": 1234,
        "billing_block_name": "block name2",
        "billing_block_type": "Consolidated",
        "owner_id": [
          "000000000002",
          "000000000003"
        ],
      "payer_account_owner_id": "000000000002"
      },
      {
        "target_client_api_id": 1234,
        "billing_block_name": "block name3",
        "billing_block_type": "Standalone",
        "owner_id": [
          "000000000004"
        ]
      }
    ]
  }'\
  'https://chapi.cloudhealthtech.com/v2/aws_account_assignments'

Get All AWS Account Billing Blocks (Version 2)

Retrieve a list of all AWS billing blocks and their account assignments.

https://chapi.cloudhealthtech.com/v2/aws_account_assignments

Response header

  • X-Total: The total number of AWS account assignments
  • X-Per-Page: The number of AWS account assignments that are returned per page

Response content

A JSON object with one field, aws_account_assignments, whose value is an array of objects with the following fields:

  • id: The ID of an AWS account assignment
  • owner_id: The AWS ID of the assigned account
  • target_client_api_id: the client API ID of the customer
  • payer_account_owner_id: The AWS ID of the account whose bills receive the billing line items for the assigned account
  • billing_block_type: The type of billing block
  • billing_block_name: The name of the billing block

The response content is paged if the total number of AWS account assignments is greater than the number that is returned per page.

curl --request GET \
  'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/' \
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer <your_api_key>'

Get Single AWS Account Assignment (Version 2)

Retrieve information on a single AWS account assignment.

https://chapi.cloudhealthtech.com/v2/aws_account_assignments/:id

Response content

A JSON object with the following fields:

  • id: The ID of an AWS account assignment
  • owner_id: The AWS ID of the assigned account
  • target_client_api_id: the client API ID of the customer
  • payer_account_owner_id: The AWS ID of the account whose bills receive the billing line items for the assigned account
  • billing_block_type: The type of billing block
  • billing_block_name: The name of the billing block
curl --request GET \
  'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/<id>' \
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'

Update AWS Account Billing Block (Version 2)

Update which AWS account is the designated payer account in an existing consolidated billing block.

https://chapi.cloudhealthtech.com/v2/aws_account_assignments/:target_client_api_id

Parameters

  • billing_block_namerequired

    String that specifies the name of the consolidated billing block.

  • payer_account_owner_idrequired

    specify the owner ID of the designated payer account for the consolidated billing block.

Response Code Description
200 OK Operation was successful
422 Unprocessable Entity Unprocessable entity
{
  "billing_block_name": "block name2",
  "payer_account_owner_id":"000000000003"
}
{
  "aws_account_assignments": [
    {
      "id": 123333333334,
      "owner_id": "000000000002",
      "target_client_api_id": 1234,
      "payer_account_owner_id": "000000000003",
      "billing_block_type": "Consolidated",
      "billing_block_name": "block name2",
      "errors": {}
    },
    {
      "id": 123333333335,
      "owner_id": "000000000003",
      "target_client_api_id": 1234,
      "payer_account_owner_id": "000000000003",
      "billing_block_type": "Consolidated",
      "billing_block_name": "block name2",
      "errors": {}
    },
  ]
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d\
  '{
    "billing_block_name": "block name2",
    "payer_account_owner_id":"000000000003"
  }'\
  'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/<target_client_api_id>'

Delete AWS Account Assignment (Version 2)

Delete the relationship between an AWS account and the Partner Customer to which it was assigned. For consolidated billing blocks, the designated payer account assignment cannot be deleted through an API endpoint and must be deleted in the CloudHealth Platform. Note: If all accounts assigned to a billing block are deleted, the billing block is also deleted.

https://chapi.cloudhealthtech.com/v2/aws_account_assignments/:id

Response Code Description
200 OK Operation was successful
400 Bad Request Unprocessable entity
curl --request
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'
  DELETE \
  'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/<id>' \

How AWS Account Assignments are Validated (Version 1)

Understand the criteria through which CloudHealth validates Partner AWS Account assignments.

CloudHealth uses the following criteria to validate AWS Account assignments.

  • All required parameters are provided when you create an AWS account assignment. Review Required Parameters.
  • The owner_id matches the owner_id of an AWS account in the partner’s CloudHealth account.
    • This owner_id does not belong to any other AWS account assignment for the partner.
    • In AWS, the partner’s corresponding AWS account belongs to another account’s consolidated billing family.
  • The customer_id matches the id of a customer that belongs to the partner.
    • This customer has partner billing enabled by setting enabled to true in its partner_billing_configuration.
  • For each customer identified by customer_id, all AWS account assignments follow one of these patterns:
    • All of the customer’s AWS accounts are standalone, each corresponding assignment’s payer_account_owner_id matches its owner_id.
    • Only one of the customer’s AWS accounts is assigned as a consolidated account. Its assignment’s payer_account_owner_id matches its owner_id. All other accounts are assigned as being linked to it. Each corresponding assignment’s payer_account_owner_id matches the consolidated account’s owner_id.
  • If this is a linked account assignment, where the payer_account_owner_id does not match the owner_id, then the payer_account_owner_id matches the owner_id of a prior AWS account assignment for the same customer_id. These additional criteria apply:
    • The prior AWS account assignment for the payer account, the one whose owner_id matches this assignment’s payer_account_owner_id—satisfies the following criteria:
      • The owner_id matches the payer_account_owner_id.
    • In AWS, both accounts belong to the same consolidated billing account family—the partner has a single account whose consolidated billing configuration contains both customer accounts as linked accounts.

Create AWS Account Assignment (Version 1)

Assign AWS accounts to Partner Customers for partner-generated billing purposes.

https://chapi.cloudhealthtech.com/v1/aws_account_assignments

Parameters

  • owner_idrequired

    The AWS ID of the assigned account.

  • customer_idrequired

    The ID of the customer to whom the account is assigned. For information on how to get this ID, see Create Partner Customer.

  • payer_account_owner_id

    The AWS ID of the account whose bills should receive the billing line items for the assigned account.

If the corresponding AWS account does not exist in the customer’s CloudHealth account, it is created.

Response Code Description
200 OK Operation was successful
422 Unprocessable Entity Unprocessable entity

Response header

  • Location: The location of the created AWS account assignment.

Response content

A JSON object that contains these fields:

  • All the fields in the request
  • id: The ID of the AWS account assignment that was created
{
  "owner_id": "000000000001",
  "customer_id": 1,
  "payer_account_owner_id": "000000000001"
}
{
  "customer_id": 1,
  "id": 1,
  "owner_id": "000000000001",
  "payer_account_owner_id": "000000000001"
}
curl --request POST
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json' -d
  '{
    "owner_id": "000000000001",
    "customer_id": 1,
    "payer_account_owner_id": "000000000001"
  }'
  'https://chapi.cloudhealthtech.com/v1/aws_account_assignments'

Read All AWS Account Assignments (Version 1)

Get information on all AWS account assignments.

https://chapi.cloudhealthtech.com/v1/aws_account_assignments

Response header

  • X-Total: The total number of AWS account assignments
  • X-Per-Page: The number of AWS account assignments that are returned per page
  • Link: A list of pages if the response content is truncated due to paging

Response content

A JSON object with one field, aws_account_assignments, whose value is an array of objects with the following fields:

  • id: The ID of an AWS account assignment
  • owner_id: The AWS ID of the assigned account
  • customer_id: The ID of the customer to whom the account is assigned
  • payer_account_owner_id: The AWS ID of the account whose bills receive the billing line items for the assigned account

The response content is paged if the total number of AWS account assignments is greater than the number that is returned per page.

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
  'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/'

Read Single AWS Account Assignment (Version 1)

Get information on a single AWS account assignment.

https://chapi.cloudhealthtech.com/v1/aws_account_assignments

Parameters

  • idrequired

    The ID of the AWS account assignment

Response content

A JSON object with one field, aws_account_assignments, whose value is an array of objects with the following fields:

  • id: The ID of an AWS account assignment
  • owner_id: The AWS ID of the assigned account
  • customer_id: The ID of the customer to whom the account is assigned
  • payer_account_owner_id: The AWS ID of the account whose bills receive the billing line items for the assigned account

The response content is paged if the total number of AWS account assignments is greater than the number that is returned per page.

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
  'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/<id>'

Update AWS Account Assignment (Version 1)

Update an existing AWS account assignment.

https://chapi.cloudhealthtech.com/v1/aws_account_assignments

Parameters

  • idrequired

    The ID of the AWS account assignment

  • owner_idrequired

    The AWS ID of the assigned account.

  • customer_idrequired

    The ID of the customer to whom the account is assigned. For information on how to get this ID, see Create Partner Customer.

  • payer_account_owner_id

    The AWS ID of the account whose bills should receive the billing line items for the assigned account.

Response Code Description
200 OK Operation was successful
422 Unprocessable Entity Unprocessable entity

Response header

  • Location: The location of the created AWS account assignment.

Response content

A JSON object that contains these fields:

  • All the fields in the request
  • id: The ID of the account assignment that was created
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "owner_id": "000000000001",
    "customer_id": 1,
    "payer_account_owner_id": "000000000001"
  }'
  'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/<id>'

Delete AWS Account Assignment (Version 1)

Delete the relationship between an AWS account and the Partner Customer to which it was assigned.

https://chapi.cloudhealthtech.com/v1/aws_account_assignments

Parameters

  • idrequired

    The ID of the AWS account assignment

Response Code Description
200 OK Operation was successful
422 Unprocessable Entity Unprocessable entity

Response header

  • Location: The location of the created AWS account assignment.

Response content

A JSON object that contains these fields:

  • All the fields in the request
  • id: The ID of the account assignment that was created
curl --request
  -H 'Authorization: Bearer <your_api_key>'
  DELETE -H 'Content-Type: application/json'
  'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/<id>'

Partner Custom Price Books

Introduction to Price Book API

An introduction to the custom price book API.

Custom price books allow you to develop a custom system of discounts, rates, and adjustments for customers on an individual level. At minimum, the following four API requests must be sent to set up custom price books:

  1. Create New Price Book
  2. Test New Price Book (Coming Soon)
  3. Assign Price Book to Customer
  4. Assign Price Book to Account

Create New Price Book

Create a new custom price book in the CloudHealth Platform that specifies custom billing rules for your customers.

https://chapi.cloudhealthtech.com/v1/price_books

Parameters

  • book_namerequired

    String that specifies the unique display name of the custom price book.

  • specificationrequired

    XML-formatted string that specifies the custom billing rules of the price book. See Understand Format of Price Book Specification.

{
  "book_name": "Gold tier",
  "specification": <XML>
}
{
  "id": XXXX,
  "book_name": "Gold tier",
  "file_hash": "0aa0d13204c2bb",
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01"
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "book_name": "Gold tier",
    "specification": <XML>
  }'
  'https://chapi.cloudhealthtech.com/v1/price_books'

Modify Existing Price Book

Modify a custom price book that already exists in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/price_books/:price book id

{
  "specification": <XML>
}
{
  "id": XXXX,
  "book_name": "Gold tier",
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01"
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "specification": <XML>
    }'
'https://chapi.cloudhealthtech.com/v1/price_books/<price book id>'

Delete Existing Price Book

Delete a custom price book from the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/price_books/:price book id

curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/<price book id>'

Get All Price Books

Retrieve a list of all your custom price books.

https://chapi.cloudhealthtech.com/v1/price_books/

[{
  "id": "1",
  "book_name": "Gold Tier",
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01",
  "file_hash": "8b5ad852dc6c11b730"
},
{
  "id": "3",
  "book_name": "Silver Tier"
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01",
  "file_hash": "0cd8f13406a4ae"
}]
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/'

Get Price Book Request

Retrieve a specific custom price book.

https://chapi.cloudhealthtech.com/v1/price_books/:id

{
  "id":61,
  "book_name":"Test Price Book",
  "file_hash":"3d9cb352ba6a00d3211ab8f18507c5ce",
  "created_at":"2018-01-01",
  "updated_at":"2018-01-25"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/<id>'

Details of Price Book Request

Get details for a specific custom price book.

https://chapi.cloudhealthtech.com/v1/price_books/:id/specification

{
  "specification": <XML>
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/<id>/specification'

Understand Format of Price Book Specification

Learn how to format the XML specification that establishes a custom price book.

Parameters

  • CHBillingRulesrequired

    Top-level element that specifies the customer by name and customer-id, and whether or not the customer gets a EC2 reserved instance volume discount or rate change.

    • createdBy

      String of the email address of the author of the XML specification

    • daterequired

      Date string specified in yyyy-mm-dd or mm/dd/yyyy of the date the XML specification was created

  • Comment

    String for documentation purposes specifying comments on the XML specification. Can be included in any element containing child elements.

  • RuleGrouprequired

    Groups together an ordered set of rules that share a common range of applicable dates. Child element of CHBillingRules.

    • startDate

      Date string specified in yyyy-mm-dd or mm/dd/yyyy of the date the rule group should take effect. If no date is specified, the rule group takes effect for all months.

    • endDate

      Date string specified in yyyy-mm-dd or mm/dd/yyyy of the date the rule group should cease effect. If no date is specified, the rule group takes effect for all months.

    • enabled

      Boolean field that specifies whether the rule group should be enabled, or true, or disabled, or false. Default value is true.

  • BillingRule

    Specifies which products and regions the rule applies to (e.g. which products and regions) and how to apply the discount. Child element of RuleGroup. Discount Rules are evaluated top-down.

    • namerequired

      String specifying the name of the rule for documentation purposes

    • includeDataTransfer

      Boolean field that specifies whether data transfer costs are covered by the rule. Default value is true.

    • includeRIPurchases

      Boolean field that specifies whether RI purchases are covered by the rule. Default value is true.

  • BasicBillingRule

    Specifies either a percentage discount from 0 to 100 or a fixed unit-price or rate. Child element of BillingRule.

    • billingAdjustmentrequired

      Numeric string between 0 and 100 specifying the discount or fixed rate amount

    • billingRuleTyperequired

      String specifying whether the discount is percentDiscount, percentIncrease, or fixedRate

  • Product

    Specifies the product a rule applies to and any constraints about when the rule should apply to the specified product. Usually a child element of BillingRule.

    • productNamerequired

      String specifying the name of the product as it appears in the billing file (case sensitive). Enter ANY to apply the rule to all products.

    • includeDataTransfer

      Boolean field that specifies whether data transfer costs are covered for this product. Overrides BillingRule. Default value is true.

    • includeRIPurchases

      Boolean field that specifies whether RI purchases are covered for this product. Overrides BillingRule. Default value is true.

  • Region

    Specifies the region a rule applies to. Usually a child element of Product or BillingRule.

    • namerequired

      String in AWS internal format that specifies the name of the region, such as us-east-2.

  • UsageType

    Specifies the usage type a rule applies to. Exclude the region on the billing file to apply UsageType to all regions and include the region to limit UsageType to that region. Child element of Product.

    • namerequired

      String specifying the usage type name, formatted to match the usage type name on the billing file without the instance-type prefixes and suffixes.

  • Operation

    Specifies the operations a rule applies to. Child element of Product.

    • namerequired

      String specifying the operation name, formatted to match the operation name on the billing file.

  • InstanceProperties

    Specifies whether the rule applies to the product for specific instance types and sizes and for reservations. Child element of Product.

    • instanceType

      String specifying the instance type the rule applies to for this product, such as t2

    • instanceSize

      String specifying the instance size the rule applies to for this product, such as 8xlarge

    • reserved

      Boolean field that specifies whether the rule applies to only reserved instances. Default value is false.

  • LineItemDescription

    Specifies a constraint on which products a rule applies to based on the contents of the line item description field in the billing file. Child element of Product.

    • startsWith

      String specifying the start of the line item description field

    • contains

      String specifying keywords in the line item description field

    • matchesRegex

      A Java string specifying a regular expression matching the line item description field

Familiarize yourself with the format of the XML specification that you can post to define the custom price book for a customer.

XML Formatting: XML is a file format that allows you to enter markup language that is both human-readable and machine-readable. Custom price book specifications are written in XML. To write your specifications, you need an XML editor. If you don’t already have an XML editor, CloudHealth recommends XML Spear.

Rule Order: Custom price book XML specifications process rules in top-down order. The first applicable rule that satisfies all specified constraints for a line item is used, and then no subsequent rules are used for that line item. If no applicable and matching rule is found, the line item will have a 0% calculated price adjustment.

Rule Applicability: Rule applicability is determined by the startDate and endDate attributes in enabled RuleGroup elements. startDates and endDates are inclusive. Whether or not an applicable rule is actually used depends on its order relative to other rules and the constraints it specifies for matching line items.

Example:

<CHBillingRules createdBy=\"user@partner.com\" date=\"2018-01-01\">
  <Comment>This is the Price Book specification for a Customer</Comment>

  <RuleGroup>

    <BillingRule name=\"10% on EC2\" includeDataTransfer=\"true\">
    <BasicBillingRule billingAdjustment=\"10.0\" billingRuleType=\"percentDiscount\"/>
      <Product productName=\"Amazon Elastic Compute Cloud\"/>
    </BillingRule>

    <BillingRule name\"$0.50 flat rate for CloudFront\">
    <BasicBillingRule billingAdjustment=\"0.5\" billingRuleType=\"fixedRate\"/>
      <Product productName=\"Amazon CloudFront\"/>
    </BillingRule>

    <BillingRule name=\"10% markup on RDS charges in us-east-1\">
    <BasicBillingRule billingAdjustment=\"10.0\" billingRuleType=\"percentIncrease\">
      <Product productName=\"Amazon Relational Database System\">
        <Region name=\"us-east-1\"/>
      </Product>
    </BillingRule>

  </RuleGroup>

</CHBillingRules>

Assign Price Book to Customer

Assign a custom price book to a customer or customers.

https://chapi.cloudhealthtech.com/v1/price_book_assignments

Parameters

  • price_book_idrequired

    Integer that specifies which custom price book to use.

  • target_client_api_idrequired

    Integer that specifies the assigned customer’s client_api_id.

{
  "price_book_id": XXXX,
  "target_client_api_id": <client_api_id>
}
{
  "id": <int>,
  "target_client_api_id": <client_api_id>,
  "price_book_id": XXXX,
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01"
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "price_book_id": XXXX,
    "target_client_api_id": <client_api_id>
  }'
  'https://chapi.cloudhealthtech.com/v1/price_book_assignments'

Modify Existing Price Book Customer Assignment

Modify which custom price book is assigned to a customer.

https://chapi.cloudhealthtech.com/v1/price_book_assignments/:id

{
  "price_book_id": XXXX
}
{
  "id": 6,
  "target_client_api_id": <client_api_id>,
  "price_book_id": XXXX,
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01"
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "price_book_id": XXXX
  }'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments/<id>'

Delete Existing Price Book Customer Assignment

Delete a custom price book’s customer assignment.

https://chapi.cloudhealthtech.com/v1/price_book_assignments/:id

curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments/<id>'

Get All Price Book Customer Assignments

Retrieve a list of all customers assigned to a custom price book.

https://chapi.cloudhealthtech.com/v1/price_book_assignments

{
  "id": 1,
  "price_book_id": XXXX,
  "target_client_api_id": <client_api_id>,
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments'

Get Price Book Customer Assignment

Retrieve one customer assigned to a custom price book.

https://chapi.cloudhealthtech.com/v1/price_book_assignments/:id

{
  "id": 1,
  "price_book_id": XXXX,
  "target_client_api_id": <client_api_id>,
  "created_at": "2018-01-01",
  "updated_at": "2018-01-01"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments/<id>'

Assign Price Book to Account

Assign a custom price book to a customer’s AWS accounts. The custom price book must have already been assigned to the customer.

https://chapi.cloudhealthtech.com/v1/price_book_account_assignments

Parameters

  • price_book_assignment_idrequired

    Integer that specifies which custom price book to use. This ID can be retrieved from the Get All Price Book Customer Assignments endpoint.

  • billing_account_owner_id

    String that specifies which account to assign the custom price books to. Enter ALL to assign the custom price book to all of the assigned customer’s accounts or enter a single account ID to assign the price book to one account. To assign the custom price book to multiple (but not all) accounts belonging to a customer, use the billing_account_owner_ids parameter.

  • billing_account_owner_ids

    Comma-separated list that specifies which accounts to assign the custom price books to. Use to assign the custom price book to multiple (but not all) of a customer’s accounts. To assign the price book to only one account, or to assign the price book to all accounts belonging to the customer, use the billing_account_owner_id parameter.

{
  "price_book_assignment_id": 6,
  "billing_account_owner_ids": ["343243","3432423"]
}
{
  "price_book_assignment_id": 6,
  "billing_account_owner_id": "12345"
}
{
  "price_book_assignment_id": 6,
  "billing_account_owner_id": "ALL"
}
{
  "price_book_account_assignments": [
  {
    "id": 52,
    "target_client_api_id": <client_api_id>,
    "price_book_assignment_id": 6,
    "billing_account_owner_id": "343243"
  },
  {
    "id": 53,
    "target_client_api_id": <client_api_id>,
    "price_book_assignment_id": 6,
    "billing_account_owner_id": "3432423"
  }
  ]
}
{
  "id": 54,
  "target_client_api_id": <client_api_id>,
  "price_book_assignment_id": 6,
  "billing_account_owner_id": "ALL"
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "price_book_assignment_id": XXXX,
    "billing_account_owner_id": "ALL"
  }'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments'

Modify Existing Price Book Account Assignment

Modify which AWS account a custom price book is assigned to.

https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/:id

{
  "billing_account_owner_id": <string>
}
{
  "id": 36,
  "target_client_api_id": <client_api id>,
  "price_book_assignment_id": <int>,
  "billing_account_owner_id": <string>
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "billing_account_owner_id": <string>
  }'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/<id>'

Delete Existing Price Book Account Assignment

Delete a custom price book’s AWS account assignment.

https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/:id

curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/<id>'

Get All Price Book Account Assignments

Retrieve a list of all AWS accounts assigned to a custom price book.

https://chapi.cloudhealthtech.com/v1/price_book_account_assignments

{
  "price_book_account_assignments": [
  {
  "id": 55,
  "target_client_api_id": <client_api id>,
  "price_book_assignment_id": <int>,
  "billing_account_owner_id": <string>
  },
  {
  "id": 56,
  "target_client_api_id": <client_api id>,
  "price_book_assignment_id": <int>,
  "billing_account_owner_id": <string>
  }
  ]
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments'

Get Price Book Account Assignment

Retrieve one AWS account assigned to a custom price book.

https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/:id

{
  "id": 56,
  "target_client_api_id": <client_api id>,
  "price_book_assignment_id": <int>,
  "billing_account_owner_id": <string>
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/<id>'

Azure Service Principals

Introduction to Azure Service Principal API

An introduction to the Azure Service Principal API.

The Azure service principal defines the access an application such as CloudHealth has to your Azure Portal data. Use this API to connect an Azure service principal to the CloudHealth Platform.

Depending on your account type, you need to complete different kinds of setup prior to using the Azure service principal API.

The Azure Service Principal API allows direct customers, partners, and partner customers to connect their service principal to CloudHealth. partners to get reports, metrics, and assets for their customers. In order to use some of the Azure Service Principal endpoints, you need to provide the sp_id. CloudHealth generates a unique ID for each service principal. See How to Get Service Principal ID.

How to Get Service Principal ID

In order to use some of the Azure Service Principal endpoints, you need to provide the sp_id. CloudHealth generates a unique ID for each service principal.

You can get the Service Principal ID for a customer’s service principal from the CloudHealth Platform. From the left menu, go to Setup > Accounts > Azure Service Principal and open the service principal. The ID of the service principal appears in the browser URL. Here’s an example URL:

https://apps.cloudhealthtech.com/azure_service_principals/33672XXXXXX68

Here, 33672XXXXXX68 is the service principal ID.

The Service Principal ID can also be retrieved using the Get All Existing Service Principals endpoint.

Connect Service Principal in CloudHealth

Connect a service principal to a customer, partner customer, and/or partner in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/azure_service_principals

Parameters

  • namerequired

    String that specifies the name of the service principal.

  • client_idrequired

    The client ID, or application ID, registered with the service principal.

  • client_secretrequired

    The secret key for the client ID.

  • tenant_idrequired

    The tenant ID, or directory ID, of the customer tenant.

  • sp_type

    JSON field that specifies whether the service principal type is global or govcloud. Default value is global.

  • is_metrics_enabled

    Boolean field that specifies whether metrics collection is enabled. Default value is true.

  • disable_assets_collection

    JSON field that specifies whether to not collect data for specific assets. Enter true to disable asset collection for the specified asset. Default value for all assets is false.

    • AzureActiveDirectoryRoleDefinition

      Boolean field that specifies whether to not collect data for the Azure Active Directory Role Definition asset. Default value is false.

    • AzureActiveDirectoryUser

      Boolean field that specifies whether to not collect data for the Azure Active Directory Users asset. Default value is false.

    • AzureKeyVaultKey

      Boolean field that specifies whether to not collect data for the Azure Key Vault Keys asset. Default value is false.

    • AzureKeyVaultSecret

      Boolean field that specifies whether to not collect data for the Azure Key Vault Secrets asset. Default value is false.

    • AzureSqlDatabaseAuditing

      Boolean field that specifies whether to not collect data for the Azure Sql Database Auditing asset. Default value is false.

    • AzureSqlDatabaseThreatDetection

      Boolean field that specifies whether to not collect data for the Azure Sql Database Threat Detection asset. Default value is false.

    • AzureSqlServerAuditing

      Boolean field that specifies whether to not collect data for the Azure Sql Server Auditing asset. Default value is false.

    • AzureSqlServerFirewallRule

      Boolean field that specifies whether to not collect data for the Azure SQL Server Firewall Rule asset. Default value is false.

    • AzureSqlServerThreatDetection

      Boolean field that specifies whether to not collect data for the Azure Sql Server Threat Detection asset. Default value is false.

    • AzureSubscriptionSecurityPolicy

      Boolean field that specifies whether to not collect data for the Azure Subscription Security Policy asset. Default value is false.

  • create_sp_for_partner_customer

    String that specifies the client API ID of the partner customer. Use this parameter only when connecting the service principal to a partner customer and partner in CloudHealth. For information on how to get this ID, see How to Get Client API ID.

{
  "name": "Production SP",
  "sp_type": "govcloud"  ,
  "client_id": "xndencrnvcr",
  "client_secret": "cbdefeb",
  "tenant_id": "356dnsdn",
  "is_metrics_enabled": false,
  "disable_assets_collection": [{
    "AzureKeyVaultKey": true,
    "AzureKeyVaultSecret": true
    }],     
  "create_sp_for_partner_customer": <client_api_id>
}
{
  "name": "Production SP",
  "sp_type": "govcloud"  ,
  "client_id": "xndencrnvcr",
  "client_secret": "cbdefeb",
  "tenant_id": "356dnsdn",
  "is_metrics_enabled": false,
  "disable_assets_collection": [{
    "AzureKeyVaultKey": true,
    "AzureKeyVaultSecret": true
    }],     
}
{
  "id": 1,
  "name": "Production SP",
  "sp_type": "govcloud" ,
  "client_id": "xndencrnvcr",
  "tenant_id": "356dnsdn",   
  "is_metrics_enabled": false,
  "created_at": "timestamp",
  "updated_at": "timestamp"
  "status" :[{
    "status": "healthy",
    "status_at": "timestamp"
    }],  
  "disable_assets_collection": [{              
    "AzureKeyVaultKey": true,                
    "AzureKeyVaultSecret": true
    }]
},

{
  "id": 2,
  "name": "Production SP",
  "sp_type": "govcloud" ,
  "client_id": "xndencrnvcr",
  "tenant_id": "356dnsdn",   
  "is_metrics_enabled": false,
  "created_at": "timestamp",
  "updated_at": "timestamp"
  "status" :[{
    "status": "healthy",
    "status_at": "timestamp"
    }],
  "disable_assets_collection": [{               
    "AzureKeyVaultKey": true,              
    "AzureKeyVaultSecret": true
    }]
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "name": "Production SP",
    "sp_type": "govcloud"  ,
    "client_id": "xndencrnvcr",
    "client_secret": "cbdefeb",
    "tenant_id": "356dnsdn",
    "is_metrics_enabled": false,
    "disable_assets_collection": [{
      "AzureKeyVaultKey": true,
      "AzureKeyVaultSecret": true
      }],     
    "create_sp_for_partner_customer": <client_api_id>
  }'
    'https://chapi.cloudhealthtech.com/v1/azure_service_principals'

Modify Existing Service Principal

Modify a service principal that is already connected in the CloudHealth Platform. The client_id, tenant_id and sp_type parameters cannot be modified.

https://chapi.cloudhealthtech.com/v1/azure_service_principals/:sp_id

Parameters

  • namerequired

    String that specifies the name of the service principal.

  • client_secretrequired

    The secret key for the client ID.

  • is_metrics_enabled

    Boolean field that specifies whether metrics collection is enabled. Default value is true.

  • modify_sp_for_partner_customer

    String that specifies the client API ID of the partner customer. Use this parameter only when modifying the service principal of a partner customer and partner in CloudHealth. For information on how to get this ID, see How to Get Client API ID.

  • disable_assets_collection

    JSON field that specifies whether to not collect data for specific assets. Enter true to disable asset collection for the specified asset. Default value for all assets is false.

{
  "name": "Production SP 1",
  "client_secret": "cbdefeb",
  "is_metrics_enabled": true,
  "modify_sp_for_partner_customer": <client_api_id>
  "disable_assets_collection"             
  [{
    "AzureKeyVaultKey" : true,
    "AzureKeyVaultSecret": false
  }]
}
{
  "name": "Production SP 1",
  "client_secret": "cbdefeb",
  "is_metrics_enabled": true,
  "disable_assets_collection"             
  [{
    "AzureKeyVaultKey": true,
    "AzureKeyVaultSecret": false
  }]
}
{
  "id":1,
  "name": "Production SP 1",
  "sp_type":"global" ,
  "client_id": "xndencrnvcr",
  "tenant_id": "356dnsdn",
  "is_metrics_enabled": true,
  "created_at": "timestamp",
  "updated_at": "timestamp"
  "status" :[{                                           
    "status": "healthy",
    "status_at": "timestamp"
  }],
  "disable_assets_collection": [{              
    "AzureKeyVaultKey": true
  }]
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "name": "Production SP 1",
    "client_secret": "cbdefeb",
    "is_metrics_enabled":true,
    "modify_sp_for_partner_customer": <client_api_id>
    "disable_assets_collection"             
    [{
      "AzureKeyVaultKey" : true,
      "AzureKeyVaultSecret":false
    }]
  }'
    'https://chapi.cloudhealthtech.com/v1/azure_service_principals/<sp_id>'

Get All Existing Service Principals

Retrieve a list of all service principals.

https://chapi.cloudhealthtech.com/v1/azure_service_principals

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
    'https://chapi.cloudhealthtech.com/v1/azure_service_principals/'

Details of Service Principal

Get details for a specific service principal.

https://chapi.cloudhealthtech.com/v1/azure_service_principals/:sp_id

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
    'https://chapi.cloudhealthtech.com/v1/azure_service_principals/<sp_id>/'

Azure Partner

Introduction to Microsoft CSP Partner API

An introduction to the Microsoft CSP Partner API.

Microsoft CSP partners and their customers are organized as tenants in a hierarchical, multi-tenant system in the Partner Platform. Customer tenants are subordinates of their corresponding Partner Tenant.

The Partner API allows partners to add their customer tenants to the Partner Platform.

How to Get Database Partner Customer ID

In order to use some of the Azure Partner endpoints, you need to provide the db_partner_customer_id. CloudHealth generates a unique ID for each partner customer.

You can get the Database Partner Customer ID for a partner customer from the CloudHealth Platform. From the left menu, go to Setup > Accounts > Azure Partner Customers and open the partner customer. The database ID of the partner customer appears in the browser URL. Here’s an example URL:

https://apps.cloudhealthtech.com/azure_partner_customers/5XXXXXXXXXX25

Here, 5XXXXXXXXXX25 is the Database Partner Customer ID.

The Database Customer ID can also be retrieved using the Get Single Partner Customer endpoint.

Create CSP Partner Customer

Add a Microsoft CSP partner customer tenant in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v2/customers

Parameters

  • namerequired

    String that specifies the unique display name of the customer’s Azure account.

  • azure_customer_id

    The Azure customer ID of the customer tenant. Use this parameter when the customer tenant has an address entered in the Azure Portal. If the customer tenant does not have an address entered in the Azure Portal, replace the azure_customer_id parameter with the address parameter.

  • address

    JSON field that specifies the customer’s mailing address. Use this parameter when the customer tenant does not have an address entered in the Azure Portal. If the customer tenant has an address entered in the Azure Portal, use the azure_customer_id instead.

    • street1required

      Line 1 of street address

    • street2

      Line 2 of street address. Can be blank.

    • cityrequired

      City specified as a string

    • staterequired

      State specified in abbreviated form. For example, specify Massachusetts as MA. For non-US countries, use the full, ASCII-transliterated state names. For example, for Australian state names, specify Australian Capital Territory, New South Wales, Northern Territory, and so on.

    • zipcoderequired

      Zipcode specified as a number

    • countryrequired

      Country specified a string

  • classification

    String that specifies the level of access the customer has in the CloudHealth Platform. Specify as managed_without_access (managed customer that does not directly access the CloudHealth Platform) or managed_with_access (managed customer that directly accesses the CloudHealth Platform). The default value is `managed_without_access’.

  • trial_expiration_date

    Date specified in ISO8601 format that indicates a date in the future when the customer’s trial expires. Beyond this date, users belonging to the customer are unable to access the CloudHealth Platform.

  • billing_contact

    String that specifies the email address of customer contact.

  • partner_billing_configuration

    Composite JSON field that specifies the configuration for the partner billing engine.

    • enabledrequired

      Boolean field that specifies whether partner billing is enabled. Default value is false.

    • folder

      String that specifies the prefix of the S3 folder that contains processed customer bills.

  • tags

    JSON array that specifies key-value pairs for tags to attach to the customer. Each customer can be assigned a maximum of 20 tags.

    • keyrequired

      Tag key

    • valuerequired

      Tag value

Response Code Description
201 OK Operation was successful
422 Unprocessable Entity Unprocessable entity
401 Unauthorized Unauthorized entry
422 Unprocessable Entry Input format errors
500 Internal Service Error Internal service error
{
 "name":"abc company",
 "azure_customer_id":"34fdg",
 "classification":"managed_with_access",
 "trial_expiration_date":"date",

 "billing_contact":"abc",
 "partner_billing_configuration":{
  "enabled":true,
  "folder":"",
 }
 "tags": [{
         "key": "customer_id", "value": "973532"
         },
        {
    "key": "service_package", "value": "basic_managed"
     }]
}
{
  "name": "Acme Corp",
  "classification": "managed_without_access",
  "billing_contact": "john.doe@acmecorp.com",
  "trial_expiration_date": "2016-09-22T00:00:00Z",
  "partner_billing_configuration": {
    "enabled": "true",
    "folder": ""
  },
  "address": {
    "street1": "1 Main St",
    "city": "Springfield",
    "state": "MA",
    "zipcode": "01234",
    "country": "US"
  },
  "tags": [{
    "key": "customer_id", "value": "973532"
  },
  {
    "key": "service_package", "value": "basic_managed"
  }]
}
{
  "id": 3947,
  "name": "Acme Corp",
  "classification": "managed_without_access",
  "billing_contact": "john.doe@acmecorp.com",
  "margin_percentage": 0.0,
  "created_at": "2016-09-15T18:17:04Z",
  "updated_at": "2016-09-15T18:17:04Z",
  "generated_external_id": "1a2b3c4d5e6f",
  "partner_billing_configuration": {
    "enabled": true,
    "folder": ""
  },
  "address": {
    "street1": "1 Main St",
    "city": "Springfield",
    "state": "MA",
    "zipcode": "01234",
    "country": "US"
  },
  "tags": [{
    "key": "customer_id", "value": "973532"
    },
    {
    "key": "service_package", "value": "basic_managed"
    }
  ],
"_links": {
  "self": {
  "href": "/v1/customers/3947"
  }
  }
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
     "name":"abc company",
     "azure_customer_id":"34fdg",
     "classification":"managed_with_access",
     "trial_expiration_date":"date",

     "billing_contact":"abc",
     "partner_billing_configuration":{
      "enabled":true,
      "folder":"",
     }
     "tags": [{
             "key": "customer_id", "value": "973532"
             },
            {
        "key": "service_package", "value": "basic_managed"
         }]
        }'
    'https://chapi.cloudhealthtech.com/v2/customers'

Get All Partner Customers

Retrieve a list of all customer tenants that you have created in the CloudHealth Platform. This information is retrieved from the CloudHealth Platform. This endpoint can be used for both AWS and Azure customer tenants.

https://chapi.cloudhealthtech.com/v2/customers

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v2/customers'

Get Single Partner Customer

Retrieve a specific customer tenant that you have created in the CloudHealth Platform. This information is retrieved from the CloudHealth Platform. This endpoint can be used for both AWS and Azure customer tenants.

https://chapi.cloudhealthtech.com/v2/customers/:client_api_id

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v2/customers/<client_api_id>'

Modify Existing Partner Customer

Modify a partner customer tenant that already exists in the CloudHealth Platform. This endpoint can be used for both AWS and Azure customer tenants.

https://chapi.cloudhealthtech.com/v2/customers/:client_api_id

{
  "name": "Acme Corporation",
  "classification": "managed_with_access"
}
{
  "id": XXXX,
  "name": "Acme Corporation",
  "classification": "managed_with_access",
  "billing_contact": "john.doe@acmecorp.com",
  "margin_percentage": 0.0,
  "created_at": "2016-09-15T13:10:47Z",
  "updated_at": "2016-09-15T16:46:34Z",
  "generated_external_id": "1a2b3c4d5e6f",
  "partner_billing_configuration": {
      "enabled": true,
      "folder": ""
  },
  "address": {
     "street1": "1 Main St",
     "street2": "",
     "city": "Springfield",
     "State": "MA",
     "zipcode": "01234",
     "Country": "US"
  },
  "_links": {
      "self": {
          "href": "/v1/customers/XXXX"
      }
  }
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
  "name": "Acme Corporation",
  "classification": "managed_with_access"
}'
'https://chapi.cloudhealthtech.com/v2/customers/<client_api_id>'

Get All CSP Partner Customers

Retrieve a list of all customer tenants. This information is retrieved from the Azure Portal.

https://chapi.cloudhealthtech.com/v1/azure_partner_customers

Response Code Description
200 OK Operation was successful
401 Unauthorized Unauthorized entry
500 Internal Service Error Internal service error
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/azure_partner_customers'

Get Single CSP Partner Customer

Retrieve a specific customer tenant. This information is retrieved from the Azure Portal.

https://chapi.cloudhealthtech.com/v1/azure_partner_customers/:db_partner_customer_id

Response Code Description
200 OK Operation was successful
401 Unauthorized Unauthorized entry
404 Not Found Entity not found
500 Internal Service Error Internal service error
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/azure_partner_customers/<db_partner_customer_id>'

Partner Azure Account Assignment

Introduction to Partner Azure Account Assignment API

An introduction to the Account Assignment API.

Use this API to administer Azure partner customer accounts that belong to CloudHealth Partners and to assign Azure partner customer accounts to Partner Customers for partner-generated billing purposes.

Create Azure Account Assignment

Assign Azure accounts to Partner Customers for partner-generated billing purposes.

/v1/azure_partner_customer_accounts/add/:client_api_id

Parameters

  • azure_customer_idsrequired

    An array of the customer IDs of the assigned Azure customer accounts.

If the corresponding Azure account does not exist in the customer’s CloudHealth account, it is created. If there is an error associated with one Azure account, none of the accounts in the request are assigned.

Response Code Description
207 OK Operation was successful but may contain error messages
401 Unauthorized Unauthorized entry
404 Not Found Bad endpoint
422 Unprocessable Entity Unprocessable entity
500 Internal Service Error General error
{
  "azure_customer_ids": ["ab123", "fgh345"]
}
"azure_partner_customer_accounts": [
  {
    "customer_tenant_name": "Azure Two",
    "azure_partner_customer_account": {
      "name": "Indigo Montoya Inc",
      "domain": "chazureteam.onmicrosoft.com",
      "azure_customer_id": "ab123"
      "created_at": "2018-12-27T17:36:36Z",
      "updated_at": "2019-04-26T20:49:59Z"
    }
  },
  {
    "http_status": 422
    "error": "azure_customer_id not found"
    "azure_customer_id": "fgh345"
  }]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  {
    "azure_customer_ids": ["ab123", "fgh345"]
  }
  'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/add/<client_api_id>'

Get All Azure Account Assignments

Retrieve a list of all Azure customer accounts assigned to a partner customer tenant.

/v1/azure_partner_customer_accounts/list

Response Code Description
200 OK Operation was successful
401 Unauthorized Unauthorized entry
500 Internal Service Error General error
"azure_partner_customer_accounts": [
  {                                                        
    "customer_tenant_name": "arriva"
    "azure_partner_customer_account": {
      "name":"abacus",
      "domain": "abacus.onmicrosoft.com",
      "azure_customer_id": "dfg234",
      "created_at": "2018-12-27T17:36:36Z",
      "updated_at": "2019-04-26T20:49:59Z"
    }
  },{
    "customer_tenant_name":"arriva",
    "azure_partner_customer_account":{
      "name":"card technologies",
      "domain":"card.onmicrosoft.com",
      "azure_customer_id":"xof194",
      "created_at": "2018-12-27T17:36:36Z",
      "updated_at": "2019-04-26T20:49:59Z"
    }
  },{
    "customer_tenant_name":"Acme Accounts Corp",
    "azure_partner_customer_account":{
      "name":"acme accounts 1",
      "domain":"acmeaccounts.onmicrosoft.com",
      "azure_customer_id":"rtq683",
      "created_at": "2019-01-25T12:33:31Z",
      "updated_at": "2019-05-01T15:32:11Z"
    }
  }]
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
  'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/list'

Get Single Azure Account Assignment

Retrieve information on a single Azure account assignment.

/v1/azure_partner_customer_accounts/list/:client_api_id

Response Code Description
200 OK Operation was successful
401 Unauthorized Unauthorized entry
500 Internal Service Error General error
"azure_partner_customer_accounts":[{
  "customer_tenant_name":"arriva",
  "azure_partner_customer_account":{
    "name":"abacus",
    "domain":"abacus.onmicrosoft.com",
    "azure_customer_id":"dfg234",
    "created_at": "2018-12-27T17:36:36Z",
    "updated_at": "2019-04-26T20:49:59Z"
  }
},{
  "customer_tenant_name":"arriva",
  "azure_partner_customer_account":{
    "name":"card technologies"
    "domain":"card.onmicrosoft.com",
    "azure_customer_id":"xof194",
    "created_at": "2018-12-27T17:36:36Z",
    "updated_at": "2019-04-26T20:49:59Z"
  }
}]
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
  'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/list/<client_api_id>'

Delete Azure Account Assignment

Remove the relationship between an Azure customer account and the partner customer that it was assigned to.

/v1/azure_partner_customer_accounts/remove/:client_api_id

Parameters

  • azure_customer_idsrequired

    An array of the customer IDs of the Azure customer accounts that should be removed from the partner customer tenant.

Response Code Description
207 OK Operation was successful
401 Unauthorized Unauthorized entry
404 Not Found Bad endpoint
422 Unprocessable Entity Unprocessable entity
500 Internal Service Error General error
{
  "azure_customer_ids": ["ab123", "fgh345"]
}
“azure_partner_customer_accounts”:[{
  "azure_partner_customer_account":{
    "name":"arriva",   
    "domain":"arriva.onmicrosoft.com",
    "azure_customer_id":"ab123",
    "created_at": "2018-12-27T17:36:36Z",
    "updated_at": "2019-04-26T20:49:59Z"
  },
  {"http_status": 422
    "error": "azure_customer_id not found"
    "azure_customer_id": "fgh345"
  }
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  {
    "azure_customer_ids": ["ab123", "fgh345"]
  }
  'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/remove/<client_api_id>'