Views End Point

Summary

The Views API end point can be used for all key tasks as it pertains to managing Cloudability Views . Cloudability Views allow our customers to give each and every user a unique view or set of views of your cloud spend and usage. It also supports limiting the scope of what is visible to individual users.

This document defines all CRUD APIs for Views in Cloudability.
Each API endpoint enables creating, reading, updating, or deleting user views and retrieving all views for a given user.
All endpoints return data using a unified View Object Schema.
isPrivate and sharedWithOrganization cannot both be true.
The end point does not support filtering and sorting.

End Point Particulars

Base URL

https://api.cloudability.com/v3

Authentication

All endpoints require a valid bearer token.

Header	Required	Description
Authorization	✅	Bearer token for authentication
Content-Type	✅	application/json

API Endpoints

Operation	Method	Endpoint
Create a View	POST	/views
Get Details of a View	GET	/views/{viewId}
Get All Views for a User	GET	/views
Update a View	PUT	/views/{viewId}
Delete a View	DELETE	/views/{viewId}

Common Objects:

View Object Schema

This object is returned by multiple endpoints such as Create, Get Details, List, and Update View.

Field	Type	Description
id	integer	Unique identifier of the view
title	string	Title or name of the view
isPrivate	boolean	Whether the view is private
sharedWithOrganization	boolean	Whether the view is shared organization-wide
authorId	integer	ID of the user who created the view
editable	boolean	Whether the current user can modify this view
deletable	boolean	Whether the current user can delete this view
viewSource	string	Origin of the view (SYSTEM, USER, etc.)
viewSourceId	integer / null	ID referencing the source if applicable
parentViewId	integer	ID of the parent view (if derived)
mappedViewIds	array[integer]	IDs of related or mapped views
sharedUserIds	array[integer]	User IDs this view is shared with
derivedUserIds	array[integer]	Derived user access IDs
sharedOrgUnitIDs	array[integer]	Organization unit IDs this view is shared with
derivedOrgUnitIDs	array[integer]	Derived organization unit IDs
email	string	Optional email metadata
description	string	Description of the view
defaultUserIds	array[integer]	Default user IDs with access
filters	array[Filter Object]	Filters applied to the view
filterStrings	array[string]	Human-readable representation of filters
tagFilters	array[Tag Filter Object]	Tag-based filters applied to the view

Filter Object

Field	Type	Description
label	string	Display label of the filter
field	string	Field name used for filtering
comparator	string	Operator used for comparison (==, =@, etc.)
value	string	Value used in filter condition
stringValue	string	Combined representation (field==value)
accountGroupFilter	boolean	True if filter applies to account groups
vendorFilter	boolean	True if filter applies to vendors
tagFilter	boolean	True if filter applies to tags

Tag Filter Object

Field	Type	Description
field	string	Tag field name
comparator	string	Operator used for tag comparison (=@)
value	string	Tag value to match
stringValue	string	String representation of tag filter
tagFilter	boolean	Always true for tag-based filters

Create a View

Endpoint

POST /views

Description

Creates a new view and returns the created View object.

Request Body

Field	Type	Required	Description
userId	integer	✅	ID of the user creating the view
orgId	integer	✅	Organization ID
title	string	✅	Title of the new view
filters	array[Filter Object]	✅	List of filters applied
ownerId	integer	❌	Owner of the view
description	string	❌	description of the view.
isPrivate	boolean	❌	Whether the view is private
sharedWithOrganization	boolean	❌	Whether shared organization-wide
sharedWithUsers	array[integer]	❌	User IDs the view is shared with
viewSource	string	❌	Source of view (SYSTEM, BUSINESS_MAPPING). The default will be SYSTEM. viewSource BUSINESS_MAPPING will be used for creation of hierarchical views.
parentViewId	integer	❌	ID of the parent view. Used for hierarchical views.
sharedOrgUnitIDs	array[integer]	❌	IDs of User Groups/ Entra ID groups.

Example Request (Create a view shared with Organization)

POST your JSON payload to the /views end point with the sharedWithOrganization attribute set to true . You should leave the sharedUserIds attribute empty.

curl -X POST https://api.cloudability.com/v3/views \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <auth_token>" \
  -d @- <<EOF
{
  "userId": 21896,
  "orgId": 4857,
  "title": "Regional Cost Report",
  "filters": [
    {
      "label": "Region",
      "field": "group_name5",
      "comparator": "==",
      "value": "US-East-1"
    }
  ],
  "ownerId": 21896,
  "isPrivate": false,
  "sharedWithOrganization": true,
  "sharedWithUsers": [],
  "viewSource": "SYSTEM",
  "viewSourceId": 0,
  "parentViewId": 0,
  "sharedOrgUnitIDs": []
}
EOF

Example Response

Returns a single view Object.

{
  "id": 123,
  "isPrivate": false,
  "sharedWithOrganization": false,
  "authorId": <authorId>,
  "title": "Test View",
  "editable": true,
  "deletable": true,
  "viewSource": "SYSTEM",
  "viewSourceId": null,
  "parentViewId": 0,
  "mappedViewIds": [],
  "sharedUserIds": [],
  "derivedUserIds": [],
  "sharedOrgUnitIDs": [],
  "derivedOrgUnitIDs": [],
  "email": "",
  "description": "",
  "defaultUserIds": [],
  "filters": [
    {
      "field": "tag9",
      "comparator": "=@",
      "value": "chime-production",
      "collectionFilter": false,
      "accountGroupNotSetFilter": false,
      "intersectionFilter": false,
      "accountIdFilter": false,
      "accountNameFilter": false,
      "accountGroupFilter": false,
      "vendorFilter": false,
      "tagFilter": true,
      "stringValue": "tag9=@chime-production"
    }
  ],
  "filterStrings": ["tag9=@chime-production"],
  "tagFilters": [
    {
      "field": "tag9",
      "comparator": "=@",
      "value": "chime-production",
      "collectionFilter": false,
      "accountGroupNotSetFilter": false,
      "intersectionFilter": false,
      "accountIdFilter": false,
      "accountNameFilter": false,
      "accountGroupFilter": false,
      "vendorFilter": false,
      "tagFilter": true,
      "stringValue": "tag9=@chime-production"
    }
  ]
}

Example Request (Create a view shared with specific Users)

POST your JSON payload to the /views end point with your sharedWithUsers attribute containing a list of userIDs the view is to be shared with. The sharedWithOrganization attribute should be set to false .

curl -X POST https://api.cloudability.com/v3/views \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <auth_token>" \
  -d @- <<EOF
{
  "userId": 21896,
  "orgId": 4857,
  "title": "Regional Cost Report",
  "filters": [
    {
      "label": "Region",
      "field": "group_name5",
      "comparator": "==",
      "value": "US-East-1"
    }
  ],
  "ownerId": 21896,
  "isPrivate": false,
  "sharedWithOrganization": false,
  "sharedWithUsers": [
  "0000",
  "1111"
  ],
  "viewSource": "SYSTEM",
  "viewSourceId": 0,
  "parentViewId": 0,
  "sharedOrgUnitIDs": []
}
EOF

Get Details of a View

Endpoint

GET /views/{viewId}?userId={userId}&orgId={orgId}

Description

Retrieves detailed information for a specific view.

Path & Query Parameters

Parameter	Type	Required	Description
viewId	integer	✅	Unique ID of the view
userId	integer	✅	ID of requesting user
orgId	integer	✅	Organization ID

Example Request

curl https://api.cloudability.com/v3/views/{viewId}?userId={userId}&orgId={orgId} \
  -H "Authorization: Bearer <auth_token>"

Example Response

{
  "id": 123,
  "isPrivate": false,
  "sharedWithOrganization": false,
  "authorId": <authorId>,
  "title": "Test View",
  "editable": true,
  "deletable": true,
  "viewSource": "SYSTEM",
  "viewSourceId": null,
  "parentViewId": 0,
  "mappedViewIds": [],
  "sharedUserIds": [],
  "derivedUserIds": [],
  "sharedOrgUnitIDs": [],
  "derivedOrgUnitIDs": [],
  "email": "",
  "description": "",
  "defaultUserIds": [],
  "filters": [
    {
      "field": "tag9",
      "comparator": "=@",
      "value": "chime-production",
      "collectionFilter": false,
      "accountGroupNotSetFilter": false,
      "intersectionFilter": false,
      "accountIdFilter": false,
      "accountNameFilter": false,
      "accountGroupFilter": false,
      "vendorFilter": false,
      "tagFilter": true,
      "stringValue": "tag9=@chime-production"
    }
  ],
  "filterStrings": ["tag9=@chime-production"],
  "tagFilters": [
    {
      "field": "tag9",
      "comparator": "=@",
      "value": "chime-production",
      "collectionFilter": false,
      "accountGroupNotSetFilter": false,
      "intersectionFilter": false,
      "accountIdFilter": false,
      "accountNameFilter": false,
      "accountGroupFilter": false,
      "vendorFilter": false,
      "tagFilter": true,
      "stringValue": "tag9=@chime-production"
    }
  ]

Getting List of Views for a User

Endpoint

GET /views?userId={userId}&orgId={orgId}

Description

Retrieves all views accessible to the specified user. If user is an admin of the org then all the views of the org will be returned by the API (except the private views).

Query Parameters

Parameter	Type	Required	Description
userId	integer	✅	User ID
orgId	integer	✅	Organization ID

Example Request

curl https://api.cloudability.com/v3/views?userId={userId}&orgId={orgId} \
  -H "Authorization: Bearer <auth_token>"

Example Response: Returns an array of View Object.

[
  {
  "id": 123,
  "isPrivate": false,
  "sharedWithOrganization": false,
  "authorId": <authorId>,
  "title": "Test View",
  "editable": true,
  "deletable": true,
  "viewSource": "SYSTEM",
  "viewSourceId": null,
  "parentViewId": 0,
  "mappedViewIds": [],
  "sharedUserIds": [],
  "derivedUserIds": [],
  "sharedOrgUnitIDs": [],
  "derivedOrgUnitIDs": [],
  "email": "",
  "description": "",
  "defaultUserIds": [],
  "filters": [
    {
      "field": "tag9",
      "comparator": "=@",
      "value": "chime-production",
      "collectionFilter": false,
      "accountGroupNotSetFilter": false,
      "intersectionFilter": false,
      "accountIdFilter": false,
      "accountNameFilter": false,
      "accountGroupFilter": false,
      "vendorFilter": false,
      "tagFilter": true,
      "stringValue": "tag9=@chime-production"
    }
  ],
  "filterStrings": ["tag9=@chime-production"],
  "tagFilters": [
    {
      "field": "tag9",
      "comparator": "=@",
      "value": "chime-production",
      "collectionFilter": false,
      "accountGroupNotSetFilter": false,
      "intersectionFilter": false,
      "accountIdFilter": false,
      "accountNameFilter": false,
      "accountGroupFilter": false,
      "vendorFilter": false,
      "tagFilter": true,
      "stringValue": "tag9=@chime-production"
    }
  ]
}
]

Update a View

Endpoint

PUT /views/{viewId}?userId={userId}&orgId={orgId}

Description

Updates details of an existing view..

Example Request

curl -X PUT https://api.cloudability.com/v3/views/{viewId}?userId={userId}&orgId={orgId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <auth_token>" \
  -d @- <<EOF
{
  "userId": {userId},
  "orgId": {orgId},
  "title": "Regional Cost Report",
  "filters": [
    {
      "label": "Region",
      "field": "group_name5",
      "comparator": "==",
      "value": "US-East-1"
    }
  ],
  "isPrivate": false,
  "sharedWithOrganization": true,
  "sharedWithUsers": [],
  "viewSource": "SYSTEM",
  "viewSourceId": 0,
  "parentViewId": 0,
  "sharedOrgUnitIDs": []
}
EOF

Example Response

{
  "id": 1001,
  "title": "Regional Cost Report - Updated",
  "sharedWithOrganization": false
}

Delete a View

Endpoint

DELETE /views/{viewId}?userId={userId}&orgId={orgId}

Description

Deletes a view permanently.

Example Request

curl -X DELETE https://api.cloudability.com/v3/views/{viewId}?userId={userId}&orgId={orgId} \
  -H "Authorization: Bearer <auth_token>"

Example Response

{
   "deletedViewIds": [1001] 
}

Error Responses for View APIs

Status Code	Meaning	Example Message
400	Bad Request	Invalid or missing parameters
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	User not permitted to perform this action
404	Not Found	View not found
409	Conflict	View with the same title already exists
500	Internal Server Error	Unexpected system error

Special Note About Filters

Views are based on creating filters around Accounts , Account Groups or Tags . You can have multiple filters for any view.

The supported operators are:

!=@, =@, !=, ==, >=, <=, >, <

So for example to create a filter set for your first *account group * equals 'Production" AND tag number 5 contains 'farm' you'd have:

"filters": [
        {
          "label": "Env",
          "field": "group_name1",
          "comparator": "==",
          "value": "Production"
        },
        {
          "label": "Project Tag",
          "field": "tag5",
          "comparator": "=@",
          "value": "farm"
        }
      ]

Example Sequence - Add New View; Create New User Defaulted to View

Follow section above to create your view. This will return a view id which you can assign to any user as their default view. You can also get this id from your view list .

Now create a new user (or update a previous one) and include the view id in the default_dimension_filter_set_id attribute

curl -X POST https://app.cloudability.com/v3/users?auth_token=[auth_token] \\
     -H "Content-Type: application/json" \\
     -d @- << EOF
{
  "user": {
    "full_name": "John Doe",
    "role": "User",
    "restricted": false,
    "email": "john_doe@example.com",
    "default_dimension_filter_set_id": [view_id],
    "new_shared_dimension_filter_set_ids": []
  }
}
EOF