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