diff --git a/README.md b/README.md index 710832f..9dade4c 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,9 @@ ## 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 jump right in? - -Jump in to the quick start docs and get running in no time: - -{% content-ref url="developer-api.md" %} -[quick-start.md](quick-start.md) -{% endcontent-ref %} - -## Want to deep dive? +## Want to check it out? Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API: diff --git a/SUMMARY.md b/SUMMARY.md index 4d98b2a..979bfcd 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,10 +1,15 @@ # Table of contents * [Welcome!](README.md) -* [Quick Start](developer-api.md) ## Reference * [API Reference](reference/api-reference/README.md) - * [Pets](reference/api-reference/pets.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) + * [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 new file mode 100644 index 0000000..c98c586 --- /dev/null +++ b/cldthrd_api.yaml @@ -0,0 +1,1059 @@ +openapi: 3.0.3 +info: + 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: Ingested successfully + 400: + description: Validation error + 404: + 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: Ingested successfully + 400: + description: Validation error + 404: + 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: 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' + - $ref: '#/components/parameters/EndDate' + - $ref: '#/components/parameters/CostType' + - $ref: '#/components/parameters/Amortization' + - $ref: '#/components/parameters/Exclude' + - $ref: '#/components/parameters/Granularity' + security: + - ApiKeyAuth: [ ] + responses: + 200: + 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' + - $ref: '#/components/parameters/EndDate' + - $ref: '#/components/parameters/CostType' + - $ref: '#/components/parameters/Amortization' + - $ref: '#/components/parameters/Exclude' + - $ref: '#/components/parameters/Granularity' + security: + - ApiKeyAuth: [ ] + responses: + 200: + 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: + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + + parameters: + CatalogKey: + name: catalog_key + in: query + description: Tag Catalog key + required: true + schema: + type: string + + MetricID: + name: metric_id + in: path + description: Cost View or Unit Metric ID + required: true + schema: + type: string + + TeamID: + name: team_id + in: path + description: team id + required: true + schema: + type: string + + StartDate: + name: start_date + in: query + description: Start Date + required: true + schema: + type: string + + EndDate: + name: end_date + in: query + description: End Date + required: true + schema: + type: string + + CostType: + name: cost_type + in: query + description: Cost Type or Cost Column ID + required: false + schema: + oneOf: + - type: string + - type: integer + + Amortization: + name: amortization + in: query + description: Cost Data Amortization + required: false + schema: + type: boolean + + Exclude: + name: exclude + in: query + description: Excluded Payment Types + required: false + schema: + type: string + + Granularity: + name: granularity + in: query + description: Metric Date Granularity + required: false + schema: + type: string + + requestBodies: + StreamData: + description: Definition of the data stream + content: + application/json: + schema: + $ref: '#/components/schemas/StreamData' + + CreateEvents: + 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 + 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: 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: 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/developer-api.md b/developer-api.md deleted file mode 100644 index f20198b..0000000 --- a/developer-api.md +++ /dev/null @@ -1,110 +0,0 @@ -# Developer API - -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. - -## Basic setup - -Cloudthread's Developer API lives at - -`https://api.cloudthread.io` - -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. - -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. - -## Data Ingestion - -Cloudthread provides the abiilty to send data to our systems that can then be used on the platform. - -Cloudthread requires a **Data Stream Token** to process incoming Data Ingestion API requests. This token helps organize and control the flow of data. Data Stream Tokens are generated with a **Data Stream Type** that determines how the incoming data is validated. Admin's have the ability to generate a Data Stream Token on the Cloudthread platform within the **Settings** tab. - -This Data Stream Token should be included in the body of incoming ingestion requests as demonstrated in the payload examples below. - -All ingestion requests use the following endpoint - -`https://api.cloudthread.io/streams/ingest` - -## Custom Data Ingestion - -Cloudthread can process custom data to help customers understand their non-cost data as it relates to their cost data. - -In order to send custom data, you must provision a **Custom Data - Data Stream Token** on the Cloudthread platform within the **Settings** tab. - -To send custom data to Cloudthread, use the **Data Ingestion** endpoint above with the provisioned Data Stream Token and the following payload - -```json -{ - data_stream_token: {DATA_STREAM_TOKEN}, - metric_agg_func: 'Sum' | 'Average' | 'Maximum' | 'Minimum', - data: [ - { - timestamp: datetime, - metric_name: string, - metric_value: float, - custom_dimensions: { - string: string, - ... - } - }, - ... - ] -} -``` - -* `metric_agg_func`: aggregation function across the dataset. *Do not* include data with different aggregation methods into the same request. -* `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`. -* `metric_name`: name of the metric -- all metrics that share a name and aggregation function will be grouped together by date given the prescribed aggregation function. This means you can up have up to four versions of the same metric name based on different aggregation functions. -* `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. - -Data sent via this API will appear in the **Unit Metrics Lab** on Cloudthread's platform. - -## Event Overlay Ingestion - -Cloudthread can process webhook events that can be overlayed on top of your cost data and unit metrics. - -To send events data to Cloudthread, use the following endpoint and the following payload - -`https://api.cloudthread.io/events` - -```json -{ - data: [ - { - timestamp: datetime, - team_id?: int, - payload: { - decscription: string (max length 1000), - type: string, - event_url?: string, - } - }, - ... - ] -} -``` - -* `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. -* `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. - -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. - - -##COMING SOON - Data querying API - -Please contact support@cloudthread.io for more information about this feature diff --git a/quick-start.md b/quick-start.md deleted file mode 100644 index 8aa1b78..0000000 --- a/quick-start.md +++ /dev/null @@ -1,128 +0,0 @@ -# Quick Start - -{% hint style="info" %} -**Good to know:** A quick start guide can be good to help folks get up and running with your API in a few steps. Some people prefer diving in with the basics rather than meticulously reading every page of documentation! -{% endhint %} - -## Get your API keys - -Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. - -You can generate an API key from your Dashboard at any time. - -## Install the library - -The best way to interact with our API is to use one of our official libraries: - -{% tabs %} -{% tab title="Node" %} -``` -# Install via NPM -npm install --save my-api -``` -{% endtab %} - -{% tab title="Python" %} -``` -# Install via pip -pip install --upgrade myapi -``` -{% endtab %} -{% endtabs %} - -{% hint style="info" %} -**Good to know:** Using tabs to separate out different languages is a great way to present technical examples or code documentation without cramming your docs with extra sections or pages per language. -{% endhint %} - -## Make your first request - -To make your first request, send an authenticated request to the pets endpoint. This will create a `pet`, which is nice. - -{% swagger baseUrl="https://api.myapi.com/v1" method="post" path="/pet" summary="Create pet." %} -{% swagger-description %} -Creates a new pet. -{% endswagger-description %} - -{% swagger-parameter in="body" name="name" required="true" type="string" %} -The name of the pet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="owner_id" required="false" type="string" %} -The - -`id` - - of the user who owns the pet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="species" required="false" type="string" %} -The species of the pet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="breed" required="false" type="string" %} -The breed of the pet -{% endswagger-parameter %} - -{% swagger-response status="200" description="Pet successfully created" %} -```javascript -{ - "name"="Wilson", - "owner": { - "id": "sha7891bikojbkreuy", - "name": "Samuel Passet", - "species": "Dog",} - "breed": "Golden Retriever", -} -``` -{% endswagger-response %} - -{% swagger-response status="401" description="Permission denied" %} - -{% endswagger-response %} -{% endswagger %} - -{% hint style="info" %} -**Good to know:** You can use the API Method block to fully document an API method. You can also sync your API blocks with an OpenAPI file or URL to auto-populate them. -{% endhint %} - -Take a look at how you might call this method using our official libraries, or via `curl`: - -{% tabs %} -{% tab title="curl" %} -``` -curl https://api.myapi.com/v1/pet - -u YOUR_API_KEY: - -d name='Wilson' - -d species='dog' - -d owner_id='sha7891bikojbkreuy' -``` -{% endtab %} - -{% tab title="Node" %} -```javascript -// require the myapi module and set it up with your API key -const myapi = require('myapi')(YOUR_API_KEY); - -const newPet = away myapi.pet.create({ - name: 'Wilson', - owner_id: 'sha7891bikojbkreuy', - species: 'Dog', - breed: 'Golden Retriever', -}) -``` -{% endtab %} - -{% tab title="Python" %} -```python -// Set your API key before making the request -myapi.api_key = YOUR_API_KEY - -myapi.Pet.create( - name='Wilson', - owner_id='sha7891bikojbkreuy', - species='Dog', - breed='Golden Retriever', -) -``` -{% endtab %} -{% endtabs %} diff --git a/reference/api-reference/README.md b/reference/api-reference/README.md index 944a744..402091f 100644 --- a/reference/api-reference/README.md +++ b/reference/api-reference/README.md @@ -1,23 +1,87 @@ # API Reference -Dive into the specifics of each API endpoint by checking out our complete documentation. +Cloudthread provides a powerful and flexible **REST Developer API** to help you get the most out of your data. -## Pets +These docs show how to use the API, and what features are currently available. -All the methods associated with `CRUD`ing some pets. Which isn't as weird as it sounds: +{% 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: + +{% embed url="https://api.cloudthread.io" fullWidth="false" %} + +{% hint style="warning" %} +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](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}` + +{% hint style="danger" %} +Any request without a valid token will be **rejected**. +{% endhint %} + +## 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](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. -{% content-ref url="pets.md" %} -[pets.md](pets.md) +## 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. + +## Tag Catalog fetch + +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 + +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 +## Users and Teams setup -Everything related to users: +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) {% endcontent-ref %} -{% hint style="info" %} -**Good to know:** Using the 'Page Link' block lets you link directly to a page. If this page's name, URL or parent location changes, the reference will be kept up to date. You can also mention a page – like [pets.md](pets.md "mention") – if you don't want a block-level link. -{% endhint %} +{% 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 new file mode 100644 index 0000000..1787b6b --- /dev/null +++ b/reference/api-reference/custom_data.md @@ -0,0 +1,48 @@ +# Data Ingestion + +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](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: + +```json +{ + data_stream_token: {DATA_STREAM_TOKEN}, + metric_agg_func: 'Sum' | 'Average' | 'Maximum' | 'Minimum', + data: [ + { + timestamp: datetime, + metric_name: string, + metric_value: float, + custom_dimensions: { + string: string, + ... + } + }, + ... + ] +} +``` + +* `metric_agg_func`: aggregation function across the dataset. _Do not_ include data with different aggregation methods into the same request. +* `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`. +* `metric_name`: name of the metric -- all metrics that share a name and aggregation function will be grouped together by date given the prescribed aggregation function. This means you can up have up to four versions of the same metric name based on different aggregation functions. +* `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. + +{% 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 new file mode 100644 index 0000000..4ba707b --- /dev/null +++ b/reference/api-reference/events.md @@ -0,0 +1,40 @@ +# Events Overlay Ingestion + +## Event Overlay Ingestion + +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: + +```json +{ + data: [ + { + timestamp: datetime, + team_id?: int, + payload: { + decscription: string (max length 1000), + type: string, + event_url?: string, + } + }, + ... + ] +} +``` + +* `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. +* `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. + +{% 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 new file mode 100644 index 0000000..6ee5023 --- /dev/null +++ b/reference/api-reference/metrics.md @@ -0,0 +1,53 @@ +# Metric Fetch + +## 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 "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 %} + +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: + +* 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) + +{% 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 "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 %} + +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: + +* 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" %} +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/pets.md b/reference/api-reference/pets.md deleted file mode 100644 index 5966dfb..0000000 --- a/reference/api-reference/pets.md +++ /dev/null @@ -1,60 +0,0 @@ -# Pets - -## Creating a new pet - -{% swagger baseUrl="https://api.myapi.com/v1" method="post" path="/pet" summary="Create pet." %} -{% swagger-description %} -Creates a new pet. -{% endswagger-description %} - -{% swagger-parameter in="body" name="name" required="true" type="string" %} -The name of the pet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="owner_id" required="false" type="string" %} -The - -`id` - - of the user who owns the pet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="species" required="false" type="string" %} -The species of the pet -{% endswagger-parameter %} - -{% swagger-parameter in="body" name="breed" required="false" type="string" %} -The breed of the pet -{% endswagger-parameter %} - -{% swagger-response status="200" description="Pet successfully created" %} -```javascript -{ - "name"="Wilson", - "owner": { - "id": "sha7891bikojbkreuy", - "name": "Samuel Passet", - "species": "Dog",} - "breed": "Golden Retriever", -} -``` -{% endswagger-response %} - -{% swagger-response status="401" description="Permission denied" %} - -{% endswagger-response %} -{% endswagger %} - -{% hint style="info" %} -**Good to know:** This API method was created using the API Method block, it's how you can build out an API method documentation from scratch. Have a play with the block and you'll see you can do some nifty things like add and reorder parameters, document responses, and give your methods detailed descriptions. -{% endhint %} - -## Updating a pet - -{% swagger src="https://petstore.swagger.io/v2/swagger.json" path="/pet" method="put" %} -[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json) -{% endswagger %} - -{% hint style="info" %} -**Good to know:** This API method was auto-generated from an example Swagger file. You'll see that it's not editable – that's because the contents are synced to a URL! Any time the linked file changes, the documentation will change too. -{% 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 new file mode 100644 index 0000000..488caa5 --- /dev/null +++ b/reference/api-reference/tag_catalog.md @@ -0,0 +1,17 @@ +# Tag Catalog Fetch + +## Tag Catalog Fetch + +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 [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 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 index 4314c8f..e5a0fe3 100644 --- a/reference/api-reference/users.md +++ b/reference/api-reference/users.md @@ -1,25 +1,9 @@ # Users -{% 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 %} +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. -## User actions +## Users GET -{% swagger src="https://petstore.swagger.io/v2/swagger.json" path="/user/login" method="get" %} -[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json) -{% endswagger %} - -{% swagger src="https://petstore.swagger.io/v2/swagger.json" path="/user/logout" method="get" %} -[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json) -{% endswagger %} - -## Creating users - -{% swagger src="https://petstore.swagger.io/v2/swagger.json" path="/user/createWithList" method="post" %} -[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json) -{% endswagger %} - -{% swagger src="https://petstore.swagger.io/v2/swagger.json" path="/user/createWithArray" method="post" %} -[https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json) +{% 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 %}