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

# Cloudhealthtech CloudHealth API

Jentic publishes the only available OpenAPI specification for CloudHealth API, keeping it validated and agent-ready. CloudHealth (now part of Broadcom VMware) is a multi-cloud cost management platform. This variant of the spec covers AWS account onboarding, SSO configuration, perspective groupings used to slice cloud spend, reporting, and asset queries against the CloudHealth platform. Authentication is a bearer API token issued in the CloudHealth UI.

## For AI agents

Manage AWS account registration, SSO, perspectives, and cost reports inside CloudHealth using a bearer API token.

## 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 and update AWS accounts on CloudHealth at `/v1/aws_accounts`
- Generate the AWS external ID needed for the cross-account IAM role
- Configure and unconfigure SSO at `/v1/sso/configure` and `/v1/sso/unconfigure`
- Create and manage perspectives that group cloud assets for cost allocation
- Run reporting queries against the perspective and asset surfaces
- Validate pending domain claims for SSO onboarding

## Use cases

### Automated AWS Account Onboarding

Register new AWS accounts in CloudHealth as part of a landing-zone provisioning pipeline. POST `/v1/aws_accounts` to add the account, call `/v1/aws_accounts/{id}/generate_external_id` to get the cross-account role's external ID, and feed it into the IAM role provisioning step. Removes the manual UI clicks from the multi-account onboarding runbook.

Example prompt: POST `/v1/aws_accounts` with the new account ID, then GET `/v1/aws_accounts/{id}/generate_external_id` and pass the value to the IAM role creation.

### SSO Configuration Lifecycle

Manage SSO setup for a CloudHealth tenant programmatically. `/v1/sso/configure` registers the identity provider details, `/v1/sso/configuration` reads the current state, and `/v1/sso/unconfigure` tears it down. Pending domain claims are listed and validated through `/v1/sso/pending_domain_claims` so a script can complete the verification step.

Example prompt: POST `/v1/sso/configure` with the IdP metadata, then GET `/v1/sso/pending_domain_claims` and POST `/v1/sso/validate_pending_domain_claim` for each.

### Perspective-Driven Cost Reporting

Slice cloud spend by business unit, environment, or product using CloudHealth perspectives, then read the values into a finance dashboard. `/v1/perspective_schemas` exposes how each perspective is grouped, and the reporting endpoints return spend by perspective for downstream BI.

Example prompt: GET `/v1/perspective_schemas` to list perspectives, then GET `/v1/perspective_schemas/{perspective_id}` for the chosen schema and pass the groupings to the reporting endpoint.

### 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 'list 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 it 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/{perspective_id}` | Get a single perspective schema |

## Key resources

- **AWS Accounts** — Registered AWS accounts 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** — Cost and usage reports against perspectives.
- **Assets** — Asset queries returning cloud resources tracked by CloudHealth.

## Why Jentic

- **Setup:** Wiring the CloudHealth API by hand means setting up its bearer token auth and pointing every call at chapi.cloudhealthtech.com yourself. Through Jentic you install once, import the CloudHealth API from the API Directory, store the token 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 token 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 'register an AWS account in CloudHealth' or 'list cost perspectives', and Jentic returns the matching operation with its input schema so the agent calls the right /v1 endpoint without browsing the reference docs.

## Related APIs

- **CloudHealth API** — Alternate import of the CloudHealth spec with both bearer and ApiKey query auth.
- **AWS Cost Explorer** — AWS-native cost and usage 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?

The API uses bearer token authentication. Generate an API token in the CloudHealth UI under My Profile and pass it as Authorization: Bearer <token>. Through Jentic, the token is stored encrypted in the vault and never enters the agent's context.

### Can I onboard a new AWS account through the API?

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

### How do I list cost 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.

### Can the API configure SSO for the tenant?

Yes. POST `/v1/sso/configure` registers the IdP metadata, GET `/v1/sso/configuration` reads the current state, and POST `/v1/sso/unconfigure` tears it down. Use `/v1/sso/pending_domain_claims` and `/v1/sso/validate_pending_domain_claim` to complete domain verification.

### What is the difference between this CloudHealth spec and the cloudhealthtech.com main spec?

Both target chapi.cloudhealthtech.com. This cloudhealth-api variant uses bearer auth only and covers 22 endpoints. The main variant adds an alternative ApiKey query parameter scheme and one or two extra paths. Pick the variant that matches your auth approach.

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

Yes. Because you self-host Jentic One, your own rules decide which CloudHealth operations and credentials the agent may use. CloudHealth puts the AWS account id in the URL path (`/v1/aws_accounts/{id}/...`), so a rule can pin the agent to one onboarded account, letting it read that account and generate its external id and nothing else. Since you pick the operations it can call, higher-impact actions like registering a new AWS account or configuring SSO at `/v1/sso/configure` are only reachable if you include them.