Getting Started

Welcome

CloudHealth provides two APIs for programmatically interacting with the platform: a REST API and a GraphQL API. You are currently viewing the documentation for the REST API. To access the documentation for the GraphQL API, click here.

Welcome to the CloudHealth REST API Guide. Here you’ll find API services that programmatically retrieve data from the CloudHealth Platform. The CloudHealth REST 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.

• The Content-Type: application/json header is required when PUTting or POSTing JSON to the API, else an HTTP 422 Unprocessable Entity is issued

  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":[…]}
      }'
  

  All examples in the CloudHealth REST API documentation have been tested on the Git Bash shell terminal. To use the examples in the Windows Command prompt, replace the single quotes in the curl request with double quotes. For example: curl -H "Authorization: Bearer XXXXX98900000YYYY" -H "Accept: application/json" "https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly"

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.

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

• cost_and_usage_report

  JSON field that specifies the location of the AWS Cost and Usage Report (CUR).

  • bucketrequired

    Name of S3 bucket containing the CUR

  • path

    The path to the CUR report, including the prefix

• 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

• cloudwatch

  JSON field that specifies whether CloudHealth should collect CloudWatch data.

  • enabledrequired

    Boolean that specified whether CloudHealth collect AWS CloudWatch data. Default value is True

  • namespaces

    String that specifies the namespaces from which CloudWatch data should be gathered. Value can be CWAgent, System/Linux, System/Windows, or a comma-separated list of two or more of these values. Default value is an empty string.

  • runtime

    Number that specifies the frequency in hours at which CloudHealth should gather CloudWatch data. Default value is 1. Value can be 1 or 24.

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

• primary_aws_region

  String that specifies which region should be used to validate the read-only IAM policy. Value can be us-east-1 (default) or eu-central-1 for global AWS accounts. GovCloud customers cannot modify their default AWS region, us-gov-west-1.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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

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. Maximum value is 100.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

The results of this API call are paginated.

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

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.

• authentication

  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)

  • bucketrequired

    Name of S3 bucket containing the DBR

• cost_and_usage_report

  JSON field that specifies the location of the AWS Cost and Usage Report (CUR).

  • bucketrequired

    Name of S3 bucket containing the CUR

  • path

    The path to the CUR report, including the prefix

• 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

• cloudwatch

  JSON field that specifies whether CloudHealth should collect CloudWatch data.

  • enabledrequired

    Should CloudHealth collect AWS Config files? Default value is True

  • namespaces

    String that specifies the namespaces from which CloudWatch data should be gathered. Value can be CWAgent, System/Linux, System/Windows, or a comma-separated list of two or more of these values. Default value is an empty string.

  • runtime

    Number that specifies the frequency in hours at which CloudHealth should gather CloudWatch data. Default value is 1. Value can be 1 or 24.

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

• primary_aws_region

  String that specifies which region should be used to validate the read-only IAM policy. Value can be us-east-1 (default) or eu-central-1 for global AWS accounts. GovCloud customers cannot modify their default AWS region, us-gov-west-1.

Delete AWS Account

Delete an AWS Account from the CloudHealth Platform

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.

SSO Configuration

Configure SSO

Create or update SSO configuration in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/sso/configure

Parameters

• client_api_id

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

• sso_providerrequired

  String that specifies the unique display name of an AWS account. Specify samlp (SAML), google-apps (Google Apps), or waad (Azure AD).

• domainsrequired

  Array that specifies SSO domains, with each domain specified in company.com format.

• default_organization_id

  Number that specifies the ID of the default organization to which new users should be assigned.

• sign_in_endpointrequired

  String that specifies the SAML 2.0 Endpoint from your IdP.

• signing_certrequired

  String that specifies the contents of the X.509 certificate from your IdP.

• sso_ignore_idp_organizationrequired

  Boolean that specifies whether the IdP does not support passing the organization to which a new user should be assigned. Default value is false.

• azure_ad_roles_protocolrequired

  Boolean that specifies whether the Azure Roles protocol is used to pass roles to the CloudHealth Platform. Default value is true.

Retrieve SSO configuration

Retrieve an existing SSO configuration

https://chapi.cloudhealthtech.com/v1/sso/configure

Parameters

• client_api_id

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

Delete SSO configuration

Delete an existing SSO configuration

https://chapi.cloudhealthtech.com/v1/sso/unconfigure

Parameters

• client_api_id

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

Retrieve Pending SSO Domains

Retrieve SSO domains that are awaiting validation

https://chapi.cloudhealthtech.com/v1/sso/pending_domain_claims

Parameters

• client_api_id

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

Validate Pending SSO Domains

Validate SSO domains that are pending

https://chapi.cloudhealthtech.com/v1/sso/validate_pending_domain_claim

Parameters

• client_api_id

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

• pending_domain_namerequired

  String that specifies the domain to validate in company.com format.

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

Create Perspective Schema

Create a Perspective and associate it with a new schema. The ID of the new Perspective is returned in the message field in the POST response.

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

• client_api_id

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

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.

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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' -X PUT "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.

How to Remove a Static Group from a Perspective

To remove a static group from a perspective, remove the rules targeting that group from the schema.

In this example, the static group Group To Delete will be removed from the perspective, and Group to Keep will not be removed. The following example shows what the schema looks like before the group is removed from the perspective:

{
 "name": "RemoveStaticGroup",
 "rules": [
   {
     "type": "filter",
     "asset": "Group To Keep",
     "to": "123456789",
     "condition": {
       "clauses": [
         {
           "field": [
             "Active?"
           ],
           "op": "=",
           "val": "true"
         }
       ]
     }
   },
   {
     "type": "filter",
     "asset": "Group To Delete",
     "to": "2468101214",
     "condition": {
       "clauses": [
         {
           "field": [
             "Active?"
           ],
           "op": "=",
           "val": "false"
         }
       ]
     }
   }
 ],
 "merges": [

 ],
 "constants": [
   {
     "type": "Static Group",
     "list": [
       {
         "ref_id": "123456789",
         "name": "KeepMe"
       },
       {
         "ref_id": "2468101214",
         "name": "DeleteMe"
       },
       {
         "ref_id": "13579131517",
         "name": "Other",
         "is_other": "true"
       }
     ]
   }
 ],
 "include_in_reports": "false"
}

After the group is removed, the schema no longer lists the Group to Delete:

{
 "name": "AfterRemovingStaticGroup",
 "rules": [
   {
     "type": "filter",
     "asset": "Group To Keep",
     "to": "123456789",
     "condition": {
       "clauses": [
         {
           "field": [
             "Active?"
           ],
           "op": "=",
           "val": "true"
         }
       ]
     }
   },
 "merges": [

 ],
 "constants": [
   {
     "type": "Static Group",
     "list": [
       {
         "ref_id": "123456789",
         "name": "KeepMe"
       },
       {
         "ref_id": "13579131517",
         "name": "Other",
         "is_other": "true"
       }
     ]
   }
 ],
 "include_in_reports": "false"
}

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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"

Get Perspective Version

Include the version of a Perspective in the response.

Add Dynamic Group to Perspective

Add a dynamic group to an existing Perspective. You can exclude the ref_id field from the request. Alternately, if you include the ref_id field, specify an arbitrary numerical value for it.

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.

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.

Query Response Size Optimization

Multidimensional queries, by default, return a complete response across all the dimensions. Depending on the complexity of the report query, the result can return a much larger dataset. This dataset may include arrays containing only null values. To optimize the response to such queries, CloudHealth has introduced a new boolean parameter collapse_null_arrays. If specified in the query, arrays with all the cost values as null would collapse to a single null value, thus significantly reducing the query response size. Consider the following example to understand how this parameter works.

Following is the example of a 3-D query over time/accounts/services, with slicing on time and AWS service categories.

  curl -X GET -H 'Authorization: Bearer <Your API Key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/olap_reports/cost/history?\
    interval=monthly&\
    dimensions\[\]=AWS-Service-Category&\
    dimensions\[\]=time&\
    dimensions\[\]=AWS-Account&\
    measures\[\]=cost&\
    filters\[\]=time:select:-5,-1&\
    filters\[\]=AWS-Service-Category:select:ec2_compute,nat_gateway_transfer,ec2_transfer,ebs_storage,nat_gateway_usage,ebs_io&\
    NO_CACHE=1"

Note that the Data node in the query response may have multiple 2-D arrays with all cost values as null, leading to an unnecessary increase in the data size to 345 KB.

 "data": [
              [
                  [
                      [
                          2936970.8662986687
                      ],
                      [
                          2303183.584927046
                      ],
                      [
                          440173.0578069503
                      ],
                      [
                          26266.99529305149
                      ],
                      [
                          61661.31648144288
                      ],
                      [
                          77100.0010629067
                      ],
                      [
                          null
                      ],
                      [
                          19137.5030886411
                      ],
                      [
                          2039.3415658562
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          7409.0660727718
                      ]
                  ],
                  [
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ]
                  ],
                  
                  ...

              ]
          ]

Now, append the collapse_null_arrays parameter to the same query.

 curl -X GET -H 'Authorization: Bearer <Your API Key>' -H 'Content-Type: application/json'    "https://chapi.cloudhealthtech.com/olap_reports/cost/history?\
  interval=monthly&\
  dimensions\[\]=AWS-Service-Category&\
  dimensions\[\]=time&\
  dimensions\[\]=AWS-Account&\
  measures\[\]=cost&\
  filters\[\]=time:select:-5,-1&\
  filters\[\]=AWS-Service-Category:select:ec2_compute,nat_gateway_transfer,ec2_transfer,ebs_storage,nat_gateway_usage,ebs_io&\
  NO_CACHE=1&\
  collapse_null_arrays=1"

The query retrieves a simplified response as compared to the original query response by replacing the 2-D null arrays with a single null value.

  "data": [
              [
                  [
                      [
                          2936970.8662986687
                      ],
                      [
                          2303183.584927046
                      ],
                      [
                          440173.0578069503
                      ],
                      [
                          26266.99529305149
                      ],
                      [
                          61661.31648144288
                      ],
                      [
                          77100.0010629067
                      ],
                      [
                          null
                      ],
                      [
                          19137.5030886411
                      ],
                      [
                          2039.3415658562
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          null
                      ],
                      [
                          7409.0660727718
                      ]
                  ],
                  null,
                  
                  ...

              ]
          ]

After adding the collapse_null_arrays parameter, the resultant response size is 43 KB, much less than the original query response. The parameter only makes changes in the response format and returns the data that is useful to you.

NOTE:

• To process the new result set, you need to add a simple nil check to the logic.
• Since the response to 3D and 4D queries can be very large, verifying a small data set by appending the collapse_null_arrays parameter is recommended before submitting the larger requests.

List of Queryable Reports

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

https://chapi.cloudhealthtech.com/olap_reports

Parameters

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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

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

Parameters

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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'

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.

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

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

Parameters

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

Get Query for a Report

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

Parameters

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

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-Availability-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. You can add up to 4 dimensions.

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

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

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

Parameters

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

Attributes of Single Asset

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

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

Parameters

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

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, AzurePolicyAssignment, or AzurePolicyStates.

• queryrequired

  Criteria for finding assets of a particular asset object type. Enclose query parameter values in single quotes. This also applies to boolean assignment values that are either True or False. Format is 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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

• api_version

  Integer that specifies the API version to use. Possible values are 1 (default) and 2. Version 1 queries only return assets that 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.

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

Include only instance as related object when searching for AWS Volumes

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

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/metrics/v1

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.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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.

Upload Metrics for Single Asset

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

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

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

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

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>
    }
  ]
}

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

• JSON documentrequired

  Payload containing the tags that you want to post. See How Tags are Processed.

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.

Organization

Introduction to Organization API

An introduction to the Organization API.

Organizations allow customers to limit the visibility of the data available to users in the CloudHealth Console. Using organizations, you can grant multiple stakeholders access to CloudHealth without providing them access to data you do not wish them to see (e.g. the marketing department should see only the infrastructure running on behalf of marketing).

To create an organization, you associate it with one or more accounts containing the data you want visible. Classic organizations may have overlapping data (e.g. both your Engineering and DevOps organizations might have access to a common set of accounts). FlexOrg organizations can be associated only with accounts belonging to their parent organizations.

By default, every company has one default organization that contains all accounts and their corresponding assets. You can modify and assign accounts to the default organization only through the CloudHealth Platform.

For more information on organizations, see the Organizations, Users, and Roles topic.

The Organization API allows admin users to create, modify, and delete organizations and assign AWS, Azure, GCP, and Data Center accounts to organizations. Users can assign Chef and Datadog accounts to an organization only through the CloudHealth Platform. In order to use some Organization endpoints, you need to provide the org_id. CloudHealth generates a unique ID for each organization. See How to Get Organization ID.

Organization API is available in two versions. Version 2 is documented in the endpoints below. To access documentation for Version 1 (Legacy) API, contact support@cloudhealthtech.com.

How to Get Organization ID

In order to use some Organization endpoints, you need to provide the org_id. CloudHealth generates a unique ID for each organization. You can get the Organization ID for an organization from the CloudHealth Platform. From the left menu, go to Setup > Admin > Organizations and view or edit the organization. The Organization ID appears in the browser URL. Here’s an example URL:

https://apps.cloudhealthtech.com/organizations/20XXXXXXXX09

Here, 20XXXXXXXX09 is the Organization ID.

The Organization ID can also be retrieved using the Get All Organizations endpoint.

Rate Limits

Understand rate limits when making requests to the Organization API.

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

• A total of 500 requests are allowed every ten minutes for the following endpoints:
  • Create Organization
  • Assign Account to Organization
  • Replace Existing Organization Account Assignment

Create Organization

Add a new organization to the CloudHealth Platform.

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

Parameters

• namerequired

  String that specifies the unique name of the new organization.

• description

  String that specifies a description of the organization.

• parent_organization_id

  String that specifies the ID of the parent organization. Applies only for organizations in FlexOrgs.

Get All Organizations

Retrieve a list of all organizations, including the number of accounts assigned to them.

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

Parameters

• per_page

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

• page

  Specify the page number for results.

• org_id

  String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.

Modify Existing Organization

Modify an existing organization that already exists in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id

Parameters

• name

  String that specifies the unique name of the organization.

• description

  String that specifies a description of the organization.

Delete Existing Organization

Delete an organization from the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id

Assign Account to Organization

Assign accounts to an organization. If your organization is in FlexOrgs, run the Get All Allowed Accounts endpoint first to verify which accounts you can assign to the organization. Existing account assignments in the organization will be entirely replaced by the assignments you specify in the body of this request. If you want to add to existing account assignments, see Add Accounts to Existing Organization Account Assignment.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id

Parameters

• aws_accounts

  Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be assigned to the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 AWS accounts per endpoint.

• azure_subscriptions

  Enter a comma-separated list of Azure subscription GUIDs that should be assigned to the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 Azure accounts per endpoint.

• gcp_compute_projects

  Enter a comma-separated list of GCP project IDs that should be assigned to the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 GCP projects per endpoint.

• data_center_accounts

  Enter a comma-separated list of Data Center account names that should be assigned to the organization. The account names can be retrieved using the Search for Assets endpoint. You can assign up to 500 Data Center accounts per endpoint.

Add Accounts to Existing Organization Account Assignment

Add one of more accounts to an organization.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id/accounts

Parameters

• accountsrequired

  Enter add to append accounts to the organization.

• aws_accounts

  Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be assigned to the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 AWS accounts per endpoint.

• azure_subscriptions

  Enter a comma-separated list of Azure subscription GUIDs that should be assigned to the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 Azure accounts per endpoint.

• gcp_compute_projects

  Enter a comma-separated list of GCP project IDs that should be assigned to the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 GCP projects per endpoint.

• data_center_accounts

  Enter a comma-separated list of Data Center account names that should be assigned to the organization. The account names can be retrieved using the Search for Assets endpoint. You can assign up to 500 Data Center accounts per endpoint.

Get Organization Account Assignment

Retrieve a list of all accounts assigned to an organization.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id/:cloud_account

Parameters

• cloud_accountrequired

  Specify the cloud account as aws_accounts for AWS, azure_subscriptions for Azure, gcp_compute_projects for GCP, data_center_accounts for Data Center, or vmware_csp_organizations for VMware Cloud.

• page

  Specify the page number for results.

• per_page

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

• query

  Specify a keyword to filter accounts by. For example, specify Production to filter accounts by field and tag for the keyword Production.

• sort

  Specify an attribute to sort accounts by. For example, specify amazon_name to sort accounts by the Amazon Name attribute.

• is_down

  Boolean field that specifies whether accounts should be sorted in ascending or descending order. Specify true to sort accounts in descending order and false to sort accounts in ascending order. Default value is false.

Get All Allowed Accounts

Used in FlexOrgs only. Retrieves a list of accounts that belong to an organization and can be assigned to potential child organizations. Make a GET request to the parent organization of the organization you want to add accounts to.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id/available_accounts

Parameters

• typerequired

  Specify the cloud account type as aws_accounts for AWS, azure_subscriptions for Azure, gcp_compute_projects for GCP, data_center_accounts for Data Center, or vmware_csp_organizations for VMware Cloud.

Replace Existing Organization Account Assignment

Replace an organization’s current account assignments with a new list of accounts. This endpoint removes all accounts currently assigned to the organization and replaces them with the new accounts.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id/accounts

Parameters

• aws_accounts

  Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be assigned to the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 AWS accounts per endpoint.

• azure_subscriptions

  Enter a comma-separated list of Azure subscription GUIDs that should be assigned to the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 Azure accounts per endpoint.

• gcp_compute_projects

  Enter a comma-separated list of GCP project IDs that should be assigned to the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 GCP projects per endpoint.

• data_center_accounts

  Enter a comma-separated list of Data Center account names that should be assigned to the organization. The account names can be retrieved using the Search for Assets endpoint. You can assign up to 500 Data Center accounts per endpoint.

Delete Existing Organization Account Assignment

Remove one of more accounts from an organization.

https://chapi.cloudhealthtech.com/v2/organizations/:org_id/accounts

Parameters

• accountsrequired

  Enter remove to remove accounts assigned to the organization.

• aws_accounts

  Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be removed from the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can remove up to 500 AWS accounts per endpoint.

• azure_subscriptions

  Enter a comma-separated list of Azure subscription GUIDs that should be removed from the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can remove up to 500 Azure accounts per endpoint.

• gcp_compute_projects

  Enter a comma-separated list of GCP project IDs that should be removed from the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can remove up to 500 GCP projects per endpoint.

• data_center_accounts

  Enter a comma-separated list of Data Center account names that should be removed from the organization. The account names can be retrieved using the Search for Assets endpoint. You can remove up to 500 Data Center accounts per endpoint.

Policies

Introduction to Policy API

An introduction to the Policy API.

The Policy API allows you to retrieve policy information and results. The API supports the following operations:

• Retrieve policy, policy block, and policy violation data for your policies in the CloudHealth Platform.
• For Partners, retrieve policy, policy block, and policy violation data for your partner customers’ policies in the CloudHealth Platform. Limited to policies in the partner customer’s default organization.

Get All Policies

Retrieve a list of all policies in your organization or in the specified partner customer’s default organization.

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

Parameters

• api_key

  String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.

• per_page

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

• page

  Specify the page number for results.

Get All Policy Blocks

Retrieve a list of all policy blocks for a policy.

https://chapi.cloudhealthtech.com/v1/policies/:policy_id/policy_blocks

Parameters

• policy_idrequired

  The policy ID of the policy. The policy ID can be retrieved using the Get All Policies endpoint.

• api_key

  String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.

• per_page

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

• page

  Specify the page number for results.

Get All Policy Violations

Retrieve a list of all policy violations generated by a policy block.

https://chapi.cloudhealthtech.com/v1/policies/:policy_id/policy_blocks/:policy_block_id/violations

Parameters

• policy_idrequired

  The policy ID of the policy. The policy ID can be retrieved using the Get All Policies endpoint.

• policy_block_idrequired

  The policy block ID of the policy block. The Policy block ID can be retrieved using the Get All Policy Blocks endpoint.

• api_key

  String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.

• per_page

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

• page

  Specify the page number for results.

• count

  Specify the number of violations to return. Default value is 1.

Get Single Policy Violation

Retrieve a single policy violation and a list of all assets and resources affected by the violation.

https://chapi.cloudhealthtech.com/v1/policies/:policy_id/policy_blocks/:policy_block_id/violations/:violation_id?api_key=:api access key&client_api_id=:client api Id&page=:page_number&per_page=:count_per_page

Parameters

• api_keyrequired

  String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.

• policy_idrequired

  The policy ID of the policy. The policy ID can be retrieved using the Get All Policies endpoint.

• policy_block_idrequired

  The policy block ID of the policy block. The policy block ID can be retrieved using the Get All Policy Blocks endpoint.

• violation_idrequired

  The violation ID of the policy violation. The policy violation ID can be retrieved using the Get All Policy Violations

• page

  Specify the page number for results.

• per_page

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

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

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 using the Get All Customers endpoint. 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.

How to Use the Client API ID with Customer API

The Client API ID is an ID assigned to each partner customer. As a partner, you can use your partner customer’s Client API ID with customer API endpoints to add, remove and view information about your partner customer.

For example, you can use a partner customer’s Client API ID to get a list of queryable reports belonging to that partner customer with the List of Queryable Reports endpoint.

To get a partner customer’s Client API ID, see the How to Get Client API ID topic.

The Client API ID is added to the end of a customer API endpoint. For example:

https://chapi.cloudhealthtech.com/v1/perspective_schemas?client_api_id=<client_api_id>

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.

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.

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