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 8f399e1..979bfcd 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -5,9 +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)
-  * [Teams](reference/api-reference/teams.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 9c624ed..c98c586 100644
--- a/cldthrd_api.yaml
+++ b/cldthrd_api.yaml
@@ -1,58 +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: tag data
+          description: Tag catalog data
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/GetTagsPayload'
+                $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'
@@ -65,7 +127,7 @@ paths:
         - ApiKeyAuth: [ ]
       responses:
         200:
-          description: metric data
+          description: Metric data
           content:
             application/json:
               schema:
@@ -73,7 +135,10 @@ paths:
 
   /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'
@@ -86,7 +151,7 @@ paths:
         - ApiKeyAuth: [ ]
       responses:
         200:
-          description: metric data
+          description: Metric data
           content:
             application/json:
               schema:
@@ -94,96 +159,122 @@ paths:
 
   /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
+          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: get teams
+          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: create team
+          description: Team created successfully
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/TeamResponse'
         400:
-          description: validation error
+          description: Validation error
         404:
-          description: slack integration or slack channel not found
+          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
+          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
+          description: Updated
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/TeamResponse'
         400:
-          description: validation error
+          description: Validation error
         404:
-          description: slack integration/slack channel not found/team not found
+          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
+          description: Deleted
         404:
-          description: team not found
+          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
+          description: List of team members
           content:
             application/json:
               schema:
@@ -192,13 +283,16 @@ paths:
   /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
+          description: List of team members
           content:
             application/json:
               schema:
@@ -207,18 +301,39 @@ paths:
   /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
+          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:
@@ -234,7 +349,7 @@ components:
       required: true
       schema:
         type: string
-
+        
     MetricID:
       name: metric_id
       in: path
@@ -273,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
@@ -289,7 +406,7 @@ components:
       description: Excluded Payment Types
       required: false
       schema:
-        type: comma-seperated string
+        type: string
 
     Granularity:
       name: granularity
@@ -301,342 +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
+      description: Create team
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/CreateTeamRequest'
 
     AssignUsersToTeam:
-      description: assign users to team
+      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
+      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
 
-    GetTagsPayload:
+    GetTagCatalogPayload:
+      description: Tag Catalog fetch response
+      type: object
       properties:
         tags:
-          type: object
-          additionalProperties:
-            type: string
+          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
index df5d922..64431af 100644
--- a/reference/api-reference/teams.md
+++ b/reference/api-reference/teams.md
@@ -1,6 +1,12 @@
 # Teams
 
-You can create, edit, and delete Teams via Cloudthread's API.
+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
 
@@ -8,13 +14,15 @@ You can create, edit, and delete Teams via Cloudthread's API.
 [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
+## 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)
@@ -32,25 +40,20 @@ You can create, edit, and delete Teams via Cloudthread's API.
 [https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml](https://raw.githubusercontent.com/cloudthread/docs-api/main/cldthrd_api.yaml)
 {% endswagger %}
 
-## Teams Assign Members
+## 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 Remove Members
+## 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
+## 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 %}
-
-
-{% hint style="info" %}
-**Good to know:** All the methods shown below are synced to an example Swagger file URL and are kept up to date automatically with changes to the API.
-{% endhint %}
diff --git a/reference/api-reference/users.md b/reference/api-reference/users.md
index fb4b187..e5a0fe3 100644
--- a/reference/api-reference/users.md
+++ b/reference/api-reference/users.md
@@ -1,14 +1,9 @@
 # Users
 
-You can fetch all users from the Cloudthread API to assign team members.
+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 %}
-
-
-{% 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 %}