diff --git a/README.md b/README.md index 5b38ef9..9dade4c 100644 --- 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 index 2d1105d..979bfcd 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,7 +5,11 @@ ## Reference * [API Reference](reference/api-reference/README.md) - * [Data Ingestion](reference/api-reference/custom_data.md) + * [Data Ingestion](reference/api-reference/custom\_data.md) * [Events Overlay Ingestion](reference/api-reference/events.md) - * [Tag Catalog Fetch](reference/api-reference/tag_catalog.md) + * [Tag Catalog Fetch](reference/api-reference/tag\_catalog.md) * [Metric Fetch](reference/api-reference/metrics.md) + * [Users](reference/api-reference/users.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/cldthrd_api.yaml b/cldthrd_api.yaml index c6b7761..c98c586 100644 --- a/cldthrd_api.yaml +++ b/cldthrd_api.yaml @@ -1,54 +1,120 @@ openapi: 3.0.3 info: - version: 0.0.1 + version: 0.0.2 title: Cloudthread API + description: | + This API allows for interaction with Cloudthread cloud cost management Platform. + termsOfService: https://www.cloudthread.io/terms-of-use + contact: + email: hey@cloudthread.io + servers: - url: 'https://api.cloudthread.io' + +tags: + - name: streams + description: Data ingestion streams + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/custom_data + - name: events + description: Custom events that can be overlayed on top of your Cost Views and Unit Metrics + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/events + - name: tag-catalog + description: Tag catalog manipulation + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/tag_catalog + - name: cost-views + description: Cost Views manipulation + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/metrics#cost-view-fetch + - name: unit-metrics + description: Unit Metric manipulation + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/metrics#unit-metric-fetch + - name: users + description: Users manipulation + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/users + - name: teams + description: Teams manipulation + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/teams + - name: savings-opportunities + description: Savings Opportunities manipulation + externalDocs: + description: Find out more + url: https://docs.cloudthread.io/v/api-docs/reference/api-reference/savings-hub/opportunities-explorer + paths: /streams/ingest: post: + summary: Ingests data into created Data Stream operationId: ingest_stream_data + tags: + - streams requestBody: $ref: '#/components/requestBodies/StreamData' security: - ApiKeyAuth: [] responses: 201: - description: created + description: Ingested successfully 400: - description: validation error + description: Validation error 404: - description: no stream found + description: No stream found /events: post: + summary: Ingests the custom events data + description: Ingests the custom events data that can be overlayed on top of your Cost Views and Unit Metrics operationId: create_events + tags: + - events requestBody: $ref: '#/components/requestBodies/CreateEvents' security: - ApiKeyAuth: [ ] responses: 201: - description: created + description: Ingested successfully 400: - description: validation error + description: Validation error 404: - description: no team found + description: No team found /tag-catalog: get: + summary: Fetches a Tag Catalog entry via catalog key operationId: get_tag_catalog + tags: + - tag-catalog parameters: - $ref: '#/components/parameters/CatalogKey' security: - ApiKeyAuth: [ ] responses: 200: - description: success + description: Tag catalog data + content: + application/json: + schema: + $ref: '#/components/schemas/GetTagCatalogPayload' /cost/metric/{metric_id}: get: + summary: Returns cost data from Cloudthread Cost View operationId: get_cost_metric_filter_data + tags: + - cost-views parameters: - $ref: '#/components/parameters/MetricID' - $ref: '#/components/parameters/StartDate' @@ -61,11 +127,18 @@ paths: - ApiKeyAuth: [ ] responses: 200: - description: success + description: Metric data + content: + application/json: + schema: + $ref: '#/components/schemas/GetCostViewPayload' /unit/metric/{metric_id}: get: + summary: Returns cost data from Cloudthread Unit Metric operationId: get_unit_metric_filter_data + tags: + - unit-metrics parameters: - $ref: '#/components/parameters/MetricID' - $ref: '#/components/parameters/StartDate' @@ -78,7 +151,188 @@ paths: - ApiKeyAuth: [ ] responses: 200: - description: success + description: Metric data + content: + application/json: + schema: + $ref: '#/components/schemas/GetUnitMetricPayload' + + /users: + get: + summary: Returns data on users + description: Returns data on registered Users of Cloudthread platform + operationId: get_users + tags: + - users + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: List of users + content: + application/json: + schema: + $ref: '#/components/schemas/GetUsersResponse' + + /teams: + get: + summary: Returns list of Teams + description: Fetches list of Teams within the org + operationId: get_teams_within_org + tags: + - teams + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: List of teams + content: + application/json: + schema: + $ref: '#/components/schemas/GetTeamsResponse' + + post: + summary: Creates new Team + description: Creates new Team within the org + operationId: create_team + tags: + - teams + requestBody: + $ref: '#/components/requestBodies/CreateTeam' + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: Team created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + 400: + description: Validation error + 404: + description: Slack integration or Slack channel not found + + /teams/{team_id}: + get: + summary: Returns specific Team + description: Fetches data on a specific Team within the org + operationId: get_team_within_org + tags: + - teams + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: Get team + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + patch: + summary: Updates existing Team + operationId: update_team + tags: + - teams + requestBody: + $ref: '#/components/requestBodies/CreateTeam' + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: Updated + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + 400: + description: Validation error + 404: + description: Slack integration/slack channel not found/team not found + + delete: + summary: Deletes existing Team + operationId: delete_team + tags: + - teams + security: + - ApiKeyAuth: [ ] + responses: + 204: + description: Deleted + 404: + description: Team not found + + /teams/{team_id}/members: + get: + operationId: get_team_members + summary: Returns list of Team members + description: Fetches list of members of specific Team + tags: + - teams + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: List of team members + content: + application/json: + schema: + $ref: '#/components/schemas/GetUsersResponse' + + /teams/{team_id}/members/assign: + post: + operationId: assign_users_to_team + summary: Adds new Users to specific Team + tags: + - teams + requestBody: + $ref: '#/components/requestBodies/AssignUsersToTeam' + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: List of team members + content: + application/json: + schema: + $ref: '#/components/schemas/GetUsersResponse' + + /teams/{team_id}/members/delete: + post: + operationId: assign_users_to_team + summary: Deletes Users from specific Team + tags: + - teams + requestBody: + $ref: '#/components/requestBodies/RemoveUsersFromTeam' + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: List of team members + content: + application/json: + schema: + $ref: '#/components/schemas/GetUsersResponse' + + /cost-optimization/opportunities/list: + post: + operationId: get_opportunities + summary: Returns the list of Savings Opportunities + tags: + - savings-opportunities + requestBody: + $ref: '#/components/requestBodies/GetOpportunitiesQuery' + security: + - ApiKeyAuth: [ ] + responses: + 200: + description: List of savings opportunities + content: + application/json: + schema: + $ref: '#/components/schemas/GetOpportunitiesResponse' components: securitySchemes: @@ -95,14 +349,22 @@ components: required: true schema: type: string - + MetricID: name: metric_id in: path description: Cost View or Unit Metric ID required: true schema: - type: in + type: string + + TeamID: + name: team_id + in: path + description: team id + required: true + schema: + type: string StartDate: name: start_date @@ -126,7 +388,9 @@ components: description: Cost Type or Cost Column ID required: false schema: - type: string or integer + oneOf: + - type: string + - type: integer Amortization: name: amortization @@ -142,7 +406,7 @@ components: description: Excluded Payment Types required: false schema: - type: comma-seperated string + type: string Granularity: name: granularity @@ -154,75 +418,642 @@ components: requestBodies: StreamData: - description: stream data + description: Definition of the data stream content: application/json: schema: $ref: '#/components/schemas/StreamData' CreateEvents: - description: create events + description: Create events for Events Overlay content: application/json: schema: $ref: '#/components/schemas/CreateEvents' + CreateTeam: + description: Create team + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTeamRequest' + + AssignUsersToTeam: + description: Assign Users to Team + content: + application/json: + schema: + description: List of Users + properties: + users_ids: + type: array + description: List of User IDs + items: + type: string + description: User ID + + RemoveUsersFromTeam: + description: Remove users from Team + content: + application/json: + schema: + description: List of Users + properties: + users_ids: + type: array + description: List of User IDs + items: + type: string + description: User ID + + GetOpportunitiesQuery: + description: Query to filter opportunities + content: + application/json: + schema: + $ref: '#/components/schemas/GetOpportunitiesQuery' + schemas: StreamData: - description: stream data + description: Stream data + type: object + required: + - data_stream_token + - metric_agg_func + - data properties: data_stream_token: type: string example: sometoken + description: Data stream token metric_agg_func: type: string example: Sum | Average | Minimum | Maximum + description: Aggregation function identifier (Sum | Average | Minimum | Maximum) data: type: array + description: Data timeseries items: $ref: '#/components/schemas/StreamDataPayload' StreamDataPayload: + description: Payload for data ingestion stream + type: object + required: + - timestamp + - metric_name + - metric_value properties: timestamp: type: string format: date-time - example: 1234567890 - description: can be either timestamp or datetime string + example: yyyyMMddHHmmss + description: Can be either timestamp or datetime string metric_name: type: string + example: customers + description: The name of the metric being ingested metric_value: type: number format: float example: 3.14 + description: The value of the metric being ingested custom_dimensions: type: object + description: Map of up to 10 key value pairs that you will be able to segment the data by on the Cloudthread platform + example: [[region1, 20.5], [region2, 7.0]] CreateEvents: + description: List of Events with their properties + type: object properties: data: type: array + description: Event data items: $ref: '#/components/schemas/CreateEventsData' CreateEventsData: + description: Properties defining the Event + type: object + required: + - timestamp + - payload properties: timestamp: type: string format: date-time - example: 1234567890 - description: can be either timestamp or datetime string - payload: - $ref: '#/components/schemas/EventsPayload' + example: yyyyMMddHHmmss + description: Can be either timestamp or datetime string team_id: type: integer example: 1 + description: ID of the team that events are relevant to (if teams are defined) + payload: + $ref: '#/components/schemas/EventsPayload' EventsPayload: + description: Events data payload + type: object + required: + - type properties: type: type: string + example: deploy + description: Event type (deploy, outage, etc.) description: type: string + example: Major code improvements + description: Event description event_url: type: string + example: https://foo.org + description: Link to event details if applicable + + GetTagCatalogPayload: + description: Tag Catalog fetch response + type: object + properties: + tags: + type: array + description: List of tags + items: + $ref: '#/components/schemas/Tags' + + GetCostViewPayload: + description: Data returned by query of Cost View + type: object + properties: + data: + type: array + description: List of Cost View data points (timeseries) + items: + $ref: '#/components/schemas/GetCostViewDataPoint' + + GetCostViewDataPoint: + description: Data point for Cost View for specific date + type: object + properties: + current_timeframe_cost: + type: number + format: float + description: Cost ($) for current period + previous_timeframe_cost: + type: number + format: float + description: Cost ($) for previous period + pop_diff: + type: number + format: float + description: Period-over-period difference total ($) + pop_change: + type: number + format: float + description: Period-over-period change (% decimal) + date: + type: string + example: YYYYMMDD + description: Period date + + GetUnitMetricPayload: + description: Data returned by query of Unit Metric + type: object + properties: + data: + type: array + description: List of Unit Metric data points (timeseries) + items: + $ref: '#/components/schemas/GetUnitMetricDataPoint' + + GetUnitMetricDataPoint: + description: Data point for Unit Metric for specific date + type: object + properties: + current_timeframe_denominator: + type: number + format: float + description: Denominator value for current period + current_timeframe_numerator: + type: number + format: float + description: Numerator value for current period ($) + current_timeframe_unit_metric: + type: number + format: float + description: Calculated unit metric for current period ($) + previous_timeframe_denominator: + type: number + format: float + description: Denominator value for previous period + previous_timeframe_numerator: + type: number + format: float + description: Numerator value for previous period ($) + previous_timeframe_unit_metric: + type: number + format: float + description: Calculated unit metric for previous period ($) + pop_diff: + type: number + format: float + description: Period-over-period difference total ($) + pop_change: + type: number + format: float + description: Period-over-period change (% decimal) + d_agg_func: + type: string + description: Denominator aggregation function (SUM, AVERAGE, etc.) + n_agg_func: + type: string + description: Denominator aggregation function (SUM, AVERAGE, etc.) + date: + type: string + description: Period date + + User: + description: Registered User on Cloudthread platform + type: object + required: + - id + - email + - name + properties: + id: + type: string + description: User type (Admin, User) + email: + type: string + description: User email + name: + type: string + description: User name + + GetUsersResponse: + description: List of Users + type: array + items: + $ref: '#/components/schemas/User' + + CreateTeamRequest: + description: Request to create a Team definition + type: object + required: + - id + - name + properties: + id: + type: string + description: Team ID + name: + type: string + description: Team name + slack_channel: + type: string + description: Slack channel link for the team notifications + aws_account_ids: + type: array + description: Team-level data filter – AWS accounts list + items: + type: string + description: AWS account ID + aws_bill_payer_account_ids: + type: array + description: Team-level data filter – AWS Payer accounts list + items: + type: string + description: AWS account ID + aws_region_names: + type: array + description: Team-level data filter – AWS regions list + items: + type: string + description: AWS region name (e.g. us-east-1) + aws_services: + type: array + description: Team-level data filter – AWS services list + items: + type: string + description: AWS service name (e.g. Amazon S3) + aws_tags: + type: array + description: Team-level data filter – AWS resource tags list + items: + type: object + description: AWS resource tag (key-value pair) + aws_account_tags: + type: array + description: Team-level data filter – AWS account tags list + items: + type: object + description: AWS account tag (key-value pair) + gcp_project_names: + type: array + description: Team-level data filter – GCP projects list + items: + type: string + description: GCP project ID + gcp_billing_account_ids: + type: array + description: Team-level data filter – GCP billing accounts ID list + items: + type: string + description: GCP billing account ID + gcp_sku_ids: + type: array + description: Team-level data filter – GCP SKU ID list + items: + type: string + description: GCP SKU ID + gcp_locations: + type: array + description: Team-level data filter – GCP locations list + items: + type: string + description: GCP location name + gcp_services: + type: array + description: Team-level data filter – GCP services list + items: + type: string + description: GCP service name + gcp_labels: + type: array + description: Team-level data filter – GCP labels list + items: + type: object + description: GCP label (key-value pair) + custom_stream_tokens: + type: array + description: Custom stream tokens list + items: + type: string + description: Custom stream token + custom_metric_names: + type: array + description: Custom stream metrics list + items: + type: string + description: Custom stream metric + custom_dimensions: + type: array + description: Custom dimensions list + items: + type: object + description: Custom dimension + opportunity_priorities: + type: array + description: Opportunity priority definition list + items: + type: integer + description: Opportunity priority identifier + + TeamResponse: + description: Properties defining the Team + type: object + properties: + id: + type: string + description: Team ID + name: + type: string + description: Team name + slack_channel: + type: string + description: Slack channel link for the team notifications + aws_account_ids: + type: array + description: Team-level data filter – AWS accounts list + items: + type: string + description: AWS account ID + aws_bill_payer_account_ids: + type: array + description: Team-level data filter – AWS Payer accounts list + items: + type: string + description: AWS account ID + aws_region_names: + type: array + description: Team-level data filter – AWS regions list + items: + type: string + description: AWS region name (e.g. us-east-1) + aws_services: + type: array + description: Team-level data filter – AWS services list + items: + type: string + description: AWS service name (e.g. Amazon S3) + aws_tags: + type: array + description: Team-level data filter – AWS resource tags list + items: + type: object + description: AWS resource tag (key-value pair) + aws_account_tags: + type: array + description: Team-level data filter – AWS account tags list + items: + type: object + description: AWS account tag (key-value pair) + gcp_project_names: + type: array + description: Team-level data filter – GCP projects list + items: + type: string + description: GCP project ID + gcp_billing_account_ids: + type: array + description: Team-level data filter – GCP billing accounts ID list + items: + type: string + description: GCP billing account ID + gcp_sku_ids: + type: array + description: Team-level data filter – GCP SKU ID list + items: + type: string + description: GCP SKU ID + gcp_locations: + type: array + description: Team-level data filter – GCP locations list + items: + type: string + description: GCP location name + gcp_services: + type: array + description: Team-level data filter – GCP services list + items: + type: string + description: GCP service name + gcp_labels: + type: array + description: Team-level data filter – GCP labels list + items: + type: object + description: GCP label (key-value pair) + custom_stream_tokens: + type: array + description: Custom stream tokens list + items: + type: string + description: Custom stream token + custom_metric_names: + type: array + description: Custom stream metrics list + items: + type: string + description: Custom stream metric + custom_dimensions: + type: array + description: Custom dimensions list + items: + type: object + description: Custom dimension + opportunity_priorities: + type: array + description: Opportunity priority definition list + items: + type: integer + description: Opportunity priority identifier + + GetTeamsResponse: + description: List of Teams with their properties + type: array + items: + $ref: '#/components/schemas/TeamResponse' + + GetOpportunitiesQuery: + description: Filter parameters to retrieve the list of matching opportunities + type: object + properties: + opportunity_type_id: + type: string + description: Opportunity type ID + status: + type: string + description: Opportunity status (e.g. Assigned, In Progress, Validation, Done, etc.) + code_automation: + type: boolean + description: Opportunity automation option (True/False) + thread_id: + type: integer + description: ID of Thread that contains opportunity (if assigned) + account: + type: string + description: ID of cloud account related to resource featured in opportunity + region: + type: string + description: Name of region related to resource featured in opportunity + service: + type: string + description: Name of service related to resource featured in opportunity + tags: + type: array + description: Tags of resource featured in opportunity + items: + $ref: '#/components/schemas/Tags' + category: + type: string + description: Opportunity category (e.g. Redshift Righsizing) + record_id: + type: string + description: ID of resource featured in opportunity + source: + type: string + description: Opportunity data source (e.g. Cloudthread, AWS Compute Optimizer, etc.) + github_pr_key: + type: string + description: GitHub Pull Request related to opportunity + secondary_id: + type: integer + description: Secondary ID of opportunity + last_detected_start_date: + type: string + format: date + description: Date filter for last detected date (start value) + last_detected_end_date: + type: string + format: date + description: Date filter for last detected date (end value) + status_updated_start_date: + type: string + format: date + description: Date filter for status updated date (start value) + status_updated_end_date: + type: string + format: date + description: Date filter for status updated date (end value) + details: + type: boolean + description: If opportunity details present (True/False) + priority: + type: integer + description: Opportunity priority (1, 2, 3, etc.) + + Tags: + description: Cost allocation resource tags + type: object + properties: + Key: + type: string + description: Resource tag key + Value: + type: string + description: Resource tag value + + GetOpportunitiesResponse: + description: List of filtered opportunities + type: array + items: + $ref: '#/components/schemas/GetOpportunities' + + GetOpportunities: + description: Opportunity data + type: object + properties: + id: + type: integer + description: Opportunity ID + source: + type: string + description: Opportunity data source (e.g. Cloudthread, AWS Compute Optimizer, etc.) + opportunity_details: + type: object + description: Opportunity details (JSON) + opportunity_type_id: + type: string + description: Opportunity type ID + cost_impact: + type: number + description: Opportunity estimated savings + record_id: + type: string + description: ID of resource featured in opportunity + status_updated_at: + type: string + format: date-time + description: Date when opportunity status was last updated + created_at: + type: string + format: date-time + description: Date when opportunity was created + status: + type: string + description: Opportunity status (e.g. Assigned, In Progress, Validation, Done, etc.) + last_detected_at: + type: string + format: date-time + description: Date when opportunity was last detected + thread_id: + type: integer + description: ID of Thread that contains opportunity (if assigned) + github_pr_key: + type: string + description: GitHub Pull Request related to opportunity (if any) + +externalDocs: + description: Find out more about Cloudthread platform + url: https://docs.cloudthread.io \ No newline at end of file diff --git a/reference/api-reference/README.md b/reference/api-reference/README.md index d78b2ef..402091f 100644 --- a/reference/api-reference/README.md +++ b/reference/api-reference/README.md @@ -1,50 +1,87 @@ -# Quick Start +# 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. -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](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 + +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](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. -* [Data Ingestion](reference/api-reference/custom_data.md) +## Tag Catalog fetch -Data sent via this API will appear in **Costs Overview** and **Unit Metrics Lab** on Cloudthread's platform. +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. -## Event Overlay Ingestion +{% content-ref url="tag_catalog.md" %} +[tag\_catalog.md](tag\_catalog.md) +{% endcontent-ref %} -Cloudthread provides the ability to send webhook Events that can be overlayed on top of your Cost Views and Unit Metrics. +## Cost View and Unit Metric Data fetch -* [Events Overlay Ingestion](reference/api-reference/events.md) +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. -Data sent via this API will appear in **Costs Overview** and **Unit Metrics Lab** on Cloudthread's platform. +{% content-ref url="metrics.md" %} +[metrics.md](metrics.md) +{% endcontent-ref %} -## Tag Catalog Fetch +## Users and Teams setup -Cloudthread provides the ability to fetch a Tag Catalog entry via catalog key. +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"). -* [Tag Catalog Fetch](reference/api-reference/tag_catalog.md) +{% content-ref url="users.md" %} +[users.md](users.md) +{% endcontent-ref %} +{% content-ref url="teams.md" %} +[teams.md](teams.md) +{% endcontent-ref %} -## Cost View and Unit Metric Data Fetch +## Savings Hub manipulation -Cloudthread provides the ability to fetch a Cost View and Unit Metric data. +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"). -* [Metric Fetch](reference/api-reference/metrics.md) +{% 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 index 52a0dff..1787b6b 100644 --- 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 index 8677cae..4ba707b 100644 --- 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 index 26b3b57..6ee5023 100644 --- a/reference/api-reference/metrics.md +++ b/reference/api-reference/metrics.md @@ -1,39 +1,53 @@ -# Metry Fetch +# Metric Fetch ## Cost View Fetch -Cloudthread provides the ability to query your Cost Views. +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 Unit Metric 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. +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/README.md b/reference/api-reference/savings-hub/README.md new file mode 100644 index 0000000..6779bcf --- /dev/null +++ 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 new file mode 100644 index 0000000..dc73ad4 --- /dev/null +++ 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 index 77465db..488caa5 100644 --- 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 %} \ No newline at end of file diff --git a/reference/api-reference/teams.md b/reference/api-reference/teams.md new file mode 100644 index 0000000..64431af --- /dev/null +++ b/reference/api-reference/teams.md @@ -0,0 +1,59 @@ +# Teams + +Cloudthread platform allows for manipulation of [Teams](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings/teams "mention") via an API. See [Setting up Teams](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/guides/onboarding/setting-up-teams "mention") for a guide on setting up teams through the UI. + +{% hint style="success" %} +You can **create**, **edit**, and **delete** Teams via Cloudthread's API. + +See the API method specifications to learn more about the parameters of paths, queries, and responses. +{% endhint %} + +## Team POST + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams" 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 create a new Team (see [Teams](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings/teams "mention")) you need to issue a **POST** request with the team definition parameters in the form of **JSON** request body. + +## Team PATCH + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams/{team_id}" method="patch" %} +[https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml) +{% endswagger %} + +## Team DELETE + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams/{team_id}" method="delete" %} +[https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml) +{% endswagger %} + +## Team GET + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams/{team_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 %} + +## Teams GET + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams" 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 %} + +## Teams POST – Assign Members + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams/{team_id}/members/assign" 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 %} + +## Teams POST – Remove Members + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams/{team_id}/members/delete" 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 %} + +## Teams GET – Members List + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/teams/{team_id}/members" 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 %} diff --git a/reference/api-reference/users.md b/reference/api-reference/users.md new file mode 100644 index 0000000..e5a0fe3 --- /dev/null +++ b/reference/api-reference/users.md @@ -0,0 +1,9 @@ +# Users + +Cloudthread platform allows for manipulation of **Users** via an API. See [User Management](http://127.0.0.1:5000/s/XCkDKj2xeiQhlyRGF6Wr/fundamentals/settings/account-and-team-management "mention") to learn more about the User roles and functions. + +## Users GET + +{% swagger src="https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml" path="/users" 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 %}