# Cloudability (IBM Apptio)

> Cloudability is IBM Apptio's cloud cost management and FinOps platform. It provides cost
> visibility, optimization recommendations, anomaly detection and governance across AWS, Azure,
> Google Cloud, OCI and custom (FOCUS) data sources. The Cloudability API v3 is a REST/JSON API
> for reporting, business mappings, rightsizing, anomalies, containers, views, users and vendor
> credentials.

This file is generated by API Evangelist from public documentation and live probes on 2026-09-05.
Cloudability does not publish an llms.txt of its own on any of its hosts (probed:
www.cloudability.com 404, www.apptio.com 404, www.ibm.com 404).

## Facts an agent needs first

- Base URL: https://api.cloudability.com/v3
- Regional hosts (choose by region, same paths): api-eu, api-au, api-ca, api-in, api-jp, api-me,
  api-sg .cloudability.com, and api.usgov.cloudability.com for US Government.
- Auth: `Authorization: Basic <cloudability_api_key>` OR the header pair `apptio-opentoken` +
  `apptio-environmentid`. GovCloud accepts only apptio-opentoken.
- Every anonymous request to api.cloudability.com returns HTTP 401, including paths that do not
  exist. A 401 is not evidence that a resource exists.
- Response envelope: `{"result": {} | [], "meta": {}}`. JSON by default; CSV available on cost
  reporting via the Accept header.
- Errors: `{"error":{"status","code","messages":[],"uniqueid","typeid","traceid"}}` — vendor JSON,
  NOT RFC 9457 problem+json.
- Pagination: `limit` (default 50) + `offset` (default 0), used together. Not every endpoint
  supports it.
- Sorting: `sort=+attribute` / `sort=-attribute`. Filtering: `filter=name <op> expression` with
  `==`, `!=`, `>`, `<`, `=@`, `!=@`.
- There is NO idempotency key, NO dry-run mode and NO documented rate limit. Retrying a failed
  write is a second write.

## Documentation

- [Getting started with Cloudability API V3](https://www.ibm.com/docs/en/cloudability-commercial/cloudability-premium/saas?topic=api-getting-started-cloudability-v3): base URLs, auth, pagination, sorting, filtering.
- [IBM Cloudability documentation](https://www.ibm.com/docs/en/cloudability-commercial): full docs for the Essentials, Standard, Premium and Federal editions.
- [Cloudability API endpoint reference](https://www.ibm.com/docs/en/cloudability-commercial/cloudability-premium/saas?topic=cloudability-api): index of every documented endpoint group.
- [Users end point](https://www.ibm.com/docs/en/cloudability-commercial/cloudability-premium/saas?topic=api-users-end-point): GET /v3/users, GET /v3/users/{userId}, PUT /v3/users/{userId}.
- [Anomaly detection end point](https://www.ibm.com/docs/en/cloudability-commercial/cloudability-premium/saas?topic=api-anomaly-detection-end-point): /v3/anomalies and /v3/anomaly-subscriptions.
- [FOCUS ingress end points](https://www.ibm.com/docs/en/cloudability-commercial/cloudability-premium/saas?topic=api-focus-ingress-end-points): /v3/vendors/byod/accounts.
- [Connect custom data (FOCUS ingress)](https://www.ibm.com/docs/en/cloudability-commercial/cloudability-essentials/saas?topic=cloudability-connect-custom-data-focus-ingress): FOCUS 1.0 and 1.1 manifest contract.

## Machine-readable artifacts

- [Cloudability Postman collection](https://raw.githubusercontent.com/IBM/Apptio-Tools/main/cloudability/postman-collection/Cloudability.postman_collection.json.example): first-party, Postman v2.1, rightsizing / anomalies / workload prediction / containers / business mappings / views.
- [Business Metrics Postman collection](https://raw.githubusercontent.com/IBM/Apptio-Tools/main/cloudability/postman-collection/Business%20Metrics.postman_collection.json): first-party, Postman v2.1.
- There is NO OpenAPI, Swagger, GraphQL, AsyncAPI, gRPC or WSDL contract. Probed 2026-09-05:
  /openapi.json, /openapi.yaml, /swagger.json, /api-docs and /docs on api.cloudability.com all
  return the same blanket 401.
- API Evangelist publishes a DERIVED entity-relationship model for this API at
  data-model/cloudability-data-model.yml in this repo. It is transcribed from IBM's own published
  object tables and the first-party Postman collections, not from a contract: six entities carry
  field lists, the rest are named with empty field lists rather than guessed.

## Surface size and known ambiguities

- IBM's API reference publishes 29 endpoint groups. Only a handful publish an object schema, so
  most of the surface is addressable but not describable.
- The same resource is published at two paths by two first-party sources: the docs say
  /v3/anomaly-subscriptions, IBM's own Postman collection says /v3/anomalies/subscriptions.
- The docs are not self-consistent on auth: getting-started says `Authorization: Basic <cldy_token>`
  while the Views end point page says "a valid bearer token". The 401 carries no WWW-Authenticate
  header, so neither can be confirmed without a credential.
- Business mappings are addressed by an `index` of 1-10 that is both the identifier and the
  evaluation order — writes are not local, and re-ordering restates historical showback.
- Field naming is inconsistent: /account_groups and account_group_entry_values are snake_case while
  views and mappings are camelCase; on the View object sharedWithUsers is array[string] and
  defaultUserIds is array[integer].

## First-party code

- [cloudability/metrics-agent](https://github.com/cloudability/metrics-agent) — Kubernetes metrics
  collection agent (Go, Apache-2.0). Helm chart 2.14.15, 2026-08-21.
  DEPRECATED: end of functionality 2026-11-19.
- [IBM FinOps Agent Helm chart](https://github.com/kubecost/finops-agent-chart) — the replacement.
  `helm repo add ibm-finops https://kubecost.github.io/finops-agent-chart`. Chart 1.0.25, 2026-08-07.
- [IBM/Apptio-Tools](https://github.com/IBM/Apptio-Tools) — Python automation scripts for account
  groups, business mappings and views, plus the Postman collections (Apache-2.0).
- [IBM/Apptio-Tools-Lib](https://github.com/IBM/Apptio-Tools-Lib) — Python helper library.
  Git-only: `pip install git+https://github.com/ibm/apptio-tools-lib.git`. No PyPI release, no tags.
- There is no first-party REST SDK for the v3 API. The npm, RubyGems and PyPI packages named
  "cloudability" are third-party and unmaintained.

## Operations, trust and status

- [Cloudability status](https://status.cloudability.com/) — Atlassian Statuspage; "API" is a named
  component per region. Machine-readable: https://status.cloudability.com/api/v2/summary.json
- [IBM Apptio status](https://status.apptio.com/) — platform-wide, 91 components.
- [Apptio Trusted Platform](https://www.apptio.com/company/trust/) — SOC 2 Type II, ISO 27001:2013,
  FedRAMP, CSA STAR Level One, GDPR, CCPA. Security contact infosec@apptio.com.
- [IBM PSIRT security.txt](https://www.ibm.com/.well-known/security.txt) — psirt@us.ibm.com and the
  HackerOne programme at https://hackerone.com/ibm.

## Agent surfaces

- No MCP server. IBM idea CLOUDY-I-1215 (created 2026-01-20, 19 votes) requests one and is marked
  "Planned for future release".
- No A2A agent card. /.well-known/agent-card.json and /.well-known/agent.json were probed on eight
  hosts on 2026-09-05 and none returned an AgentCard.
- No webhooks. Anomaly subscriptions deliver by email or PagerDuty only.

## Pricing

- No published pricing. https://www.apptio.com/products/cloudability/pricing/ redirects to a
  contact-sales form. API access is an entitlement of a Cloudability subscription, not a metered
  product.

## Broken links to avoid

- developers.cloudability.com and support.cloudability.com both 301 to help.apptio.com, which has
  no DNS record. Every deep link into the legacy Cloudability developer documentation is dead.
- https://www.ibm.com/products/cloudability 301s to the generic https://www.ibm.com/products index.