CloudHealth API Guide logo

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"

This area displays code examples that you can copy and paste into a terminal. Before running these examples, make sure you replace placeholder values enclosed within angle brackets <> with actual values.
For example, all API queries must include your unique API Key in the authorization header. The value of this key is indicated as <your_api_key> in these code examples. Replace this placeholder value with your actual API Key.

Getting Your API Key

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

How CloudHealth Validates API Requests

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

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

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

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

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

Periodic Key Rotation

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

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

Error Codes

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

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

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

All errors return JSON in the following format:

{
  "error": "error message here"
}

AWS Accounts in CloudHealth

Enable AWS Account

Enable an AWS Account in the CloudHealth Platform.

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

Parameters

  • namerequired

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

  • authenticationrequired

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

    • protocolrequired

      Authentication protocol. Specify access_key or assume_role

    • access_keyrequired

      Access Key for IAM User

    • secret_keyrequired

      Access Key for IAM User

    • assume_role_arnrequired

      Role ARN for IAM Role

    • assume_role_external_idrequired

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

  • billing

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

    • bucketrequired

      Name of S3 bucket containing the DBR

  • 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

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

AWS Accounts in CloudHealth

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

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

Parameters

  • page

    Specify the page number for results

  • per_page

    Specify how many results should be displayed per page. Default value is 30. 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.

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

Single AWS Account

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

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

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

Update Existing AWS Account

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

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

Parameters

  • namerequired

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

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

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

Delete AWS Account

Delete an AWS Account from the CloudHealth Platform

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

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

Get External ID

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

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

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

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

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

You can also get your API key through an endpoint.

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

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 ah-saml (AuthHub SAML), or ah-waad (AuthHub Azure AD).

  • issuerrequired

    String that specifies the SAML Issuer or Entity ID.

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

curl -X PUT -H 'Authorization: Bearer API_KEY' -H 'Content-Type: application/json' -d '{"sso_provider": <"ah-samlp"|"ah-waad">, "domains": ["<domain-1>,...,<domain-N>"], "signing_cert": "<cert>", "sign_in_endpoint": "<sign_in_endpoint>", "issuer": "<issuer>", "sso_ignore_idp_organization": <true|false>}' 'https://chapi.cloudhealthtech.com/v1/sso/configure'
{"identityProviderId":"<idp-guid>","verifyCertAlias":"cloudhealth-<id>","samlMDidpRedirectBindingURL":"<sign_in_endpoint>","issuer":"<issuer>","cert":"<cert>","message":"SSO configured for <customer>"}

Retrieve SSO configuration

Retrieve an existing SSO configuration

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

Parameters

  • client_api_id

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

curl -X GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/sso/configuration'
{"configuration":{"sso_provider":"google-apps", "claimed_domains":["cloudhealthtech.com"], "pending_domains":[], "connection_name":"cloudhealthtech-com", "default_organization":"CloudHealth Technologies"} }

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.

curl -X DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/sso/unconfigure'
{"success":"SSO unconfigured for CloudHealth Technologies"}

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.

curl -X GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/sso/pending_domain_claims'
{"pending_sso_domains": [{"domain":"cloudhealthtech.com", "token":"xxxxx-xxxxx-xxxxx", "created_at":"2019-07-10T18:45:47Z", "created_by_id":11937}]}

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.

curl -X PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d '{"pending_domain_name":"cloudhealthtech.com"}' 'https://chapi.cloudhealthtech.com/v1/sso/validate_pending_domain_claim'
{"valid":"true" }

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.

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

Retrieve Perspective Schema

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

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

Parameters

  • include_version

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

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

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

Create Perspective Schema

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

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

Update Perspective Schema

Modify a Perspective based on rules posted through a schema.

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

Parameters

  • check_version

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

  • include_version

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

  • 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"
}
curl -s -H 'Content-Type: application/json' -X PUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
  ?api_key=<api_key>" -d '{"schema":<schema JSON>}'

Delete Perspective Schema

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

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

Parameters

  • force

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

  • hard_delete

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

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

Get Perspective Version

Include the version of a Perspective in the response.

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

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.

curl -s -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -X PUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>" -d '{"schema":{"name": "<perspective_name>","rules": [{"type": "categorize","asset": "AwsS3Bucket","field": ["Active?"],"name": "Dynamic_group_name"}]}}''

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.

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

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

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

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

List Reports of Specific Type

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

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

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'

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

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

Data for Standard Report

Retrieve the data for a specific Standard report.

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

Parameters

  • dimensions

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

  • measures

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

  • interval

    String that specifies the granularity of report data.

  • filters

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

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

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

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

    This query returns the following response.

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

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

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

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

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

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

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

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

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

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

Data for Custom Report

Retrieve the data for a custom Standard report.

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

Parameters

  • dimensions

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

  • measures

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

  • interval

    String that specifies the granularity of report data.

  • filters

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

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

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

Report Dimensions and Measures

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

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

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.

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

Get Query for a Report

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

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.

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

Add Dimensions and Measures to Report Query

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

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

    This query returns a response that looks like this.

    {
    "dimensions": [
       {
           "label": "Owner Perspective",
           "name": "Groupset-998"
           "members": [...],
       },
       {
           "label": "Function Perspective",
           "name": "Groupset-999"
           "members": [...],
      },
      {
           "label": "Availability Zones",
           "name": "AWS-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.

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

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

Attributes of Single Asset

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

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

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.

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

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

Search for Assets

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

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

Parameters

  • namerequired

    String that specifies the type asset object to query, for example, AWSInstance, 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.

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

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

Asset Query Examples

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

List API names for all asset types

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

List available fields for AWS RDS Instances

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

List available fields for Azure Virtual Machines

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

List available fields for AWS Load Balancer

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

Filter AWS Load Balancers by name

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

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

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

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

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

Metrics

Introduction to Metrics API

An introduction to the Metrics API and its limitations.

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

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

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

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

Limitations

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

Rate Limits

Understand rate limits when making requests to the Metrics API.

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

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

Understand Format of Metrics Payload

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

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

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

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

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

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

Here’s an example of the payload.

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

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

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

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

Field: assetType

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

Field: granularity Supported Values: hour

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

Each entry array consists of these components.

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

An entry for instance might look like this.

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

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

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

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

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

Metrics for Single Asset

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

https://chapi.cloudhealthtech.com/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.

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

Upload Metrics for Single Asset

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

https://chapi.cloudhealthtech.com/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>
    }
  ]
}
Response code Meaning
200 Success / Partial failure
400 No data was processed. Possibly malformed JSON document.
429 Request was throttled
500 Error with CloudHealth servers. Do not resend request immediately.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/metrics/v1" -d '{"metrics":{"datasets":[{"metadata":{"assetType":"aws:ec2:instance","granularity":"hour","keys":["assetId","timestamp","memory:usedPercent.avg","memory:usedPercent.max","memory:usedPercent.min"]},"values":[["us-east-1:12345678:i-99999999","2015-06-03T01:00:00+00:00",100.0,200.0,50.0],["us-east-1:12345678:i-88888888","2015-06-03T02:00:00+00:00",25.5,45.2,15.0]]}]}}'
{
  succeeded: 198,
  failed:    2,
  errors:    0,
  datasets:  [
    {
      "succeeeded": 100,
      "errors": [],
      "failures": []
    },
    {
      "succeeeded": 98,
      "errors": [],
      "failures": [
      {
        "error": "Number of values (6) must equal number of keys (5).",
        "row": [
          "us-east-1:12345678:i-99999999",
          "2015-06-03T02:00:00+00:00",
          100,
          75,
          50,
          111
        ]
      },
      {
        "error": "Percentage value (101) is greater than 100.",
        "row": [
          "us-east-1:12345678:i-88888888",
          "2015-06-03T03:00:00+00:00",
          101,
          75,
          50
        ]
      },
    ]
  },
  ]
}

Tagging

Introduction to Tagging API

An introduction to the Tagging API and its limitations.

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

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

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

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

Limitations

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

How Tags are Processed

Understand the process through which CloudHealth updates tags.

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

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

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

Update Tags for Single Asset

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

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

Parameters

The response to the post request is JSON.

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

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.

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.

{
  "name": "abc",
  "description": "abc desc",
  "parent_organization_id": "24"
}
{
  "id":"6116033432624",
  "parent_organization_id": "24",
  "name": "abc",
  "description": "abc desc",
  "idp_name": "abc",
  "flex_org": false,
  "default_organization": true,
  "assigned_users_count": 124,
  "num_aws_accounts": 118,
  "num_azure_subscriptions": 25,
  "num_gcp_compute_projects": 15,
  "num_data_center_accounts": 84,
  "num_vmware_csp_organizations": 1
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "name": "abc",
    "description": "abc desc",
    "parent_organization_id": "24"
  }'    
    'https://chapi.cloudhealthtech.com/v2/organizations'

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.

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

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.

{
  "description": "abc 123"
}
{
  "id":"6116033432624",
  "name": "abc",
  "description": "abc 123",
  "idp_name": "abc",
  "flex_org": false,
  "default_organization": true,
  "assigned_users_count": 124,
  "num_aws_accounts": 118,
  "num_azure_subscriptions": 25,
  "num_gcp_compute_projects": 15,
  "num_data_center_accounts": 84,
  "num_vmware_csp_organizations": 1
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "description": "abc 123"
  }'
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>'

Delete Existing Organization

Delete an organization from the CloudHealth Platform.

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

curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
    '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.

{
  "aws_accounts":["12345","67890"],
  "azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
  "gcp_compute_projects":["gcp-project-name","gcp-new-project"],
  "data_center_accounts":["myplace-datacenter"]
}
[{
  "id":"6116033432624",
  "name": "abc",
  "description": "abc 123",
  "idp_name": "abc",
  "flex_org": false,
  "default_organization": true,
  "assigned_users_count": 124,
  "num_aws_accounts": 118,
  "num_azure_subscriptions": 25,
  "num_gcp_compute_projects": 15,
  "num_data_center_accounts": 84,
  "num_vmware_csp_organizations": 1
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "accounts":"add",
    "aws_accounts":["12345","67890"],
    "azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
    "gcp_compute_projects":["gcp-project-name","gcp-new-project"],
    "data_center_accounts":["myplace-datacenter"]
  }'    
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>'

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.

{
  "accounts":"add",
  "aws_accounts":["12345","67890"],
  "azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
  "gcp_compute_projects":["gcp-project-name","gcp-new-project"],
  "data_center_accounts":["myplace-datacenter"]
}
[{
  "id":"6116033432624",
  "name": "abc",
  "description": "abc 123",
  "idp_name": "abc",
  "flex_org": false,
  "default_organization": true,
  "assigned_users_count": 124,
  "num_aws_accounts": 118,
  "num_azure_subscriptions": 25,
  "num_gcp_compute_projects": 15,
  "num_data_center_accounts": 84,
  "num_vmware_csp_organizations": 1
}]
curl --request PATCH -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "accounts":"add",
    "aws_accounts":["12345","67890"],
    "azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
    "gcp_compute_projects":["gcp-project-name","gcp-new-project"],
    "data_center_accounts":["myplace-datacenter"]
  }'    
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/accounts'

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.

{
"accounts": [
  {
    "name": "Example Subscription",
    "region": "global",
    "created_at": "2017-10-19T17:36:10Z",
    "updated_at": "2019-04-03T04:49:49Z",
    "account_type": "Unknown",
    "status": "Critical",
    "authentication_type": "Role Based",
    "tags": []
  },
  {
    "name": "Production Account",
    "region": "global",
    "created_at": "2018-05-02T05:51:20Z",
    "updated_at": "2018-05-04T16:36:55Z",
    "account_type": "Unknown",
    "status": "Critical",
    "authentication_type": "User Based",
    "tags": [
      {
        "key": "Environment",
        "value": "Production"
      }
    ]
  }
],
"_links": {
    "next": {
      "href": "/v2/organizations/:org_id/aws_accounts?page=2&per_page=30"
    }
  }
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d  
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/<cloud_account>'

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.

{
  "aws_accounts": [
    {
      "id": "656265534892",
      "name": "CloudHealth NG Dev",
      "owner_id": "foo",
      "account_type": "standalone",
      "authentication_type": "role",
      "status": "healthy",
      "tags": { "foo": "bar", "baz": "bang" }
    }
  ]
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d  
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/available_accounts?type=aws_accounts'

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.

{
  "aws_accounts":["12345","67890"],
  "azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
  "gcp_compute_projects":["gcp-project-name","gcp-new-project"],
  "data_center_accounts":["myplace-datacenter"]
}
[{
  "id":"6116033432624",
  "name": "abc",
  "description": "abc 123",
  "idp_name": "abc",
  "flex_org": false,
  "default_organization": true,
  "assigned_users_count": 124,
  "num_aws_accounts": 118,
  "num_azure_subscriptions": 25,
  "num_gcp_compute_projects": 15,
  "num_data_center_accounts": 84,
  "num_vmware_csp_organizations": 1
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "aws_accounts":["12345","67890"],
    "azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
    "gcp_compute_projects":["gcp-project-name","gcp-new-project"],
    "data_center_accounts":["myplace-datacenter"]
  }'    
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/accounts>'

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.

{
  "accounts":"remove",
  "aws_accounts":["12345"],
  "azure_subscriptions":["151f9055-7a93-4bbb"],
  "gcp_compute_projects":["gcp-project-name"],
  "data_center_accounts":["myplace-datacenter"]
}
{
  "id":"6116033432624",
  "name": "abc",
  "description": "abc 123",
  "idp_name": "abc",
  "flex_org": false,
  "default_organization": true,
  "assigned_users_count": 124,
  "num_aws_accounts": 118,
  "num_azure_subscriptions": 25,
  "num_gcp_compute_projects": 15,
  "num_data_center_accounts": 84,
  "num_vmware_csp_organizations": 1
}
curl --request PATCH -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "accounts":"remove",
    "aws_accounts":["12345"],
    "azure_subscriptions":["151f9055-7a93-4bbb"],
    "gcp_compute_projects":["gcp-project-name"],
    "data_center_accounts":["myplace-datacenter"]
  }'    
    'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/accounts'

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.

Response Code Description
403 Forbidden Missing API Key
Unable to find Client ID from Partner Customers
User does not have role permission to use this endpoint
422 Unprocessable Entity Exceeded maximum 30 per page
Page parameters must be greater than zero
{
  "policies": [
    {  
      "id": 152,
      "name": "Missing cht_owner Tag",
      "description": "A block for each asset type",
      "user_defined": true,
      "creator": "John Doe",
      "creator_email": "jdoe@cloudhealthtech.com",
      "last_editor": "John Doe",
      "last_editor_email": "jdoe@cloudhealthtech.com",
      "enabled": true,
      "last_evaluation": "2019-05-23 20:19:42 UTC",
      "created_at": "2017-08-02 17:39:56 UTC",
    },
    {
      "id": 151,
      "name": "CIS AWS Foundations",
      "description": "Center for Internet Security (CIS) security benchmark providing best practices securing AWS environments. This policy can be used to validate your adherence to important security recommendations.",
      "user_defined": true,
      "creator": null,
      "creator_email": null,
      "last_editor": null,
      "last_editor_email": null,
      "enabled":true,
      "last_evaluation": "2019-05-23 20:19:42 UTC",
      "created_at": "2016-11-28 03:57:14 UTC"
    }
],
"_links" : {
    "next" : {
        "href": "cloudhealthtech.com/v1/policies?api_key=4760&per_page=20&page=3"
    },
    "prev" : {
        "href": "cloudhealthtech.com/v1/policies?api_key=4760&per_page=20&page=1"
    }
  }
}
curl --request GET \
  'https://chapi.cloudhealthtech.com/v1/policies?api_key=<client_api_id>&per_page=<max_page_count>&page=<page_number>' \
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'

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.

Response Code Description
403 Forbidden Missing API Key
Unable to find Client ID from Partner Customers
User does not have role permission to use this endpoint
404 Not Found Policy ID not found
Policy ID corresponds to a rightsizing policy. Policy API cannot retrieve policy blocks for a rightsizing policy.
422 Unprocessable Entity Exceeded maximum 30 per page
Page parameters must be greater than zero
{
  "policy_blocks":[
    { "id": 1511828492778, "name": "Block 1", "last_evaluated": "2019-05-28 11:11:23 UTC"},
    { "id": 1511828492779, "name": "Block 2", "last_evaluated": "2019-05-28 11:11:23 UTC"},
    { "id": 1511828492780, "name": "Block 3", "last_evaluated": "2019-05-28 11:11:23 UTC"},
    { "id": 1511828492781, "name": "Block 4", "last_evaluated": "2019-05-28 11:11:23 UTC"},
    { "id": 1511828492782, "name": "Block 5", "last_evaluated": "2019-05-28 11:11:23 UTC"}
  ],
  "_links": {}
}
curl --request GET \
  'https://chapi.cloudhealthtech.com/v1/policies/<policy_id>/policy_blocks?api_key=<client_api_id>&per_page=<max_page_count>&page=<page_number>' \
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'

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.

Response Code Description
403 Forbidden Missing API Key
Unable to find Client ID from Partner Customers
User does not have role permission to use this endpoint
404 Not Found Policy block ID not found
422 Unprocessable Entity Exceeded maximum 30 per page
Page parameters must be greater than zero
Past violation count parameter must be greater than zero
Exceeded maximum 100000 past violations
{
  "id": "6116033458540",
  "resource_type": "aws_ec2_instance",
  "policy_violations": [
    {
      "alerts": [
        {
          "alert_id": 6116034999228,
          "evaluation_time": "2019-07-29T20:55:50Z",
          "description": "541 M5 instances are large size or larger ",
          "severity": "Critical",
          "affected_resources": 541,
          "uniq_key": ""
        }
      ]
    },
    {
      "alerts": [
        {
          "alert_id": 6116034999178,
          "evaluation_time": "2019-07-24T17:14:04Z",
          "description": "541 M5 instances are large size or larger ",
          "severity": "Critical",
          "affected_resources": 541,
          "uniq_key": ""
        }
      ]
    },
  ],
  "_links": {
    "next": {
      "href": "/v1/policies/6116033430880/policy_blocks/6116033458540/violations?count=4&page=2&per_page=2"
    }
  }
}
curl --request GET \
  'https://chapi.cloudhealthtech.com/v1/policies/<policy_id>/policy_blocks/<policy_block_id>/violations?api_key=<client_api_id>&count=5' \
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'

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.

Response Code Description
403 Forbidden Missing API Key
Unable to find Client ID from Partner Customers
User does not have role permission to use this endpoint
404 Not Found Violation ID or alert ID not found
{
   "resource_type": "aws_s3_bucket",
   "comments": ["TestTestTest"]
   "affected_resources" : [
     {
       "id": 1,
       "New": false,
       "model_type": "S3 Bucket",
       "Name": "cloudhealth-detailed-bills",
       "Storage in GB": "1,142,023.68",
       "Account Name": "CloudHealth",
       "List Price in Month": "$34,260.71",
       "Access": "Not public *",
     },
     {
       "id": 2,
       "New": false,
       "model_type": "S3 Bucket",
       "Name": "cloudhealth-detailed-bills-dev",
       "Storage in GB": "604.35",
       "Account Name": "CloudHealth",
       "List Price in Month": "$18.13",
       "Access": "Not public *",
     },
     ...
   ],
   "_links": {
       "next": {
           "href": "policy_violation/5841156436453?api_key=4760&page=2&per_page=33"
       }
   }
 }
curl --request GET \
  'https://chapi.cloudhealthtech.com/v1/policies/<policy_id>/policy_blocks/<policy_block_id>/violations/<violation_id>?api_key=<client_api_id>&page=<page_number>&per_page=<count_per_page>' \
  -H 'Authorization: Bearer <your_api_key>'
  -H 'Content-Type: application/json'

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.

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

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

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

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

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

Assets for Specific Customer

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

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

Parameters

  • client_api_idrequired

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

  • namerequired

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

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

Create Partner Customer

Add a partner customer tenant in the CloudHealth Platform.

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

Parameters

  • namerequired

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

  • addressrequired

    JSON field that specifies the customer’s mailing address.

    • street1required

      Line 1 of street address

    • street2required

      Line 2 of street address. Can be blank.

    • cityrequired

      City specified as a string

    • staterequired

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

    • zipcoderequired

      Zipcode specified as a number

    • countryrequired

      Country specified a string

  • classification

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

  • trial_expiration

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

  • billing_contact

    String that specifies the email address of customer contact.

  • partner_billing_configuration

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

    • enabledrequired

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

    • folder

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

  • tags

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

    • keyrequired

      Tag key

    • valuerequired

      Tag value

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

Modify Existing Customer

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

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

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

Delete Existing Customer

Delete a partner customer tenant from the CloudHealth Platform.

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

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

Get Single Customer

Retrieve a specific customer tenant.

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

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

Get All Customers

Retrieve a list of all customer tenants.

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

Parameters

  • per_page

    Integer that specifies the number of assets to return per page.

  • page

    Integer that specifies the page to display when results run over multiple pages.

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

Statement for Single Customer

Retrieve the billing statement for a specific partner customer.

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

Parameters

  • client_api_idrequired

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

  • status

    String that specifies the status of the statement. Valid values are Final or Estimated.

  • billing_period

    String that specifies the billing_period of the statement. The date is specified in the format YYYY-MM.

  • per_page

    Integer that specifies the number of assets to return per page.

  • page

    Integer that specifies the page to display when results run over multiple pages.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customer_statements/?client_api_id=<client_api_id>&page=1&status=Final&billing_period=2020-12&per_page=2'
{
  customer_id : 1211,
  cloud: "AWS",
  billing_period : "2020-12",
  total_amount : 211,523.09,
  status : "Final",
  detailed_billing_records_generation_time : "2020-12-23 23:59:11",
  statement_generation_time : "2020-12-23 23:59:41",
  statement_summary_generation_time : "2020-12-23 23:59:53",
  currency: {
    name: "USD",
    symbol: "$"
  }
}

Statements for All Customers

Retrieve billing statements for all partner customers.

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

Parameters

  • status

    String that specifies the status of the statement. Valid values are Final or Estimated.

  • billing_period

    String that specifies the billing_period of the statement. The date is specified in the format YYYY-MM.

  • per_page

    Integer that specifies the number of assets to return per page.

  • page

    Integer that specifies the page to display when results run over multiple pages.

curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customer_statements/?page=1&status=Final&billing_period=2020-12&per_page=2'
{
  cloud: "AWS",
  billing_period : "2020-12",
  total_amount : 211,523.09,
  status : "Final",
  detailed_billing_records_generation_time : "2020-12-23 23:59:11",
  statement_generation_time : "2020-12-23 23:59:41",
  statement_summary_generation_time : "2020-12-23 23:59:53",
  currency: {
    name: "USD",
    symbol: "$"
  }
}

Connect GovCloud Commercial Account to GovCloud Asset Account

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

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

Parameters

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

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

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

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

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

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

List All GovCloud Linkages Owned by Current Customer

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

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

Parameters

  • client_api_idrequired

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

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

Details of Single GovCloud Linkage

Get details for a specific GovCloud linkage.

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

Parameters

  • client_api_idrequired

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

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

Update Single GovCloud Linkage

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

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

Parameters

  • client_api_idrequired

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

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

Understand Format of GovCloud Linkage Payload

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

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

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

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

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

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

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

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

Partner AWS Account Assignment

Introduction to Partner AWS Account Assignment API

An introduction to the Account Assignment API.

Use this API to administer AWS accounts that belong to CloudHealth partners and to assign AWS accounts to partner customers for partner-generated billing purposes.

Partner AWS Account Assignment API is available in two versions:

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

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

How AWS Account Assignments are Validated (Version 2)

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

CloudHealth uses the following criteria to validate AWS Account assignments.

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

Create AWS Account Assignment (Version 2)

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

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

Parameters

  • target_client_api_idrequired

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

  • billing_block_name

    String that specifies the unique name of the billing block.

  • billing_block_typerequired

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

  • owner_idrequired

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

  • payer_account_owner_id

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

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

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

Get All AWS Account Billing Blocks (Version 2)

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

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

Parameters

  • target_client_api_id

    The client API ID of the customer.

Response header

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

Response content

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

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

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

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

Get Single AWS Account Assignment (Version 2)

Retrieve information on a single AWS account assignment.

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

Response content

A JSON object with the following fields:

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

Update AWS Account Billing Block (Version 2)

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

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

Parameters

  • billing_block_namerequired

    String that specifies the name of the consolidated billing block.

  • payer_account_owner_idrequired

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

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

Delete AWS Account Assignment (Version 2)

Delete the relationship between an AWS account and the Partner Customer to which it was assigned. Note: If all accounts assigned to a billing block are deleted, the billing block is also deleted.

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

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

How AWS Account Assignments are Validated (Version 1)

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

CloudHealth uses the following criteria to validate AWS Account assignments.

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

Create AWS Account Assignment (Version 1)

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

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

Parameters

  • owner_idrequired

    The AWS ID of the assigned account.

  • customer_idrequired

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

  • payer_account_owner_id

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

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

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

Response header

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

Response content

A JSON object that contains these fields:

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

Read All AWS Account Assignments (Version 1)

Get information on all AWS account assignments.

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

Response header

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

Response content

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

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

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

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

Read Single AWS Account Assignment (Version 1)

Get information on a single AWS account assignment.

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

Parameters

  • idrequired

    The ID of the AWS account assignment

Response content

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

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

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

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

Update AWS Account Assignment (Version 1)

Update an existing AWS account assignment.

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

Parameters

  • idrequired

    The ID of the AWS account assignment

  • owner_idrequired

    The AWS ID of the assigned account.

  • customer_idrequired

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

  • payer_account_owner_id

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

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

Response header

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

Response content

A JSON object that contains these fields:

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

Delete AWS Account Assignment (Version 1)

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

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

Parameters

  • idrequired

    The ID of the AWS account assignment

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

Response header

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

Response content

A JSON object that contains these fields:

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

Partner Custom Price Books

Introduction to Price Book API

An introduction to the custom price book API.

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

  1. Create New Price Book
  2. Test New Price Book
  3. Assign Price Book to Customer
  4. Assign Price Book to Account

Note: Custom price books are only available for AWS.

Create New Price Book

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

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

Parameters

  • book_namerequired

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

  • specificationrequired

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

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

Modify Existing Price Book

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

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

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

Delete Existing Price Book

Delete a custom price book from the CloudHealth Platform.

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

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

Get All Price Books

Retrieve a list of all your custom price books.

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

Parameters

  • page

    Specify the page number for results

  • per_page

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

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

Get Price Book Request

Retrieve a specific custom price book.

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

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

Details of Price Book Request

Get details for a specific custom price book.

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

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

Understand Format of Price Book Specification

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

Parameters

  • CHTBillingRulesrequired

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

    • createdBy

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

    • daterequired

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

  • Comment

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

  • RuleGrouprequired

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

    • startDate

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

    • endDate

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

    • enabled

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

  • BillingRule

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

    • namerequired

      String specifying the name of the rule for documentation purposes

    • includeDataTransfer

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

    • includeRIPurchases

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

  • BasicBillingRule

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

    • billingAdjustmentrequired

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

    • billingRuleTyperequired

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

  • Product

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

    • productNamerequired

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

    • includeDataTransfer

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

    • includeRIPurchases

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

  • Region

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

    • namerequired

      String in AWS internal format that specifies the name of the region, such as us-east-2. To specify the start of the field, use the format [key word]*. To specify the end of the field, use the format *[key word]. To specify a key word that appears anywhere in the field, including the start or end, use the format *[key word]*.

  • UsageType

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

    • namerequired

      String specifying the usage type name, formatted to match the usage type name on the billing file without the instance-type prefixes and suffixes. To specify the start of the field, use the format [key word]*. To specify the end of the field, use the format *[key word]. To specify a key word that appears anywhere in the field, including the start or end, use the format *[key word]*.

  • Operation

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

    • namerequired

      String specifying the operation name, formatted to match the operation name on the billing file. To specify the start of the field, use the format [key word]*. To specify the end of the field, use the format *[key word]. To specify a key word that appears anywhere in the field, including the start or end, use the format *[key word]*.

  • RecordType

    Specifies the record types, or line item types, a rule applies to. Child element of Product.

    • name

      String specifying the start, end, or key word in the RecordType field. To specify the start of the field, use the format [key word]*. To specify the end of the field, use the format *[key word]. To specify a key word that appears anywhere in the field, including the start or end, use the format *[key word]*.

  • InstanceProperties

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

    • instanceType

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

    • instanceSize

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

    • reserved

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

  • LineItemDescription

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

    • name

      String specifying the start, end, or key word in the line item description field. To specify the start of the field, use the format [key word]*. To specify the end of the field, use the format *[key word]. To specify a key word that appears anywhere in the field, including the start or end, use the format *[key word]*.

    • startsWith

      String specifying the start of the line item description field

    • contains

      String specifying keywords in the line item description field

    • matchesRegex

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

  • SavingsPlanOfferingType

    Specifies the Savings Plan offering types a rule applies to. Child element of Product.

    • name

      String specifying the start, end, or key word in the SavingsPlanOfferingType field. To specify the start of the field, use the format [key word]*. To specify the end of the field, use the format *[key word]. To specify a key word that appears anywhere in the field, including the start or end, use the format *[key word]*.

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

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

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

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

Example:

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

  <RuleGroup>

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

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

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

  </RuleGroup>

</CHTBillingRules>

Understand Price Book Test Results

Learn how to review the results of the custom price book XML specification test.

Familiarize yourself with the format of the custom price book XML specification test results that you can verify whether the custom price book is accurate before you assign the price book to customers.

Test Result Formats: Test results are returned in aggregations that contain the calculated discounts and rates according to the custom price book XML specification. Three aggregations are provided in the following hierarchy:

  • Product-level
  • Usage type-level
  • Operation level

Review and Revise: Review the three aggregations and verify whether all discounts, rates, and adjustments for each product appear as expected. If any of the discounts, rates, or adjustments are incorrect, then there are mistakes present in the XML specification that must be corrected. There are several possible reasons why the XML specification is incorrect:

  • The data was incorrectly entered into the XML specification. Review the XML specification and verify that all discount, rate, and adjustment amounts are correct for each product.
  • The order is incorrect. The XML specification evaluates each rule in top-down order. Once a product has a discount, rate, or adjustment applied to it, the XML specification ignores all further price adjustments applied to that product. Verify that the rule order is correct in the XML specification.
  • The product name is misspelled. The productName attribute must exactly match the product name in the billing file and is case sensitive. For example, a discount to Amazon Elastic Compute cloud will be ignored because the last word in the product name isn’t properly capitalized. Verify that all product names in the XML specification are correctly spelled and formatted.

Once you have corrected the XML specification, modify the custom price book in CloudHealth and rerun the test.

Assign Price Book to Customer

Assign a custom price book to a customer or customers.

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

Parameters

  • price_book_idrequired

    Integer that specifies which custom price book to use.

  • target_client_api_idrequired

    Integer that specifies the assigned customer’s client_api_id.

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

Modify Existing Price Book Customer Assignment

Modify which custom price book is assigned to a customer.

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

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

Delete Existing Price Book Customer Assignment

Delete a custom price book’s customer assignment.

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

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

Get All Price Book Customer Assignments

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

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

Parameters

  • page

    Specify the page number for results

  • per_page

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

  • target_client_api_id

    Specifies the assigned customer’s client_api_id.

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

Get Price Book Customer Assignment

Retrieve one customer assigned to a custom price book.

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

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

Assign Price Book to Account

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

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

Parameters

  • price_book_assignment_idrequired

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

  • billing_account_owner_id

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

  • billing_account_owner_ids

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

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

Modify Existing Price Book Account Assignment

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

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

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

Delete Existing Price Book Account Assignment

Delete a custom price book’s AWS account assignment.

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

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

Get All Price Book Account Assignments

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

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

Parameters

  • page

    Specify the page number for results

  • per_page

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

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

Get Price Book Account Assignment

Retrieve one AWS account assigned to a custom price book.

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

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

Get Specific Customer Price Book Assignments

Run a query to get specific channel customer assignments.

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

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

Partner Billing Rules

Introduction to Billing Rule API

An introduction to the Billing Rule API.

Partner Billing Rules allow partners to adjust AWS and Azure customer costs globally or for specific customers. CloudHealth applies these adjustments when generating the bills for individual customers.

The Billing Rules API allows partner customers to create, modify, and delete AWS support and custom line item billing rules.

How to Get Billing Rule ID

In order to use some Billing Rule endpoints, you need to provide the partner_billing_rule_id. CloudHealth generates a unique ID for each billing rule. You can get the Billing Rule ID for an organization from the CloudHealth Platform. From the left menu, go to Partner > Partner Billing > Billing Rules and view or edit the organization. The Billing Rule ID appears in the browser URL. Here’s an example URL:

https://apps.cloudhealthtech.com/partner_billing_rules/57XXXXXXXXX96/edit

Here, 57XXXXXXXXX96 is the Billing Rule ID.

The Billing Rule ID can also be retrieved using the Create Billing Rule and Get All Billing Rules endpoints.

How to Get Azure Enterprise Agreement ID

In order to use some Billing Rule endpoints, you may need to provide the Azure Enterprise Agreement (EA) ID. CloudHealth generates a unique ID for each EA. You can get the Azure EA ID from the CloudHealth Platform. From the left menu, go to Setup > Accounts > Azure Enrollment and view or edit the EA. The Azure EA ID appears in the browser URL. Here’s an example URL:

https://apps.cloudhealthtech.com/azure_enrollments/20XXXXXXX19/edit

Here, 20XXXXXXX19 is the Azure EA ID.

Create New Partner Billing Rule

Add a new partner billing rule in the CloudHealth Platform.

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

Parameters

  • namerequired

    String that specifies the unique name of the billing rule.

  • cloudrequired

    Specify the cloud the billing rule applies to as either aws or azure.

  • add_target_customers

    Enter the client API keys of the AWS customers that the billing rule applies to. To apply the rule to all customers, enter all.

  • add_enterprise_agreements

    Specify which EA customers the billing rule applies to. Enter the EA’s client API key and the Azure EA ID in a comma-separated list.

  • add_csp_customers

    Enter the client API keys of the Microsoft CSP customers that the billing rule applies to. To apply the rule to all customers, enter all.

  • billing_rule_typerequired

    Specify whether the billing rule is custom (a custom line item) or support (an AWS support rule). You can only create an AWS support rule for a rule whose cloud is aws.

  • rule_actionrequired

    String that specifies what action the billing rule should take. For custom line items, enter flat_fee (flat fee charge or credit) or spend_ratio (percentage of spend charge or credit). For AWS support rules, enter flat_fee (flat fee charge), list_price (AWS list price charge), percentage_discount (percentage discount charge), suppress_charge (charges suppressed for this item), or custom_tier (custom pricing charge).

  • rule_scope

    Specify whether the scope of an AWS Support billing rule is per_account or per_billing_family. Default value is per_account.

  • support_tier

    Specify whether the support tier of an AWS Support billing rule is developer, business, or enterprise. Default value is developer.

  • flat_fee_cost

    For AWS support rules with a rule action of flat_fee, specify the flat fee charge amount. Required for flat fee AWS support rules.

  • charge_percentage_discount

    For AWS support rules with a rule action of percentage_discount, specify the percentage discount charge amount. Required for percentage discount AWS support rules.

  • pricing_info

    For AWS support rules with a rule action of custom_tier, specify in a JSON array the custom pricing structure. Custom tier pricing is structured as either a flat fee or a percentage of monthly AWS usage in four tiered spend ranges, whichever is greater. For example, the greater of either $100 or 10% for monthly AWS usage $0-$10,000; 7% for $10,000-$80,000; 5% for $80,000-$250,000; 3% for $250,000 and up. See AWS Support Plan Pricing for more information on AWS Support custom pricing. Required for custom tier pricing AWS support rules.

    • min_feerequired

      Enter the flat fee that should be charged if the percentage of AWS spend is lower than this amount. For example, 100.

    • min_spend_rangerequired

      Enter the lower AWS spend range for each of the four spend range tiers in a comma-separated list. For example, [0, 10000, 80000, 250000]

    • min_spend_raterequired

      Enter the percentage charged to each of the four AWS spend range tiers in a comma-separated list. For example, [10,7,5,3].

  • start_month

    For custom line items, specify the month the billing rule should take effect. The date string has the format YYYY-MM. Default value is the current month.

  • frequency

    For custom line items, specify whether the billing rule is one_time or recurring. Default value is one_time.

  • product_name

    For custom line items, specify the product name of the billing rule. This name appears as a line item in the customer’s bill. Required for custom line items.

  • product_description

    For custom line items, specify the product description of the billing rule. This description appears in the line item in the customer’s bill. Required for custom line items.

  • type

    For custom line items, specify whether the billing rule is a charge or credit. Default value is charge.

  • apply_flat_fee_cost

    For custom line items with a rule action of flat_fee, enter specify the flat fee amount. Required for flat fee custom line item rules.

  • apply_rate_in_percentage

    For custom line items with a rule action of spend_ratio, specify the percentage of spend amount. Required for percentage of spend custom line item rules.

  • add_spend_ratio_as_custom_line_item

    For Azure custom line items with a rule action of spend_ratio, specify whether to apply the percentage credits and charges once to the main subscription (true) or to each line item in the bill (false). The default value is false.

{
  "name": "Business support",
  "cloud": "aws",
  "billing_rule_type": "custom_tier",
  "add_target_customers": [1,2,3],
  "rule_action": "custom_tier",
  "rule_scope": "per_billing_family",
  "support_tier": "business",
  "pricing_info":{
    "min_fee": 100,
    "min_spend_range":[0,10000, 80000, 250000],
    "min_spend_rate": [10,7,5,3]
  }
}
{
  "name": "Customer markup",
  "add_target_customers": [1,2,3],
  "cloud": "aws",
  "billing_rule_type": "custom",
  "rule_action": "spend_ratio",
  "start_month": "2019-05",
  "frequency": "recurring",
  "product_name": "markup",
  "product_description": "markup",
  "type": "charge",
  "apply_rate_in_percentage": 5
}
{
  "name": "Customer markup",
  "add_csp_customers":[3,4]
  "add_enterprise_agreements": {<client_api_key>:[234,456], "2":[457,890]},
  "billing_rule_type": "custom",
  "cloud": "azure",
  "rule_action": "flat_fee",
  "start_month": "2019-05",
  "frequency": "recurring",
  "product_name": "markup",
  "product_description": "markup",
  "type": "charge",
  "apply_flat_fee_cost": 1000
}
{
  "name": "Customer markup",
  "product_name": "markup",
  "product_description": "markup",
  "rule_scope": "per_account",
  "billing_rule_type": "custom",
  "cloud": "aws",
  "target_customers": [1,2,3],
  "start_month": "2019-05",
  "frequency": "recurring",
  "type": "charge",
  "rate_in_percentage": 5
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "name": "Customer markup",
    "add_target_customers": [1,2,3],
    "cloud": "aws",
    "billing_rule_type": "custom",
    "rule_action": "spend_ratio",
    "start_month": "2019-05",
    "frequency": "recurring",
    "product_name": "markup",
    "product_description": "markup",
    "type": "charge",
    "apply_rate_in_percentage": 5
  }'    
    'https://chapi.cloudhealthtech.com/v1/partner_billing_rules'

Modify Existing Billing Rule

Modify an existing billing rule in the CloudHealth Platform. You cannot modify the billing rule’s cloud, billing rule type, or rule action.

https://chapi.cloudhealthtech.com/v1/partner_billing_rules/:partner_billing_rule_id

Parameters

  • namerequired

    String that specifies the unique name of the billing rule.

  • add_target_customers

    Enter the client API keys of the AWS customers that the billing rule applies to. To apply the rule to all customers, enter all.

  • remove_target_customers

    Enter the client API keys of the AWS customers that should be removed from the billing rule.

  • add_enterprise_agreements

    Specify which EA customers the billing rule applies to. Enter the EA’s client API key and the Azure EA ID in a comma-separated list.

  • remove_enterprise_agreements

    Specify which EA customers should be removed from the billing rule. Enter the EA’s client API key and the Azure EA ID in a comma-separated list.

  • add_csp_customers

    Enter the client API keys of the Microsoft CSP customers that the billing rule applies to. To apply the rule to all customers, enter all.

  • remove_csp_customers

    Enter the client API keys of the Microsoft CSP customers that should be removed from the billing rule.

  • rule_scope

    Specify whether the scope of an AWS Support billing rule is per_account or per_billing_family. Default value is per_account.

  • support_tier

    Specify whether the support tier of an AWS Support billing rule is developer, business, or enterprise. Default value is developer.

  • flat_fee_cost

    For AWS support rules with a rule action of flat_fee, specify the flat fee charge amount. Required for flat fee AWS support rules.

  • charge_percentage_discount

    For AWS support rules with a rule action of percentage_discount, specify the percentage discount charge amount. Required for percentage discount AWS support rules.

  • pricing_info

    For AWS support rules with a rule action of custom_tier, specify in a JSON array the custom pricing structure. Custom tier pricing is structured as either a flat fee or a percentage of monthly AWS usage in four tiered spend ranges, whichever is greater. For example, the greater of either $100 or 10% for monthly AWS usage $0-$10,000; 7% for $10,000-$80,000; 5% for $80,000-$250,000; 3% for $250,000 and up. See AWS Support Plan Pricing for more information on AWS Support custom pricing. Required for custom tier pricing AWS support rules.

    • min_feerequired

      Enter the flat fee that should be charged if the percentage of AWS spend is lower than this amount. For example, 100.

    • min_spend_rangerequired

      Enter the lower AWS spend range for each of the four spend range tiers in a comma-separated list. For example, [0, 10000, 80000, 250000]

    • min_spend_raterequired

      Enter the percentage charged to each of the four AWS spend range tiers in a comma-separated list. For example, [10,7,5,3].

  • start_month

    For custom line items, specify the month the billing rule should take effect. The date string has the format YYYY-MM. Default value is the current month.

  • frequency

    For custom line items, specify whether the billing rule is one_time or recurring. Default value is one_time.

  • product_name

    For custom line items, specify the product name of the billing rule. This name appears as a line item in the customer’s bill. Required for custom line items.

  • product_description

    For custom line items, specify the product description of the billing rule. This description appears in the line item in the customer’s bill. Required for custom line items.

  • type

    For custom line items, specify whether the billing rule is a charge or credit. Default value is charge.

  • apply_flat_fee_cost

    For custom line items with a rule action of flat_fee, enter specify the flat fee amount. Required for flat fee custom line item rules.

  • apply_rate_in_percentage

    For custom line items with a rule action of spend_ratio, specify the percentage of spend amount. Required for percentage of spend custom line item rules.

  • add_spend_ratio_as_custom_line_item

    For Azure custom line items with a rule action of spend_ratio, specify whether to apply the percentage credits and charges once to the main subscription (true) or to each line item in the bill (false). The default value is false.

{
  "name": "Customer markup 23",
  "add_enterprise_agreements": {"1":[2]},
  "remove_csp_customers":[111]
  "start_month": "2019-06",
  "frequency": "one_time",
  "apply_rate_in_percentage": 4
}
{
  "id": 1,
  "name": "Customer markup 23",
  "product_name": "markup",
  "product_description": "markup",
  "billing_rule_type": "custom",
  "cloud": "azure",
  "csp_customers": [1,2],
  "enterprise_agreements":{"1":[2]},
  "start_month": "2019-06",
  "frequency": "one_time",
  "type": "charge",
  "rate_in_percentage": 4,
  "add_spend_as_custom_line_item": true
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "name": "Customer markup 23",
    "add_enterprise_agreements": {"1":[2]},
    "remove_csp_customers":[111]
    "start_month": "2019-06",
    "frequency": "one_time",
    "apply_rate_in_percentage": 4
  }'
    'https://chapi.cloudhealthtech.com/v1/partner_billing_rules/<partner_billing_rule_id>'

Get Single Billing Rule

Retrieve a specific billing rule.

https://chapi.cloudhealthtech.com/v1/partner_billing_rules/:partner_billing_rule_id

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

Delete Existing Billing Rule

Delete a billing rule from the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/partner_billing_rules/:partner_billing_rule_id

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

Azure Service Principals

Introduction to Azure Service Principal API

An introduction to the Azure Service Principal API.

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

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

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

How to Get Service Principal ID

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

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

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

Here, 33672XXXXXX68 is the service principal ID.

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

Connect Service Principal in CloudHealth

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

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

Parameters

  • namerequired

    String that specifies the name of the service principal.

  • client_idrequired

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

  • client_secretrequired

    The secret key for the client ID.

  • tenant_idrequired

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

  • sp_type

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

  • is_metrics_enabled

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

  • disable_assets_collection

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

    • AzureActiveDirectoryRoleDefinition

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

    • AzureActiveDirectoryUser

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

    • AzureKeyVaultKey

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

    • AzureKeyVaultSecret

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

    • AzureSqlDatabaseAuditing

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

    • AzureSqlDatabaseThreatDetection

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

    • AzureSqlServerAuditing

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

    • AzureSqlServerFirewallRule

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

    • AzureSqlServerThreatDetection

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

    • AzureSubscriptionSecurityPolicy

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

  • create_sp_for_partner_customer

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

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

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

Modify Existing Service Principal

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

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

Parameters

  • namerequired

    String that specifies the name of the service principal.

  • client_secretrequired

    The secret key for the client ID.

  • is_metrics_enabled

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

  • modify_sp_for_partner_customer

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

  • disable_assets_collection

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

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

Get All Existing Service Principals

Retrieve a list of all service principals.

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

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

Details of Service Principal

Get details for a specific service principal.

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

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

Azure Partner

Introduction to Microsoft CSP Partner API

An introduction to the Microsoft CSP Partner API.

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

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

How to Get Client API ID

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

You can get the Client API ID for a customer 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 Get Database Partner Customer ID

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

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

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

Here, 5XXXXXXXXXX25 is the Database Partner Customer ID.

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

Create CSP Partner Customer

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

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

Parameters

  • namerequired

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

  • azure_customer_id

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

  • address

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

    • street1required

      Line 1 of street address

    • street2

      Line 2 of street address. Can be blank.

    • cityrequired

      City specified as a string

    • staterequired

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

    • zipcoderequired

      Zipcode specified as a number

    • countryrequired

      Country specified a string

  • classification

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

  • trial_expiration_date

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

  • billing_contact

    String that specifies the email address of customer contact.

  • partner_billing_configuration

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

    • enabledrequired

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

    • folder

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

  • tags

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

    • keyrequired

      Tag key

    • valuerequired

      Tag value

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

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

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

Get All Partner Customers

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

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

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

Get Single Partner Customer

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

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

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

Modify Existing Partner Customer

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

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

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

Get All CSP Partner Customers

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

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

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

Get Single CSP Partner Customer

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

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

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

Add Subscriptions to MSP Client

Assign subscriptions to a MSP client.

https://chapi.cloudhealthtech.com/v1/azure_subscriptions/add/db_msp_client_id

Response Code Description
401 API key is wront or the request is not made by the partner
500 Internal server error
422 Azure ID is not found or is invalid or already assigned to a MSP client
404 MSP client ID not found
403 API key provided is invalid
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/azure_subscriptions/add/db_msp_client_id'

Get all MSP Client Subscriptions

List all subscriptions associated with MSP clients.

https://chapi.cloudhealthtech.com/v1/azure_subscriptions/list/db_msp_client_id

Response Code Description
401 API key is wront or the request is not made by the partner
500 Internal server error
422 Azure ID is not found or is invalid or already assigned to a MSP client
404 MSP client ID not found
403 API key provided is invalid
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/azure_subscriptions/list/db_msp_client_id'

Remove Subscription from MSP Client

Removes all subscriptions associated with a MSP client.

https://chapi.cloudhealthtech.com/v1/azure_subscriptions/remove/db_msp_client_id

Response Code Description
401 API key is wront or the request is not made by the partner
500 Internal server error
422 Azure ID is not found or is invalid or already assigned to a MSP client
404 MSP client ID not found
403 API key provided is invalid
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/azure_subscriptions/remove/db_msp_client_id'

Partner Azure Account Assignment

Introduction to Partner Azure Account Assignment API

An introduction to the Account Assignment API.

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

Create Azure Account Assignment

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

/v1/azure_partner_customer_accounts/add/:client_api_id

Parameters

  • azure_customer_idsrequired

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

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

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

Get All Azure Account Assignments

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

/v1/azure_partner_customer_accounts/list

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

Get Single Azure Account Assignment

Retrieve information on a single Azure account assignment.

/v1/azure_partner_customer_accounts/list/:client_api_id

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

Delete Azure Account Assignment

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

/v1/azure_partner_customer_accounts/remove/:client_api_id

Parameters

  • azure_customer_idsrequired

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

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

GCP Billing Accounts

Introduction to GCP Billing Account API

An introduction to the GCP Billing Account API.

The GCP billing account contains a customer’s projects and are the source of truth for a customer’s cost and usage data. By connecting the GCP billing account to the CloudHealth Platform, you allow the CloudHealth Platform access to the data the Platform needs to create reports and recommendations on how to better manage your cloud and cut down on costs. When the GCP billing account is connected, the Platform automatically pulls in derived projects. Random change.

The GCP Billing Account API allows both direct customers and GCP partners to connect GCP billing accounts with the CloudHealth Platform.

How to Get Client API ID

If you are a GCP partner, 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 Get CloudHealth Billing Account ID

In order to use some of the GCP Billing Account endpoints, you need to provide the cloudhealth_billing_account_id. CloudHealth generates a unique ID for each billing account.

You can get the CloudHealth Billing Account ID for a billing account from the CloudHealth Platform. From the left menu, go to Setup > Accounts > GCP Billing and open the billing account. The CloudHealth Billing Account ID of the partner customer appears in the browser URL. Here’s an example URL:

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

Here, 5XXXXXXXXXX25 is the CloudHealth Billing Account ID.

The CloudHealth Billing Account ID can also be retrieved using the Get All GCP Billing Accounts endpoint.

How to Encode a JSON Private Key

Several GCP Billing Account API endpoints require you to enter the JSON private key for the service account associated with the billing account. Before you can enter the JSON private key in the endpoint parameter, you must first encode the JSON private key.

  1. Create and download the JSON private key in gcloud. For more information, see the Creating and Managing Service Account Keys.
  2. In gcloud, enter the command cloudshell download <private key name>.json to download the JSON private key. When prompted, click Download.
  3. In Terminal, enter the command cd downloads to open the Downloads folder.
  4. In Terminal, enter the following command to encode the downloaded private key: base64 < '<private key name>.json'
  5. Copy the private key generated in the response. Use this private key for the billing_account_service_account_json_key or linked_projects_json_key parameter.

Enable GCP Billing Account

Enable a GCP billing account for a direct customer or a partner customer in the CloudHealth Platform.

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

Parameters

  • client_api_id

    The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.

  • billing_account_namerequired

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

  • billing_account_idrequired

    The GCP billing account ID of the billing account in the Google Console.

  • bq_billing_datasetrequired

    String that specifies the BigQuery billing dataset name.

  • bq_billing_projectrequired

    String that specifies the BigQuery billing project ID.

  • bq_activation_daterequired

    Date in YYYY-MM-DD format that specifies the BigQuery activation date. To locate the activation date, run the following query in the BigQuery Query Editor, replacing insert_table_name with the BigQuery table name - SELECT min(export_time) FROM insert_table_name.

  • bq_billing_table

    String that specifies the name of the BigQuery billing table. By default, the customer-owned BigQuery table is used. If you are a partner enabling a partner customer GCP billing account, you should assign the partner-owned BigQuery table, not the customer-owned table.

  • billing_bucketrequired

    String that specifies the name of the billing bucket that contains the GCP billing export for the billing account.

  • billing_bucket_prefixrequired

    String that specifies the report prefix for the billing bucket.

  • billing_account_service_accountrequired

    String that specifies the GCP service account associated with the billing account.

  • billing_account_service_account_json_key

    Enter the service account’s private JSON key in the format data:application/json;base64, <private JSON key>.

  • linked_projects_service_account

    String that specifies the second GCP service account associated with the billing account, if applicable. To ensure that the minimum set of permissions are used, some customers might prefer to use two service accounts for CloudHealth, one for billing data and one for asset and rightsizing data. CloudHealth recommends that partners use two service accounts for their partner customers, with the billing data service account owned by the partner and the asset and rightsizing data service account owned by the partner customer.

  • linked_projects_json_key

    Enter the second service account’s private JSON key in the format data:application/json;base64, <private JSON key>.

Note: If you update the service account key here, it will not be applied to the derived projects. Use the Graphql API Update GCP Project Details to apply the service account key to all the derived projects.

Response Code Description
422 Unprocessable Entity Unprocessable entity
401 Unauthorized Unauthorized entry
403 Forbidden Invalid Client API ID
422 Unprocessable Entry Input format errors
500 Internal Service Error Internal service error
{
  "billing_account_name": <billing_account_name>,
  "billing_account_id": <billing_account_id>,
  "bq_billing_dataset": <bq_billing_dataset>,
  "bq_billing_project": <bq_billing_project>,
  "bq_billing_activation_date": <bq_billing_activation_date>,
  "billing_bucket": <billing_bucket>,
  "billing_bucket_prefix": <billing_bucket_prefix>,
  "billing_account_service_account": <billing_account_service_account>,
  "billing_account_service_account_json_key": data:application/json;base64, <private JSON key>,
  "linked_projects_service_account" : <linked_projects_service_account>,
  "linked_projects_json_key": data:application/json;base64, <private JSON key>
}
{
  "cloudhealth_billing_account_id": "6116033430514",
  "billing_account_name": "Chayan Test BA",
  "billing_account_id": "00807B-DFFF5B-2DAAB8",
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  '{
    "billing_account_name": <billing_account_name>,
    "billing_account_id": <billing_account_id>,
    "bq_billing_dataset": <bq_billing_dataset>,
    "bq_billing_project": <bq_billing_project>,
    "bq_billing_activation_date": <bq_billing_activation_date>,
    "billing_bucket": <billing_bucket>,
    "billing_bucket_prefix": <billing_bucket_prefix>,
    "billing_account_service_account": <billing_account_service_account>,
    "billing_account_service_account_json_key": <billing_account_service_account_json_key>,
    "linked_projects_service_account" : <linked_projects_service_account>,
    "linked_projects_json_key": <linked_projects_json_key>
  }'
    'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts'

Get All GCP Billing Accounts

Retrieve a list of all GCP billing accounts that have been enabled with the CloudHealth Platform.

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

Parameters

  • client_api_id

    The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.

  • per_page

    Specify how many results should be displayed per page. Default value is 25. Maximum value is 50.

  • page

    Specify the page number for results. Default value is 1.

curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts?per_page=<max_page_count>&page=<page_number>'

Get Single GCP Billing Account

Retrieve a specific GCP billing account that you have enabled with the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/:cloudhealth_billing_account_id

Parameters

  • cloudhealth_billing_account_idrequired

    The CloudHealth billing account ID of the GCP billing account. For more information, see How to Get CloudHealth Billing Account ID.

  • client_api_id

    The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.

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

Modify Existing GCP Billing Account

Modify a GCP billing account that already exists in the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/:cloudhealth_billing_account_id

Parameters

  • cloudhealth_billing_account_idrequired

    The CloudHealth billing account ID of the GCP billing account. For more information, see How to Get CloudHealth Billing Account ID.

  • client_api_id

    The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.

  • billing_account_name

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

  • billing_account_id

    The GCP billing account ID of the billing account in the Google Console.

  • bq_billing_dataset

    String that specifies the BigQuery billing dataset name.

  • bq_billing_project

    String that specifies the BigQuery billing project ID.

  • bq_activation_date

    Date in YYYY-MM-DD format that specifies the BigQuery activation date. To locate the activation date, run the following query in the BigQuery Query Editor, replacing insert_table_name with the BigQuery table name - SELECT min(export_time) FROM insert_table_name

  • bq_billing_table

    String that specifies the name of the BigQuery billing table.

  • billing_bucket

    String that specifies the name of the billing bucket that contains the GCP billing export for the billing account.

  • billing_bucket_prefix

    String that specifies the report prefix for the billing bucket.

  • billing_account_service_account

    String that specifies the GCP service account associated with the billing account.

  • billing_account_service_account_json_key

    Enter the service account’s private JSON key in the format data:application/json;base64, <private JSON key>.

  • linked_projects_json_key

    Enter the second service account’s private JSON key in the format data:application/json;base64, <private JSON key>.

Note: If you update the service account key here, it will not be applied to the derived projects. Contact CloudHealth Support to apply the service account key to all the derived projects.

{
  "cloudhealth_billing_account_id": <cloudhealth_billing_account_id>,
  "client_api_id": <client_api-id>,
  "billing_account_name": <billing_account_name>,
  "billing_account_id": <billing_account_id>,
  "bq_billing_dataset": <bq_billing_dataset>,
  "bq_billing_project": <bq_billing_project>,
  "bq_billing_activation_date": <bq_billing_activation_date>,
  "bq_billing_table": <bq_billing_table>,
}
{
  "cloudhealth_billing_account_id": "6116033430514",
  "billing_account_name": "Chayan Development BA",
  "billing_account_id": "00807B-DFFF5B-2DAAB8",
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
  "cloudhealth_billing_account_id": <cloudhealth_billing_account_id>,
  "client_api_id": <client_api-id>,
  "billing_account_name": <billing_account_name>,
  "billing_account_id": <billing_account_id>,
  "bq_billing_dataset": <bq_billing_dataset>,
  "bq_billing_project": <bq_billing_project>,
  "bq_billing_activation_date": <bq_billing_activation_date>,
  "bq_billing_table": <bq_billing_table>,
}'
'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/<cloudhealth_billing_account_id>'

Delete GCP Billing Account

Remove a GCP billing account from the CloudHealth Platform.

https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/:cloudhealth_billing_account_id

Parameters

  • cloudhealth_billing_account_idrequired

    The CloudHealth billing account ID of the GCP billing account. For more information, see How to Get CloudHealth Billing Account ID.

  • client_api_id

    The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.

{
  "cloudhealth_billing_account_id": "6116033430514",
  "billing_account_name": "Chayan Test BA",
  "billing_account_id": "00807B-DFFF5B-2DAAB8",
}
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
  'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/<cloudhealth_billing_account_id>'