openapi: 3.0.2
info:
  title: Interos Groups Watchtower API
  version: 1.0.0
  description: This API uses location data provided by https://geocode.earth/
  x-logo: https://www.interos.ai/wp-content/uploads/2019/12/logo_blue-black-1.png
servers:
- url: https://api.interos.ai
security:
- Interos API Key: []
- Interos Customer ID: []
tags:
- name: Watchtower
paths:
  /v1/custom_fields:
    get:
      summary: Get Custom Fields
      description: Retrieves a paginated list of custom fields.
      tags:
      - Watchtower
      operationId: get_custom_fields_custom_fields_get
      parameters:
      - required: false
        schema:
          title: Is Scenario
          type: boolean
        name: is_scenario
        in: query
      - required: false
        schema:
          title: Id
          type: array
          items:
            type: string
            format: uuid
        name: id
        in: query
      - required: false
        schema:
          title: Slug
          type: array
          items:
            type: string
        name: slug
        in: query
      - description: 'Used to limit the number of records returned. Default: 25. Max: 50'
        required: false
        schema:
          title: Limit
          maximum: 50.0
          exclusiveMinimum: 0.0
          type: integer
          description: 'Used to limit the number of records returned. Default: 25. Max: 50'
          default: 25
        name: limit
        in: query
      - description: Identifies where to start the pagination block and should not be sent on the initial request.
        required: false
        schema:
          title: Next
          type: string
          description: Identifies where to start the pagination block and should not be sent on the initial request.
        name: next
        in: query
      - description: Return total number of affected records. Only valid on the initial request.
        required: false
        schema:
          title: Return Count
          type: boolean
          description: Return total number of affected records. Only valid on the initial request.
          default: false
        name: return_count
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APICustomFieldsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/organizations/static_custom_fields/values:
    post:
      summary: Post Organizations Static Custom Fields Values
      description: Set static custom field values for multiple organizations
      tags:
      - Watchtower
      operationId: post_organizations_static_custom_fields_values_organizations_static_custom_fields_values_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostOrganizationsStaticCustomFieldsValuesRequest'
        required: true
      responses:
        '200':
          description: Succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostOrganizationsStaticCustomFieldsValuesResponse'
        '400':
          description: Bad Request Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/scenarios/watchlists/{watchlist_id}/organizations:
    get:
      summary: Get Watchlist Organizations
      description: Retrieves a paginated list of organizations for a watchlist. Response includes groups and scenario links for each organization, as well as full scenario and custom field details as reference data.
      tags:
      - Watchtower
      operationId: get_watchlist_organizations_scenarios_watchlists__watchlist_id__organizations_get
      parameters:
      - required: true
        schema:
          title: Watchlist Id
          type: string
        name: watchlist_id
        in: path
      - required: false
        schema:
          title: Search Term
          type: string
        name: search_term
        in: query
      - required: false
        schema:
          title: Scenario Ids
          type: array
          items:
            type: string
        name: scenario_ids
        in: query
      - required: false
        schema:
          title: Match All Scenarios
          type: boolean
          default: false
        name: match_all_scenarios
        in: query
      - required: false
        schema:
          title: Organization Ids
          type: array
          items:
            type: string
        name: organization_ids
        in: query
      - required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ScenarioOrganizationStatus'
        name: status
        in: query
      - required: false
        schema:
          $ref: '#/components/schemas/ScenarioActivity'
        name: scen_activity
        in: query
      - description: 'Used to limit the number of records returned. Default: 25. Max: 50'
        required: false
        schema:
          title: Limit
          maximum: 50.0
          exclusiveMinimum: 0.0
          type: integer
          description: 'Used to limit the number of records returned. Default: 25. Max: 50'
          default: 25
        name: limit
        in: query
      - description: Identifies where to start the pagination block and should not be sent on the initial request.
        required: false
        schema:
          title: Next
          type: string
          description: Identifies where to start the pagination block and should not be sent on the initial request.
        name: next
        in: query
      - description: Return total number of affected records. Only valid on the initial request.
        required: false
        schema:
          title: Return Count
          type: boolean
          description: Return total number of affected records. Only valid on the initial request.
          default: false
        name: return_count
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedListWithReferenceData_WatchlistOrganization__GetOrgsWithScenariosForWatchlistReferenceData_'
        '404':
          description: Watchlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CustomFieldDataElementValue:
      title: CustomFieldDataElementValue
      required:
      - field_slug
      type: object
      properties:
        data_element_type:
          title: Data Element Type
          enum:
          - custom_field
          type: string
          default: custom_field
        field_slug:
          title: Field Slug
          type: string
        value:
          title: Value
          anyOf:
          - type: string
          - type: boolean
          - type: integer
          - type: number
          - $ref: '#/components/schemas/EntityTableFieldValue'
    RiskFactorCodes:
      title: RiskFactorCodes
      enum:
      - geopolitical
      - finance
      - cyber
      - esg
      - operations
      - restrictions
      - catastrophic
      type: string
      description: An enumeration.
    APICustomFieldsResponse:
      title: APICustomFieldsResponse
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/APICustomField'
          default: []
        total_count:
          title: Total Count
          type: integer
        next:
          title: Next
          type: string
    EntityTableFieldValue:
      title: EntityTableFieldValue
      required:
      - column_slugs
      - rows
      type: object
      properties:
        column_slugs:
          title: Column Slugs
          type: array
          items:
            type: string
          description: The slugs of the columns. The ordering of the slugs derives the ordering of cell values within the rows.
        rows:
          title: Rows
          type: array
          items:
            $ref: '#/components/schemas/EntityTableFieldValueRow'
          description: The rows making up this table value.
    ScenarioOrganizationLinkCurrentDetectionDetails:
      title: ScenarioOrganizationLinkCurrentDetectionDetails
      required:
      - contributing_data_elements
      type: object
      properties:
        contributing_data_elements:
          title: Contributing Data Elements
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/CustomFieldDataElementValue'
            - $ref: '#/components/schemas/AttributeDataElementValue'
            - $ref: '#/components/schemas/RiskSubfactorScoreDataElementValue'
            - $ref: '#/components/schemas/RiskFactorScoreDataElementValue'
          description: The data elements that are contributing to this organization triggering this scenario.
    Scenario:
      title: Scenario
      required:
      - scenario_id
      - scenario_name
      - backing_custom_field_id
      type: object
      properties:
        scenario_id:
          title: Scenario Id
          type: string
          format: uuid
        scenario_name:
          title: Scenario Name
          type: string
        scenario_description:
          title: Scenario Description
          type: string
        backing_custom_field_id:
          title: Backing Custom Field Id
          type: string
          format: uuid
    PostStaticCustomFieldValue:
      title: PostStaticCustomFieldValue
      type: object
      properties:
        value:
          title: Value
    WatchlistOrganization:
      title: WatchlistOrganization
      required:
      - organization_id
      - priority_value
      - groups
      - scenario_links
      - data_element_values
      type: object
      properties:
        organization_id:
          title: Organization Id
          type: string
          format: uuid
        organization_name:
          title: Organization Name
          type: string
        priority_value:
          title: Priority Value
          type: integer
        groups:
          title: Groups
          type: array
          items:
            $ref: '#/components/schemas/GroupWithOrgTiers'
        scenario_links:
          title: Scenario Links
          type: array
          items:
            $ref: '#/components/schemas/ScenarioOrganizationLink'
        data_element_values:
          title: Data Element Values
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/CustomFieldDataElementValue'
            - $ref: '#/components/schemas/AttributeDataElementValue'
            - $ref: '#/components/schemas/RiskSubfactorScoreDataElementValue'
            - $ref: '#/components/schemas/RiskFactorScoreDataElementValue'
          description: Values this organization has for the data elements used by watchlist columns.
    ScenarioOrganizationLink:
      title: ScenarioOrganizationLink
      required:
      - scenario_id
      - organization_id
      - first_detected
      - status_updated
      - most_recent_positive_detection
      type: object
      properties:
        scenario_id:
          title: Scenario ID
          type: string
          description: The ID of the scenario.
          format: uuid
        organization_id:
          title: Organization ID
          type: string
          description: The ID of the organization.
          format: uuid
        first_detected:
          title: First Detected
          type: string
          description: The date and time this organization was first detected as triggering this scenario.
          format: date-time
        status_updated:
          title: Status Updated
          type: string
          description: The date and time this organization given its current status for this scenario.
          format: date-time
        most_recent_positive_detection:
          title: Most Recent Positive Detection
          type: string
          description: The date and time this organization was most recently detected as triggering this scenario.
          format: date-time
        most_recent_negative_detection:
          title: Most Recent Negative Detection
          type: string
          description: The date and time this organization was most recently detected as not triggering this scenario.
          format: date-time
        contributing_variables_last_updated:
          title: Contributing Variables Last Updated
          type: string
          description: The date and time this organization most recently had a change in the variables that contribute to this scenario detection.
          format: date-time
        has_had_current_trigger_state_since:
          title: Has Had Current Trigger state since
          type: string
          description: The date and time this organization last changed from triggering this scenario to not triggering, or vice versa.
          format: date-time
        status:
          title: Status
          allOf:
          - $ref: '#/components/schemas/ScenarioOrganizationStatus'
          description: Status of this organization for this scenario.
        current_detection_details:
          title: Current Detection Details
          allOf:
          - $ref: '#/components/schemas/ScenarioOrganizationLinkCurrentDetectionDetails'
          description: Information about the current detection. Null if the organization is not currently triggering this scenario.
    PostOrganizationsStaticCustomFieldsValuesValidationError:
      title: PostOrganizationsStaticCustomFieldsValuesValidationError
      required:
      - message
      - type
      type: object
      properties:
        message:
          title: Message
          type: string
        type:
          title: Type
          type: string
        field_index:
          title: Field Index
          type: integer
    AttributeDataElementValue:
      title: AttributeDataElementValue
      required:
      - attribute_key
      type: object
      properties:
        data_element_type:
          title: Data Element Type
          enum:
          - attribute
          type: string
          default: attribute
        attribute_key:
          title: Attribute Key
          type: string
        value:
          title: Value
          anyOf:
          - type: string
          - type: boolean
          - type: integer
          - type: number
          - $ref: '#/components/schemas/EntityTableFieldValue'
        formatted_value:
          title: Formatted Value
          type: string
    FieldType:
      title: FieldType
      enum:
      - BOOLEAN
      - DATE
      - DATE_TIME
      - DECIMAL
      - DYNAMIC_BOOLEAN
      - DYNAMIC_DECIMAL
      - DYNAMIC_INTEGER
      - DYNAMIC_PRIORITY
      - DYNAMIC_TEXT
      - INTEGER
      - LONG_TEXT
      - MULTI_SELECT
      - SHORT_TEXT
      - SINGLE_SELECT
      - TABLE
      description: An enumeration.
    RiskFactorScoreDataElementValue:
      title: RiskFactorScoreDataElementValue
      required:
      - risk_factor_key
      type: object
      properties:
        data_element_type:
          title: Data Element Type
          enum:
          - risk_factor_score
          type: string
          default: risk_factor_score
        risk_factor_key:
          $ref: '#/components/schemas/RiskFactorCodes'
        value:
          title: Value
          type: integer
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    CustomField:
      title: CustomField
      required:
      - custom_field_id
      - field_title
      - field_type
      - field_slug
      type: object
      properties:
        custom_field_id:
          title: Custom Field Id
          type: string
          format: uuid
        field_title:
          title: Field Title
          type: string
        field_type:
          title: Field Type
          type: string
        field_slug:
          title: Field Slug
          type: string
        description:
          title: Description
          type: string
        metadata:
          title: Metadata
          type: object
        field_settings:
          title: Field Settings
          type: object
    PaginatedListWithReferenceData_WatchlistOrganization__GetOrgsWithScenariosForWatchlistReferenceData_:
      title: PaginatedListWithReferenceData[WatchlistOrganization, GetOrgsWithScenariosForWatchlistReferenceData]
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/WatchlistOrganization'
          default: []
        reference_data:
          title: Reference Data
          allOf:
          - $ref: '#/components/schemas/GetOrgsWithScenariosForWatchlistReferenceData'
          default: {}
        total_count:
          title: Total Count
          type: integer
        next:
          title: Next
          type: string
    PostOrganizationsStaticCustomFieldsValuesRequest:
      title: PostOrganizationsStaticCustomFieldsValuesRequest
      required:
      - custom_field_slugs
      - organizations
      type: object
      properties:
        custom_field_slugs:
          title: Custom Field Slugs
          maxItems: 50
          minItems: 1
          type: array
          items:
            type: string
        organizations:
          title: Organizations
          maxItems: 1000
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/PostOrganizationWithStaticCustomFieldValues'
    PostOrganizationsStaticCustomFieldsValuesInvalidOrganization:
      title: PostOrganizationsStaticCustomFieldsValuesInvalidOrganization
      required:
      - organization_id
      - validation_errors
      type: object
      properties:
        organization_id:
          title: Organization Id
          type: string
          format: uuid
        validation_errors:
          title: Validation Errors
          type: array
          items:
            $ref: '#/components/schemas/PostOrganizationsStaticCustomFieldsValuesValidationError'
    GetOrgsWithScenariosForWatchlistReferenceData:
      title: GetOrgsWithScenariosForWatchlistReferenceData
      required:
      - scenarios
      - custom_fields
      - attributes
      - risk_subfactors
      type: object
      properties:
        scenarios:
          title: Scenarios
          type: array
          items:
            $ref: '#/components/schemas/Scenario'
        custom_fields:
          title: Custom Fields
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
        attributes:
          title: Attributes
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        risk_subfactors:
          title: Risk Subfactors
          type: array
          items:
            $ref: '#/components/schemas/RiskSubfactor'
    RiskSubfactor:
      title: RiskSubfactor
      required:
      - risk_subfactor_key
      type: object
      properties:
        risk_subfactor_key:
          title: Risk Subfactor Key
          type: string
        risk_subfactor_name:
          title: Risk Subfactor Name
          type: string
        risk_subfactor_segment:
          title: Risk Subfactor Segment
          type: string
        risk_subfactor_description:
          title: Risk Subfactor Description
          type: string
        risk_factor_key:
          title: Risk Factor Key
          type: string
    ScenarioOrganizationStatus:
      title: ScenarioOrganizationStatus
      enum:
      - open
      - in_progress
      - closed
      description: An enumeration.
    RiskSubfactorScoreDataElementValue:
      title: RiskSubfactorScoreDataElementValue
      required:
      - risk_subfactor_key
      type: object
      properties:
        data_element_type:
          title: Data Element Type
          enum:
          - risk_subfactor_score
          type: string
          default: risk_subfactor_score
        risk_subfactor_key:
          title: Risk Subfactor Key
          type: string
        value:
          title: Value
          type: integer
    GroupWithOrgTiers:
      title: GroupWithOrgTiers
      required:
      - group_id
      - group_name
      - tiers
      type: object
      properties:
        group_id:
          title: Group Id
          type: string
          format: uuid
        group_name:
          title: Group Name
          type: string
        tiers:
          title: Tiers
          type: array
          items:
            type: integer
    PostOrganizationWithStaticCustomFieldValues:
      title: PostOrganizationWithStaticCustomFieldValues
      required:
      - organization_id
      - values
      type: object
      properties:
        organization_id:
          title: Organization Id
          type: string
          format: uuid
        values:
          title: Values
          maxItems: 50
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/PostStaticCustomFieldValue'
    PostOrganizationsStaticCustomFieldsValuesResponse:
      title: PostOrganizationsStaticCustomFieldsValuesResponse
      required:
      - updated_organization_ids
      - invalid_organizations
      type: object
      properties:
        updated_organization_ids:
          title: Updated Organization Ids
          type: array
          items:
            type: string
            format: uuid
        invalid_organizations:
          title: Invalid Organizations
          type: array
          items:
            $ref: '#/components/schemas/PostOrganizationsStaticCustomFieldsValuesInvalidOrganization'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    EntityTableFieldValueRow:
      title: EntityTableFieldValueRow
      required:
      - cell_values
      type: object
      properties:
        cell_values:
          title: Cell Values
          type: array
          items:
            anyOf:
            - type: string
            - type: boolean
            - type: integer
            - type: number
          description: The values this row has for each cell.
    APICustomField:
      title: APICustomField
      required:
      - custom_field_id
      - field_title
      - field_type
      - field_slug
      type: object
      properties:
        custom_field_id:
          title: Custom Field Id
          type: string
          format: uuid
        field_title:
          title: Field Title
          type: string
        field_type:
          $ref: '#/components/schemas/FieldType'
        field_slug:
          title: Field Slug
          type: string
        description:
          title: Description
          type: string
        metadata:
          title: Metadata
          type: object
          additionalProperties:
            type: string
        scenario_id:
          title: Scenario Id
          type: string
          format: uuid
        category_id:
          title: Category Id
          type: string
          format: uuid
        category_name:
          title: Category Name
          type: string
    ScenarioActivity:
      title: ScenarioActivity
      enum:
      - ALL
      - POSITIVE
      - NEGATIVE
      description: An enumeration.
    Attribute:
      title: Attribute
      required:
      - attribute_key
      type: object
      properties:
        attribute_key:
          title: Attribute Key
          type: string
        attribute_name:
          title: Attribute Name
          type: string
        attribute_description:
          title: Attribute Description
          type: string
        risk_subfactor_key:
          title: Risk Subfactor Key
          type: string
    HTTPError:
      properties:
        detail:
          title: Detail
          type: string
      required:
      - detail
      title: HTTPError
      type: object
  securitySchemes:
    Interos API Key:
      in: header
      name: x-api-key
      type: apiKey
    Interos Customer ID:
      in: header
      name: x-customer-id
      type: apiKey