Annotations

List annotations

GET

https://api.costfluent.com

/v1/annotations

Bearer (API token)

Returns the workspace's annotations by date, open ones unless includeResolved is set. An unknown costReportId answers 404.

Needs a token with viewCostReports on the workspace.

List annotations › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

costReportId

startDate

string | null · date

endDate

string | null · date

includeResolved

boolean

Default: false

page

integer · int32

The page to return, counted from 1. A page below 1 reads page 1; one past the last returns no items.

Default: 1

limit

integer · int32

Items per page, from 1 to 100. A larger value is clamped to 100, a smaller one to 1.

Default: 20

List annotations › Responses

Success

PaginatedResponseOfAnnotationResponse

PaginationLinks · required

AnnotationResponse[] · required

GET/v1/annotations

curl 'https://api.costfluent.com/v1/annotations?workspaceId=<string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "links": {
    "self": "self",
    "first": "first",
    "prev": "prev",
    "next": "next",
    "last": "last"
  },
  "data": [
    {
      "id": "id",
      "date": "2024-08-25",
      "source": "source",
      "text": "text",
      "costReportIds": [
        "string"
      ],
      "budgetId": "string",
      "costAlertId": "string",
      "sourceName": "sourceName",
      "thresholdPercent": 0,
      "thresholdBasis": "string",
      "createdByUserId": "string",
      "resolvedAt": "2024-08-25T15:00:00Z",
      "resolvedByUserId": "string",
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

Create annotation

POST

https://api.costfluent.com

/v1/annotations

Bearer (API token)

Pins a dated note to one to ten of the workspace's cost reports. A cost report that is not one of the workspace's answers 404 naming it.

Needs a token with updateCostReport on the workspace.

Create annotation › Headers

Idempotency-Key

string · minLength: 1 · maxLength: 255

A unique value, at most 255 printable ASCII characters, such as a UUID, that makes retrying this create safe. A retry with the same key and the same request within 24 hours answers the first response again, marked Idempotent-Replayed: true, and creates nothing; the same key with another request answers 422 idempotency_key_reused. A key is kept only for a create that succeeded. Without it, every request creates.

Create annotation › Request Body

CreateAnnotationRequest

workspaceId

WorkspacePublicId · minLength: 1 · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

date

string · date · required

text

string · minLength: 1 · required

costReportIds

CostReportPublicId[] · minLength: 1 · required

Create annotation › Responses

Created

AnnotationResponse

id

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

date

string · date · required

source

AnnotationSource · required

costReportIds

CostReportPublicId[] · required

createdAt

string · date-time · required

text

string | null

sourceName

string | null

thresholdPercent

integer | null · int32

resolvedAt

string | null · date-time

updatedAt

string | null · date-time

POST/v1/annotations

curl https://api.costfluent.com/v1/annotations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "workspaceId": "workspaceId",
  "date": "2024-08-25",
  "text": "text",
  "costReportIds": [
    "string"
  ]
}'

Example Request Body

{
  "workspaceId": "workspaceId",
  "date": "2024-08-25",
  "text": "text",
  "costReportIds": [
    "string"
  ]
}

json

Example Responses

{
  "id": "id",
  "date": "2024-08-25",
  "source": "source",
  "text": "text",
  "costReportIds": [
    "string"
  ],
  "budgetId": "string",
  "costAlertId": "string",
  "sourceName": "sourceName",
  "thresholdPercent": 0,
  "thresholdBasis": "string",
  "createdByUserId": "string",
  "resolvedAt": "2024-08-25T15:00:00Z",
  "resolvedByUserId": "string",
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Get annotation

GET

https://api.costfluent.com

/v1/annotations/{annotationId}

Bearer (API token)

Returns an annotation of the workspace. One whose every cost report is deleted answers 404.

Needs a token with viewCostReports on the workspace.

Get annotation › path Parameters

annotationId

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

Get annotation › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Get annotation › Responses

Success

AnnotationResponse

id

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

date

string · date · required

source

AnnotationSource · required

costReportIds

CostReportPublicId[] · required

createdAt

string · date-time · required

text

string | null

sourceName

string | null

thresholdPercent

integer | null · int32

resolvedAt

string | null · date-time

updatedAt

string | null · date-time

Update annotation

PUT

https://api.costfluent.com

/v1/annotations/{annotationId}

Bearer (API token)

Replaces a note whole: its date, its text and its cost reports, a report left out no longer being annotated. A budget's or cost alert's annotation records what fired and is not edited.

Needs a token with updateCostReport on the workspace.

Update annotation › path Parameters

annotationId

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

Update annotation › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Update annotation › Headers

If-Match

string

Applies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.

Update annotation › Request Body

UpdateAnnotationRequest

date

string · date · required

text

string · minLength: 1 · required

costReportIds

CostReportPublicId[] · minLength: 1 · required

Update annotation › Responses

Success

AnnotationResponse

id

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

date

string · date · required

source

AnnotationSource · required

costReportIds

CostReportPublicId[] · required

createdAt

string · date-time · required

text

string | null

sourceName

string | null

thresholdPercent

integer | null · int32

resolvedAt

string | null · date-time

updatedAt

string | null · date-time

PUT/v1/annotations/{annotationId}

curl 'https://api.costfluent.com/v1/annotations/:annotationId?workspaceId=<string>' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "date": "2024-08-25",
  "text": "text",
  "costReportIds": [
    "string"
  ]
}'

Example Request Body

{
  "date": "2024-08-25",
  "text": "text",
  "costReportIds": [
    "string"
  ]
}

json

Example Responses

{
  "id": "id",
  "date": "2024-08-25",
  "source": "source",
  "text": "text",
  "costReportIds": [
    "string"
  ],
  "budgetId": "string",
  "costAlertId": "string",
  "sourceName": "sourceName",
  "thresholdPercent": 0,
  "thresholdBasis": "string",
  "createdByUserId": "string",
  "resolvedAt": "2024-08-25T15:00:00Z",
  "resolvedByUserId": "string",
  "createdAt": "2024-08-25T15:00:00Z",
  "updatedAt": "2024-08-25T15:00:00Z"
}

json

application/json

Delete annotation

DELETE

https://api.costfluent.com

/v1/annotations/{annotationId}

Bearer (API token)

Deletes an annotation, a budget's or cost alert's included; the cost reports it stood on stay.

Needs a token with updateCostReport on the workspace.

Delete annotation › path Parameters

annotationId

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

Delete annotation › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Delete annotation › Headers

If-Match

string

Applies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.

Delete annotation › Responses

No Content

No data returned

Reopen annotation

POST

https://api.costfluent.com

/v1/annotations/{annotationId}/reopen

Bearer (API token)

Shows a resolved annotation in the default list again. An open one is returned as it is.

Needs a token with updateCostReport on the workspace.

Reopen annotation › path Parameters

annotationId

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

Reopen annotation › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Reopen annotation › Headers

If-Match

string

Applies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.

Reopen annotation › Responses

Success

AnnotationResponse

id

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

date

string · date · required

source

AnnotationSource · required

costReportIds

CostReportPublicId[] · required

createdAt

string · date-time · required

text

string | null

sourceName

string | null

thresholdPercent

integer | null · int32

resolvedAt

string | null · date-time

updatedAt

string | null · date-time

Resolve annotation

POST

https://api.costfluent.com

/v1/annotations/{annotationId}/resolve

Bearer (API token)

Hides an annotation from the default list. One already resolved is returned as it is.

Needs a token with updateCostReport on the workspace.

Resolve annotation › path Parameters

annotationId

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

Resolve annotation › query Parameters

workspaceId

WorkspacePublicId · pattern: ^wsp_[A-Za-z0-9_-]{2… · required

Resolve annotation › Headers

If-Match

string

Applies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.

Resolve annotation › Responses

Success

AnnotationResponse

id

AnnotationPublicId · pattern: ^ann_[A-Za-z0-9_-]{2… · required

date

string · date · required

source

AnnotationSource · required

costReportIds

CostReportPublicId[] · required

createdAt

string · date-time · required

text

string | null

sourceName

string | null

thresholdPercent

integer | null · int32

resolvedAt

string | null · date-time

updatedAt

string | null · date-time

Anomalies Allocation