What this is

The CloudFix API lets you automate access to recommendations, reports, integrations, and administrative configuration for your CloudFix tenant.

Who this guide is for

• CloudFix admins who manage users, integrations, and settings
• Developers who want to pull recommendations and reports
• Partners or integration engineers who need webhooks or API tokens

Base URL

https://app.cloudfix.com/api/v3

Authentication

Most endpoints require an Authorization header. CloudFix accepts two kinds of token: API tokens, for automation, and sign-in tokens, issued when a user signs in.

Public endpoints (no auth required) are limited to login/registration, token refresh, and a small set of onboarding and marketplace flows. If an endpoint is public, it is explicitly listed in the technical summary.

API tokens (for automation)

API tokens start with cft_. Send a token in any of these forms:

• Authorization: api-token cft_<token>
• Authorization: Bearer cft_<token>
• Authorization: cft_<token>

Creating and managing API tokens:

• Tenant Admins create and revoke API tokens under Settings > API Tokens. The token value is shown only once, so copy it when you create it.
• Each token has a role: Reader, ResourceManager or RunbookManager. A token never gets more access than the user who created it.
• Each token has an expiry date. When you create a token through the API (POST /api/v3/tokens with a Tenant Admin sign-in token and a body such as {"name":"automation-token","role":"Reader","expiresInDays":90}), expiresInDays defaults to 90.
• A token stops working if the user who created it is deactivated or removed.

Sign-in tokens

POST /api/v3/auth/login returns an accessToken, a refreshToken and a tokenProvider. Send the access token prefixed with the token provider. For a username and password sign-in, that looks like this:

Authorization: cognito <accessToken>

Don't send a sign-in token with the Bearer scheme. CloudFix treats every Bearer value as an API token, so a sign-in token sent that way is refused with 403. Sign-in tokens expire; call POST /api/v3/auth/refresh with your username and refreshToken to get a new one.

Choose your auth method

Use an API token for automation. API tokens are limited to the Reader, ResourceManager and RunbookManager roles:

• Reader: list recommendations, the summary and summary filters, recommendation reports, share links, the recommendations export, and tenant details.
• ResourceManager: everything Reader can do, plus snoozing recommendations, marking them manually fixed, and executing fixes (POST /api/v3/create-change-requests).
• RunbookManager: everything ResourceManager can do, plus runbook approval.

Everything else requires a Tenant Admin sign-in token. That includes user management, API token management, webhooks and email integrations, settings (apart from reading excluded accounts), validations and analysis status, and the savings and cost-ranking reports.

Organizations with more than one tenant

Each API token belongs to one tenant: the tenant that was selected in the CloudFix UI when the token was created. By default, requests made with the token return that tenant's data, so a token created in the master tenant returns the master tenant's data. To read a child tenant through the API, create a separate token while that child tenant is selected, and send each request with the token for the tenant you want.

A token for a child tenant works only if the user who creates it also has a user account in that child tenant. A token created by a user who exists only in the master tenant is refused with 403 on every call.

Authorization and permissions

Access is role-based. Each API route maps to a permission set.

• 401 Unauthorized: the request has no Authorization header.
• 403 Forbidden: the request was refused. The token is invalid, expired or revoked; the user who created it is inactive or no longer exists in that tenant; or the token's role does not include that endpoint.

The report endpoints (savings, realized savings, savings history and cost ranking) currently require a Tenant Admin sign-in token, and API tokens receive 403 from them. With an API token, you can use GET /api/v3/recommendations/summary, which returns completedSavings and realizedSavings for each recommendation type, or the recommendations export described below.

Data persistence

• CloudFix stores configuration, recommendations, and reports server-side.
• Webhook and integration settings are persistent and remain active until updated or deleted.
• Token lifecycle and revocation are managed by the backend.
• Retention periods vary by plan and policy; contact CloudFix Support for retention details.

Not in scope for the API

These CloudFix UI features are not directly exposed as API endpoints:

• UI-only rendering and exports (charts, PDF exports, report layout)
• Viewer-only report presentation (the API returns data and share URLs; the UI controls the viewing experience)
• One-click UI execution controls beyond the API change-request and scheduling endpoints
• Client analytics and telemetry built into the UI

Common tasks by persona

Admin

Typical goals:

• Manage users
• Manage API tokens
• Configure integrations and webhooks
• Configure finders/fixers settings and excluded accounts

Relevant capabilities (these need a Tenant Admin sign-in token):

• Users: list, create, update, delete
• Tokens: create, list, revoke
• Integrations: email integrations and webhooks
• Settings: excluded accounts, finders configuration, execution schedules

Developer

Typical goals:

• Retrieve recommendations
• Pull summary views or reports
• Access savings and cost ranking reports

Relevant capabilities:

• Recommendations: list, summary, filters, report, export (API token with the Reader role or higher)
• Reports: savings, realized savings, savings history, cost ranking (Tenant Admin sign-in token; see Authorization and permissions above)
• Validations and analysis status (Tenant Admin sign-in token)

Partner or integration engineer

Typical goals:

• Register and manage webhooks
• Sync or maintain email integration config
• Use tokens for automation

Relevant capabilities:

• Webhooks: register, list, delete (Tenant Admin sign-in token)
• Email integrations: register, edit, delete, sync (Tenant Admin sign-in token)
• API tokens for reading and acting on recommendations

Walkthrough: get a token, list recommendations, and take action

This is a simple end-to-end flow you can follow in production.

1) Get an API token in the UI. A Tenant Admin creates it under Settings > API Tokens. Use it in the Authorization header as api-token <token>.

2) List recommendations. Call the recommendations endpoint to get individual recommendation IDs (see Listing recommendations: filters, paging and sorting below):

GET /api/v3/recommendations?pageNumber=1&pageLimit=50

3) Group recommendations. Use the summary endpoints to group by recommendation type and scope to OUs/accounts/regions/tags:

GET /api/v3/recommendations/summary

GET /api/v3/recommendations/summary-filters

4) Act on recommendations. Use IDs from the recommendations list to snooze, mark fixed, or create change requests (ResourceManager role or higher):

POST /api/v3/recommendations/postpone

POST /api/v3/recommendations/manual-fix

POST /api/v3/create-change-requests

5) View reports. Use the recommendation ID to fetch a report and optionally generate a share link:

GET /api/v3/recommendations/report?recommendationId=<id>

POST /api/v3/recommendations/share with JSON body {"recommendationId": "<id>"}

Listing recommendations: filters, paging and sorting

GET /api/v3/recommendations returns individual recommendations. All parameters are optional query-string parameters. To pass several values for a repeatable parameter, repeat it, for example region=us-east-1&region=eu-west-1. A comma-separated list in one parameter is treated as a single value (the exception is ids).

Parameter	What it does
status (repeatable)	Filters by status. See Status values below.
finderFixerId	Recommendation type, for example EbsDeleteOldVolumeSnapshots. It also matches recommendation types grouped under that type. The value must match exactly (it is case-sensitive).
account (repeatable)	AWS account ID.
ou (repeatable)	Organizational unit ID.
region (repeatable)	AWS Region, for example us-east-1.
tagKey, tagValue (repeatable, in pairs)	Resource tag filter. The first tagKey is paired with the first tagValue, and so on. A recommendation matches if its resource has any of the pairs. Values must match exactly.
resource	Text contained in the resource ID or resource name.
from, to	Creation date range in YYYY-MM-DD format. Send both; one on its own is ignored.
ids	Up to 100 recommendation IDs, comma-separated. These are returned with their parameters.
includeParameters	true or 1 to include each recommendation's parameters object. Without it, parameters is empty.
pageNumber, pageLimit, sortBy, sortOrder	See Paging and sorting below.

Status values

Write the status in lower case with underscores. Matching is not case-sensitive, and hyphens also work.

• Open: suggested, manual_approval, scheduled, in_progress
• Finished: completed, manually_fixed, failed, rejected
• No longer relevant: no_longer_applicable, resource_deleted, resource_fixed

Without a status parameter, the endpoint returns every status except Completed, Manually Fixed, Failed and Rejected. That default includes No Longer Applicable, Resource Deleted and Resource Fixed. To list only open recommendations, ask for them explicitly, for example status=suggested&status=manual_approval.

The filter matches the stored status. The status field in the response can show a different label: a Manual Approval recommendation is returned as Disabled when its fixer is not enabled for your tenant, and a Suggested or Manual Approval recommendation is returned as Needs Stack Upgrade when your deployed CloudFix stack must be updated before the fix can run.

Paging and sorting

• pageNumber starts at 1. Zero, negative and non-numeric values return 422. Without it, you get the first page.
• pageLimit sets the page size. The default is 500. No maximum is enforced, but a response larger than 6 MB fails and a request that runs longer than 30 seconds times out, so keep pages moderate, especially with includeParameters=true.
• The default order is most recently scheduled or updated first: by scheduledAt, or by updatedAt for recommendations with no scheduled date, descending, then by id.
• sortBy accepts annualSavings, annualCost, updatedAt or scheduledAt (case-sensitive; other values return 422). Recommendations with no value in that field are ordered by their updatedAt instead. sortOrder is asc or desc (default desc).
• The response has no total count or last-page marker. A page can hold fewer than pageLimit items even when later pages still have results, because some recommendations are filtered out after the page is read. Don't treat a short page as the end of the list.
• The default order uses timestamps that change when a recommendation is scheduled or updated, so a recommendation can move to another page while you are paging. If you need a single point-in-time file, use the export described under Exporting all recommendations as CSV, keeping in mind that it selects recommendations differently (see Why GET /recommendations and the export return different counts).

Response format

The response body is a JSON array of recommendation objects; it is not wrapped in another object. Useful fields include:

• id: the recommendation ID used by the action and report endpoints
• customerId: your tenant's numeric ID
• accountId, accountNickname, region, organizationalUnitName, ouId
• opportunityType: the recommendation type (the value finderFixerId filters on), and opportunityDescription: its display name
• resourceId, resourceName
• annualCost, annualSavings, actualSavings: left out for recommendation types that don't report savings
• status, createdAt, updatedAt, scheduledAt
• manualFix, and fixUnavailable, which is present only when CloudFix has no automated fix for that recommendation
• parameters: empty unless you use includeParameters or ids

Resource tags are not included in the response, although you can filter on them with tagKey and tagValue.

When the endpoint rejects a request (for example 422 for an invalid pageNumber), the response body is a plain-text message describing the problem. Authentication errors (401 and 403) return JSON such as {"message":"Forbidden"}.

Exporting all recommendations as CSV

The export produces the same CSV file as Reports > Recommendations Export in the CloudFix UI (see Reporting on Recommendations and Their Savings). Any API token or user that can list recommendations (Reader role or higher) can use it.

Preview and row count

GET /api/v3/recommendations/export takes the export filters as query-string parameters: statuses, accountIds, regions, finderTypes and categories (each repeatable), plus dateFrom and dateTo. It returns up to 100 rows in data, the number of rows the export would contain in totalCount, and the recommendation types you can filter on in availableFinders.

Download

curl -s -X POST "https://app.cloudfix.com/api/v3/recommendations/export/download" -H "Authorization: api-token cft_<token>" -H "Content-Type: application/json" -d '{"statuses":["Manual Approval","Suggested"],"accountIds":["123456789012"]}'

The response is {"downloadUrl":"..."}. Download the CSV from that URL within 15 minutes, after which the link expires.

All body fields are optional; leave a field out to include everything:

• statuses: status names exactly as they are displayed, for example "Manual Approval" (up to 50)
• accountIds: AWS account IDs (up to 500)
• regions: AWS Regions (up to 50)
• finderTypes: recommendation types, which also match types grouped under them (up to 200)
• categories: recommendation categories (up to 10)
• dateFrom, dateTo: creation date range in YYYY-MM-DD format, both inclusive. dateFrom can't be later than dateTo.

A body with any other field is rejected with 400.

What the export contains

• Only recommendations with annual savings greater than 0.
• No Longer Applicable recommendations are never included. With no statuses filter, every other status is included, finished ones too.
• One row per resource and recommendation type group. When a resource has several recommendations in the same group, the row with the highest annual savings is kept (or the most recently updated one, if savings are equal).
• Up to 50,000 rows. A larger export returns 400 with "Export exceeds the 50,000 row limit. Apply filters to narrow the results." Split it, for example by account, Region or date range. An export with no matching rows returns 400 with "No recommendations match the current filters".
• Rows are sorted by recommendation type name, then resource ID.

CSV columns: Account, Account Name, Region, Resource ID, Finder, Category, Status, Tags, Annual Cost, Annual Savings, Created Date, Updated Date, Completed Date, Fix Unavailable Reason.

• The Status column shows the stored status.
• The Tags column lists only tags whose key is Owner, AccountOwner, or L followed by digits (such as L4), as key=value pairs separated by semicolons.
• Text values that start with =, +, -, @ or a few other characters are prefixed with an apostrophe, so spreadsheet applications don't treat them as formulas.

Why GET /recommendations and the export return different counts

The two endpoints select recommendations differently, so their totals usually differ:

• Default statuses. Without a status filter, GET /recommendations leaves out Completed, Manually Fixed, Failed and Rejected but includes No Longer Applicable, Resource Deleted and Resource Fixed. The export, without a statuses filter, includes every status except No Longer Applicable.
• Savings. The export includes only recommendations with annual savings greater than 0. GET /recommendations includes all of them.
• Duplicates. The export keeps one row per resource and recommendation type group. GET /recommendations returns every recommendation, so the same resource can appear more than once.
• Recommendations the list leaves out. GET /recommendations leaves out recommendations from AWS accounts that are no longer onboarded in your tenant, recommendations of types your plan does not include, and open recommendations of types that are currently turned off or that your deployed CloudFix stack has no permissions for. The export does not apply these rules.
• Status labels. GET /recommendations can return a stored Manual Approval or Suggested recommendation as Disabled or Needs Stack Upgrade. The export shows the stored status.

To compare like with like, call the export preview (GET /api/v3/recommendations/export) with the same filters and read totalCount.

Making the summary useful

The recommendations summary is an aggregate view that groups findings by recommendation type. It is designed for prioritization and tracking, not for item-by-item actions.

How to use it effectively:

• Prioritize by potentialSavings and resourcesTotal to decide which recommendation types to tackle first.
• Use categoryTypeName and supportsAutoFix to separate quick wins from maintenance-window work.
• Track progress over time with completedSavings and realizedSavings.
• Use subCategoryTypeName and subCategoryTypeDescription as the human-friendly identifier for each recommendation type.

Using summary filters

The summary filters endpoint provides the allowed filter values (organizational units, accounts, regions, and tags) for your tenant. Use these values to build precise summary queries, for example:

• Filter the summary to a single OU or account to focus on one business unit.
• Filter by region or tag to align with cost-center or environment-specific reporting.

From summary to a single recommendation

The summary does not include recommendation IDs by design. To retrieve individual recommendations, use the recommendations list endpoint with filters:

• Use the recommendation type from summary (subCategoryTypeName) with the /recommendations finderFixerId filter to get concrete recommendation IDs.
• If you need to scope to an account, use account=<accountId> (ou=, region=, tagKey=, and tagValue= are also supported).
• Then use those IDs for actions like report retrieval, manual fixes, or change requests.