GITBOOK-9: API docs refresh – Aug 2023 – 2

ilia-semenov · gitbook-bot · commit 2b52752670be · 2023-08-22T05:43:29.000Z
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 ## Welcome to Cloudthread Developer API
 
-Welcome to Cloudthread Developer API! Here you'll find all the documentation you need to get up and running with the cloud cost management API.
+Welcome to Cloudthread **Developer API**! Here you'll find all the documentation you need to get up and running with the cloud cost management API.
 
 ## Want to check it out?
 
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -9,6 +9,7 @@
   * [Events Overlay Ingestion](reference/api-reference/events.md)
   * [Tag Catalog Fetch](reference/api-reference/tag\_catalog.md)
   * [Metric Fetch](reference/api-reference/metrics.md)
-  * [Teams](reference/api-reference/teams.md)
   * [Users](reference/api-reference/users.md)
-  * [Savings Hub](reference/api-reference/savings-hub.md)
+  * [Teams](reference/api-reference/teams.md)
+  * [Savings Hub](reference/api-reference/savings-hub/README.md)
+    * [Opportunities Explorer](reference/api-reference/savings-hub/opportunities-explorer.md)
diff --git a/reference/api-reference/README.md b/reference/api-reference/README.md
@@ -1,64 +1,74 @@
 # API Reference
 
-Cloudthread provides a powerful and flexible REST Developer API to help you get the most out of your data.
+Cloudthread provides a powerful and flexible **REST Developer API** to help you get the most out of your data.
 
-This page shows how to use the API, and what features are currently available.
+These docs show how to use the API, and what features are currently available.
+
+{% hint style="info" %}
+**Good to know:** All the API methods referenced in the docs are synced to a Swagger file URL (**OpenAPI v3**) and are kept up to date **automatically** with changes to the API.
+{% endhint %}
 
 ## Basic setup
 
-Cloudthread's Developer API lives at
+Cloudthread's **Developer API** lives at:
+
+{% embed url="https://api.cloudthread.io" fullWidth="false" %}
 
-`https://api.cloudthread.io`
+{% hint style="warning" %}
+Cloudthread requires an **API Token** to process incoming developer API requests.&#x20;
 
-Cloudthread requires an API Token to process incoming developer API requests. Admin's have the ability to generate API Tokens on the Cloudthread platform within the **Settings** tab.
+Admin's have the ability to generate API Tokens on the Cloudthread platform within the [Settings](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings "mention") tab.
+{% endhint %}
 
 This API Token should be included in the headers for all Developer API requests as follows:
 
 `x-api-key: {API_TOKEN}`
 
-Any request without a valid token will be rejected.
+{% hint style="danger" %}
+Any request without a valid token will be **rejected**.
+{% endhint %}
 
-## Custom Data Ingestion
+## Custom Data ingestion
 
 Cloudthread provides the ability to send custom data to our systems that can then be used in your Cost Views and Unit Metrics.
 
-In order to send custom data, you must provision a **Custom Data - Data Stream Token** on the Cloudthread platform within the **Settings** tab.
+In order to send custom data, you must provision a **Custom Data - Data Stream Token** on the Cloudthread platform within the [Settings](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings "mention") tab.
 
 {% content-ref url="custom_data.md" %}
 [custom\_data.md](custom\_data.md)
 {% endcontent-ref %}
 
-Data sent via this API will appear in **Costs Overview** and **Unit Metrics Lab** on Cloudthread's platform.
+Data sent via this API will appear in [Costs Overview](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/costs-overview "mention") and [Unit Metrics Lab](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/unit-metrics-lab "mention") on Cloudthread's platform.
 
-## Event Overlay Ingestion
+## Event Overlay ingestion
 
-Cloudthread provides the ability to send webhook Events that can be overlayed on top of your Cost Views and Unit Metrics.
+Cloudthread provides the ability to send **webhook** **events** that can be overlayed on top of your [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view "mention") and [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric "mention"). See [Events Overlay](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/events-overlay "mention") for more details.
 
 {% content-ref url="events.md" %}
 [events.md](events.md)
 {% endcontent-ref %}
 
-Data sent via this API will appear in **Costs Overview** and **Unit Metrics Lab** on Cloudthread's platform.
+Data sent via this API will appear in [Costs Overview](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/costs-overview "mention") and [Unit Metrics Lab](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/unit-metrics-lab "mention") on Cloudthread's platform.
 
-## Tag Catalog Fetch
+## Tag Catalog fetch
 
-Cloudthread provides the ability to fetch a Tag Catalog entry via catalog key.
+Cloudthread provides the ability to fetch a [Tags Catalog](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/tag-assistant/tag-catalogs "mention") entry via catalog key.
 
 {% content-ref url="tag_catalog.md" %}
 [tag\_catalog.md](tag\_catalog.md)
 {% endcontent-ref %}
 
-## Cost View and Unit Metric Data Fetch
+## Cost View and Unit Metric Data fetch
 
-Cloudthread provides the ability to fetch a Cost View and Unit Metric data.
+Cloudthread provides the ability to fetch [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view "mention") and [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric "mention") data.
 
 {% content-ref url="metrics.md" %}
 [metrics.md](metrics.md)
 {% endcontent-ref %}
 
 ## Users and Teams setup
 
-API can be used to set up Users and Teams.
+API can be used to set up and change **Users** (see [User Management](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings/account-and-team-management "mention")) and [Teams](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings/teams "mention").
 
 {% content-ref url="users.md" %}
 [users.md](users.md)
@@ -67,3 +77,11 @@ API can be used to set up Users and Teams.
 {% content-ref url="teams.md" %}
 [teams.md](teams.md)
 {% endcontent-ref %}
+
+## Savings Hub manipulation
+
+API to retrive and setup [Savings Opportunities](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-savings/key-concepts/optimization-opportunities "mention") and [Savings Threads](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-savings/key-concepts/savings-threads "mention").
+
+{% content-ref url="savings-hub/" %}
+[savings-hub](savings-hub/)
+{% endcontent-ref %}
diff --git a/reference/api-reference/custom_data.md b/reference/api-reference/custom_data.md
@@ -1,14 +1,18 @@
 # Data Ingestion
 
-Cloudthread can process custom data for generating Cost Views and Unit Metrics.
+Cloudthread can process custom data for generating [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view "mention") and [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric "mention").
 
-In order to send custom data, you must provision a **Custom Data - Data Stream Token** on the Cloudthread platform within the **Settings** tab.
+In order to send custom data, you must provision a **Custom Data - Data Stream Token** on the Cloudthread platform within the [Settings](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings "mention") tab.
+
+{% hint style="info" %}
+See more in [Ingesting Custom Data](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/guides/monitoring-cloud-costs/ingesting-custom-data "mention") guide.
+{% endhint %}
 
 {% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/streams/ingest" method="post" %}
 [https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
 {% endswagger %}
 
-To send custom data to Cloudthread, use the endpoint above with the provisioned Data Stream Token and the following payload
+To send custom data to Cloudthread, use the endpoint above with the provisioned **Data Stream Token** and the following payload:
 
 ```json
 {
@@ -35,10 +39,10 @@ To send custom data to Cloudthread, use the endpoint above with the provisioned
 * `mertic_value`: float convertiable value of the metric.
 * `custom_dimensions`: map of **up to 10** key value pairs that you will be able to segment the data by on the Cloudthread platform.
 
-If the data pass validation and successfully save you'll receive a `201` status code.
-
-Cloudthread creates a record ID for each data point by hashing the metric name, metric aggreation function, and the custom dimensions into a single key. To update a data point that's already been sent, the incoming data point must match along these fields -- otherwise a new data point will be generated. You can then update a given timestamp and metric value pair by sending in the matching timestamp with a new metric value.
-
-{% hint style="info" %}
-**Good to know:** All the methods shown below are synced to an example Swagger file URL and are kept up to date automatically with changes to the API.
+{% hint style="success" %}
+If the data pass **validation** and successfully save you'll receive a `201` status code.
 {% endhint %}
+
+* Cloudthread creates a record ID for each data point by hashing the metric name, metric aggregation function, and the custom dimensions into a single key.
+* To update a data point that's already been sent, the incoming data point must match along these fields -- otherwise a new data point will be generated.
+* You can then update a given timestamp and metric value pair by sending in the matching timestamp with a new metric value.
diff --git a/reference/api-reference/events.md b/reference/api-reference/events.md
@@ -2,13 +2,13 @@
 
 ## Event Overlay Ingestion
 
-Cloudthread can process webhook events that can be overlayed on top of your Cost Views and Unit Metrics.
+Cloudthread can process **webhook events** that can be overlayed on top of your [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view "mention") and [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric "mention").
 
 {% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/events" method="post" %}
 [https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
 {% endswagger %}
 
-To send events data to Cloudthread, use the endpoint above and the following payload
+To send events data to Cloudthread, use the endpoint above and the following payload:
 
 ```json
 {
@@ -28,15 +28,13 @@ To send events data to Cloudthread, use the endpoint above and the following pay
 ```
 
 * `timestamp`: datetime with **hourly** granularity. Any timestamp with minutes, seconds, etc. will be rejected. E.g. `'2022-10-01 00:00:00'`. To send daily data, send data with the timepart = `00:00:00`.
-* `team_id`: OPITIONAL - integer ID of the team for which the event is tied. If this value is set, only users on this team (and admins) will be able to see this event on the platform. Invalid team IDs will be rejected.
+* `team_id`: OPITIONAL – integer ID of the team for which the event is tied. If this value is set, only users on this team (and admins) will be able to see this event on the platform. Invalid team IDs will be rejected.
 * `decscription`: text describing event.
-* `type`: event type to help organize and filter events on the platform - please ensure types are consistent across events to create easy filtering.
-* `event_url`: OPTIONAL - link to get more information about the sent event.
+* `type`: event type to help organize and filter events on the platform – please ensure types are consistent across events to create easy filtering.
+* `event_url`: OPTIONAL – link to get more information about the sent event.
 
-If the data pass validation and successfully save you'll receive a `201` status code.
-
-Data sent via this API will appear in **Costs Overview** and **Unit Metrics Lab** on Cloudthread's platform.
-
-{% hint style="info" %}
-**Good to know:** All the methods shown below are synced to an example Swagger file URL and are kept up to date automatically with changes to the API.
+{% hint style="success" %}
+If the data pass **validation** and successfully save you'll receive a `201` status code.
 {% endhint %}
+
+Data sent via this API will appear in [Costs Overview](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/costs-overview "mention") and [Unit Metrics Lab](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/unit-metrics-lab "mention") on Cloudthread's platform.
diff --git a/reference/api-reference/metrics.md b/reference/api-reference/metrics.md
@@ -2,38 +2,52 @@
 
 ## Cost View Fetch
 
-Cloudthread provides the ability to query your [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view).
+Cloudthread provides the ability to query your [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view "mention").
 
 {% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/cost/metric/{metric_id}" method="get" %}
 [https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
 {% endswagger %}
 
-* `metric_id`: the ID of the Cost View you wish to query.
+To query [Cost Views](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-transparency/key-concepts/cost-view "mention"), use the endpoint above and the following query parameters:
 
-To query Cost Views, use the endpoint above and the following query parameters
+* Path (go after `/` in the URL)
+  * `metric_id`: the ID of the Cost View you wish to query
+* Query (go after `?` in the URL)
+  * `start_date`: start date of the timeframe you wish to query – formatted as YYYY-MM-DD, required
+  * `end_date`: inclusive end date of the timeframe you wish to query – formatted as YYYY-MM-DD
+  * `cost_type`: OPTIONAL – specifies the cost type (Unblended, Public, etc.)
+  * `amortization`: OPTIONAL – specifies if to include amortization
+  * `exclude`: OPTIONAL – specifies if to exclude taxes, refunds, etc.
+  * `granularity`: OPTIONAL – specifies the data granularity (hour, day, week, quarter, year)
 
-* `start_date`: start date of the timeframe you wish to query - formatted as YYYY-MM-DD
-* `end_date`: inclusive end date of the timeframe you wish to query - formatted as YYYY-MM-DD
-
-If the data pass validation a `200` status code.
+{% hint style="info" %}
+If the data pass **validation** a `200` status code.
+{% endhint %}
 
 ## Unit Metric Fetch
 
-Cloudthread provides the ability to query your [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric).
+Cloudthread provides the ability to query your [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric "mention").
 
 {% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/unit/metric/{metric_id}" method="get" %}
 [https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
 {% endswagger %}
 
-* `metric_id`: the ID of the Unit Metric you wish to query.
-
-To query Unit Metrics, use the endpoint above and the following query parameters
+To query [Unit Metrics](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/unit-metrics/key-concepts/unit-metric "mention") use the endpoint above and the following query parameters:
 
-* `start_date`: start date of the timeframe you wish to query - formatted as YYYY-MM-DD
-* `end_date`: inclusive end date of the timeframe you wish to query - formatted as YYYY-MM-DD
-
-If the data pass validation a `200` status code.
+* Path (go after `/` in the URL)
+  * `metric_id`: the ID of the Unit Metric you wish to query.
+* Query (go after `?` in the URL)
+  * `start_date`: start date of the timeframe you wish to query - formatted as YYYY-MM-DD
+  * `end_date`: inclusive end date of the timeframe you wish to query - formatted as YYYY-MM-DD
+  * `cost_type`: OPTIONAL – specifies the cost type (Unblended, Public, etc.)
+  * `amortization`: OPTIONAL – specifies if to include amortization
+  * `exclude`: OPTIONAL – specifies if to exclude taxes, refunds, etc.
+  * `granularity`: OPTIONAL – specifies the data granularity (hour, day, week, quarter, year)
 
 {% hint style="info" %}
-**Good to know:** All the methods shown below are synced to an example Swagger file URL and are kept up to date automatically with changes to the API.
+If the data pass **validation** a `200` status code.
+{% endhint %}
+
+{% hint style="success" %}
+See the response data **schema** at the method description above.
 {% endhint %}
diff --git a/reference/api-reference/savings-hub.md b/reference/api-reference/savings-hub.md
diff --git a/reference/api-reference/savings-hub/README.md b/reference/api-reference/savings-hub/README.md
@@ -0,0 +1,2 @@
+# Savings Hub
+
diff --git a/reference/api-reference/savings-hub/opportunities-explorer.md b/reference/api-reference/savings-hub/opportunities-explorer.md
@@ -0,0 +1,7 @@
+# Opportunities Explorer
+
+This API allows to work with [Savings Opportunities](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/cost-savings/key-concepts/optimization-opportunities "mention").
+
+{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/cost-optimization/opportunities/list" method="post" %}
+[https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
+{% endswagger %}
diff --git a/reference/api-reference/tag_catalog.md b/reference/api-reference/tag_catalog.md
@@ -2,16 +2,16 @@
 
 ## Tag Catalog Fetch
 
-Cloudthread provides the ability to fetch a Tag Catalog entry via catalog key.
+Cloudthread provides the ability to fetch a [Tags Catalog](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/tag-assistant/tag-catalogs "mention") entry via catalog key.
+
+{% hint style="info" %}
+See [Setting up Tag Catalog](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/guides/tagging-cloud-resources/setting-up-tag-catalog "mention") guide for more details.
+{% endhint %}
 
 {% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/tag-catalog" method="get" %}
 [https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
 {% endswagger %}
 
-To query Tag Catalog, use the endpoint above and the following query parameters
+To query [Tags Catalog](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/tag-assistant/tag-catalogs "mention"), use the endpoint above and the following query parameters
 
 * `catalog_key`: the ID of the Catalog entry you wish to query
-
-{% hint style="info" %}
-**Good to know:** All the methods shown below are synced to an example Swagger file URL and are kept up to date automatically with changes to the API.
-{% endhint %}
diff --git a/reference/api-reference/teams.md b/reference/api-reference/teams.md
diff --git a/reference/api-reference/users.md b/reference/api-reference/users.md
