canonical: https://jentic.com/apis/cloudhealthtech.com/cloudhealth-main

# Cloudhealthtech CloudHealth API

Jentic publishes the only available OpenAPI specification for CloudHealth API, keeping it validated and agent-ready. CloudHealth is a multi-cloud cost management platform owned by Broadcom VMware. This main variant of the spec covers AWS account onboarding, SSO configuration, perspectives for cost grouping, reporting, and asset queries, and supports two auth schemes - bearer token in the Authorization header and an api_key query parameter - so legacy scripts and modern SDK clients can share the same surface. Coverage spans 24 endpoints.

## For AI agents

Manage CloudHealth AWS accounts, SSO, perspectives, reports, and assets via bearer token or api_key query parameter authentication.

## Scope

Does not provision cloud resources, ingest billing data directly from cloud providers, or replace AWS Cost Explorer - use for CloudHealth tenant configuration and perspective reporting only.

## Capabilities

- Register AWS accounts and generate the cross-account IAM external ID
- Configure, read, and unconfigure SSO including pending domain claims
- Create and inspect perspectives that group cloud spend by tag, account, or service
- Run reports and asset queries against the CloudHealth dataset
- Authenticate with either Bearer tokens or the legacy api_key query parameter
- Validate pending domain claims to complete SSO onboarding

## Use cases

### Multi-Cloud Cost Reporting

Surface cloud spend in a finance dashboard by reading CloudHealth perspective and reporting endpoints. `/v1/perspective_schemas` exposes how each perspective is grouped, and report endpoints return spend by perspective for downstream BI. Avoids screen-scraping the CloudHealth UI for monthly close.

Example prompt: GET `/v1/perspective_schemas`, pick the chargeback perspective by name, then GET `/v1/perspective_schemas/{perspectiveId}` and pass the groupings to the cost report endpoint.

### AWS Account Onboarding Automation

Register new AWS accounts in CloudHealth from a landing-zone pipeline. POST `/v1/aws_accounts` to add the account, GET `/v1/aws_accounts/{id}/generate_external_id` for the cross-account role's external ID, and pass that ID to the IAM role provisioning step. Removes manual UI work from the multi-account onboarding runbook.

Example prompt: POST `/v1/aws_accounts` with the account ID and metadata, then GET `/v1/aws_accounts/{id}/generate_external_id` and feed it into the IAM role creation.

### Legacy Script Compatibility

Run scripts that were written before CloudHealth supported bearer tokens by using the api_key query parameter scheme defined in the spec. The same endpoints accept either auth method, so a gradual migration is possible without a forklift rewrite.

Example prompt: Append ?api_key=<token> to the request URL when calling GET `/v1/aws_accounts` from legacy automation that cannot easily set Authorization headers.

### AI Agent FinOps Workflow

Let a Jentic-powered FinOps agent answer cost questions and onboard accounts. The agent searches Jentic for 'register AWS account in CloudHealth' or 'get CloudHealth perspectives', loads the matching operation, and executes it. The CloudHealth bearer token stays in your Jentic One instance.

Example prompt: Search Jentic for 'list CloudHealth perspectives', load the listPerspectives operation, and execute under the stored bearer token.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/aws_accounts` | List registered AWS accounts |
| POST | `/v1/aws_accounts` | Register a new AWS account |
| GET | `/v1/aws_accounts/{id}/generate_external_id` | Generate the IAM external ID |
| POST | `/v1/sso/configure` | Configure SSO for the tenant |
| GET | `/v1/sso/configuration` | Read current SSO configuration |
| POST | `/v1/sso/validate_pending_domain_claim` | Validate a pending domain claim |
| GET | `/v1/perspective_schemas` | List perspective schemas |
| GET | `/v1/perspective_schemas/{perspectiveId}` | Get a single perspective schema |

## Key resources

- **AWS Accounts** — Account registration and external ID generation at `/v1/aws_accounts.`
- **SSO** — SSO configuration and pending domain claims at `/v1/sso.`
- **Perspectives** — Cost grouping schemas at `/v1/perspective_schemas.`
- **Reporting** — Reports against perspectives and assets.
- **Assets** — Asset queries returning cloud resources tracked by CloudHealth.

## Why Jentic

- **Setup:** Wiring the CloudHealth API by hand means handling either a bearer token or the equivalent api_key query value and pointing every call at chapi.cloudhealthtech.com yourself. Through Jentic you install once, import the CloudHealth API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** CloudHealth puts the AWS account id in the URL path (`/v1/aws_accounts/{id}/...`), so a rule can pin your agent to one onboarded account: it can read that account and generate its external id and nothing else. You choose the operations it may call, so registering a new account or configuring SSO is only in reach if you include it.
- **Credential handling:** Your CloudHealth bearer token or api_key value is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list CloudHealth perspectives' or 'register an AWS account in CloudHealth', and Jentic returns the matching operation with its input schema so the agent calls the correct /v1 endpoint without browsing the reference docs.

## Related APIs

- **CloudHealth API** — Bearer-only variant of the same CloudHealth surface with 22 endpoints.
- **AWS Cost Explorer** — AWS-native cost data without third-party FinOps tooling.
- **AWS Budgets** — Threshold and forecast alerts on AWS spend.

## FAQ

### Why is there no official OpenAPI spec for CloudHealth API?

CloudHealth Technologies does not publish a structured OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CloudHealth API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the CloudHealth API use?

This spec defines two schemes. BearerAuth expects an Authorization: Bearer <token> header, and ApiKeyAuth accepts the same token as a ?api_key=<token> query parameter for legacy scripts. Through Jentic, tokens are stored encrypted in the vault and injected at execution.

### Can I onboard a new AWS account through this CloudHealth API?

Yes. POST `/v1/aws_accounts` with the account ID and metadata, then GET `/v1/aws_accounts/{id}/generate_external_id` for the IAM external ID. Use that value when creating the cross-account role in AWS to complete onboarding.

### How do I list CloudHealth perspectives through Jentic?

Run jentic search 'list CloudHealth perspectives', load the listPerspectiveSchemas operation, and execute GET `/v1/perspective_schemas.` Jentic handles the bearer token from the stored credential.

### What is the difference between this main spec and the cloudhealth-api spec?

Both target chapi.cloudhealthtech.com. This main variant exposes 24 endpoints and supports both bearer and api_key query authentication, while the cloudhealth-api variant covers 22 endpoints with bearer auth only. Pick whichever matches your auth and endpoint needs.

### Can I use the api_key query parameter for authentication?

Yes. The ApiKeyAuth scheme accepts the token as ?api_key=<token>. This is supported for backward compatibility with older scripts; new integrations should prefer the bearer token header.

### Can I limit what my agent is allowed to do with the CloudHealth API?

Yes. Because you run Jentic One yourself, your own rules decide which CloudHealth operations and credentials the agent may use. Since CloudHealth carries the AWS account id in the URL path (`/v1/aws_accounts/{id}/...`), you can pin the agent to a single onboarded account so it only reads that account and generates its external id via GET `/v1/aws_accounts/{id}/generate_external_id.` Broader actions like POST `/v1/aws_accounts` to register an account or POST `/v1/sso/configure` to change SSO are reachable only if you include them in what the agent is allowed to call.