Public API data formats
How the Costfluent Public API writes money, dates, currencies and IDs, and how a write is made conditional on the version you read.
The OpenAPI document declares each field's format. This page explains the ones an integration has to handle with care.
Money
Every amount of money is a decimal string, never a JSON number, so no client sums binary floats that drift:
Code
- Responses write every amount with exactly eight decimals, a point and no exponent.
- Requests send an amount the same way, with up to eight decimals:
"1250.5"and"1250.50000000"are the same amount. A JSON number, an exponent or a thousands separator is refused with400. - A budget amount is kept to the cent, so a budget amount with more than two decimals is refused rather than rounded.
- Compare amounts by value, not as text:
"49"and"49.00000000"are equal. - Percentages, ratios such as allocation coverage, exchange rates and usage quantities stay JSON numbers.
- A cost alert's
thresholdValueis a decimal string whether it is an amount or a percentage, as itsthresholdTypesays.
Dates and months
- A date is
YYYY-MM-DD, such asstartDate,endDateand a custom integration'schargePeriodStart. A charge period is a day, so a time is refused. - A forecast month is
YYYY-MM. - A timestamp, such as
createdAt, is an ISO 8601 date and time.
Currencies
A currency is an upper-case three-letter ISO 4217 code, such as EUR or GBP.
IDs
Every Costfluent object is addressed by a prefixed ID, such as wsp_ for a workspace, bud_ for a budget, crp_ for a cost report, seg_ for a segment and prv_ for an integration. The prefix says what the ID names, and the API refuses an ID of the wrong kind. Treat the rest as opaque.
A batch of costs sent to a custom integration answers with a batchId beginning with cbt_: a receipt for that batch, not an upload you can read back.
Conditional updates
A budget read answers with an ETag header, the version of the budget it returned. Send it back as If-Match on the PUT that changes the budget:
Code
When someone changed the budget after your read, the PUT is refused with 412 and precondition_failed, and nothing changes: read it again, then decide. Without If-Match, the last write wins.
How it behaves
- The create and the update of a budget answer with its new
ETagtoo. If-Match: *applies the update whatever the version.- The Terraform provider sends the
ETagof its last read, so an edit made in Costfluent between a plan and its apply stops the apply instead of being overwritten.