Prevedere Workbench API

openapi: 3.2.0
info:
  title: Board Foresight API - V1 Alert Workbench API
  description: 'Workbenches are a powerful feature in the Board Foresight application that allow users to organize and analyze data through indicators. They enable the creation of models by selecting primary and additional indicators, which can be further adjusted and managed.


    Using Workbenches endpoints you can

    - Retrieve the workbench information for the given workbench ID

    - Update or add an indicator to the existing workbench specified by the given ID

    - Retrieve the workbench series information for the given workbench ID and categories

    - Retrieves the list of accessible workbenches for the company'
  version: v1
servers:
- url: https://api.prevedere.com
  description: Base URL declared by the provider in apis.yml (roadmap#122).
security:
- api key: []
tags:
- name: Workbench
  description: 'Workbenches are a powerful feature in the Board Foresight application that allow users to organize and analyze data through indicators. They enable the creation of models by selecting primary and additional indicators, which can be further adjusted and managed.


    Using Workbenches endpoints you can

    - Retrieve the workbench information for the given workbench ID

    - Update or add an indicator to the existing workbench specified by the given ID

    - Retrieve the workbench series information for the given workbench ID and categories

    - Retrieves the list of accessible workbenches for the company'
paths:
  /workbench/{WorkbenchId}:
    get:
      tags:
      - Workbench
      description: Retrieve the workbench information for the given workbench id
      parameters:
      - name: WorkbenchId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Workbench'
            application/json:
              schema:
                $ref: '#/components/schemas/Workbench'
            text/json:
              schema:
                $ref: '#/components/schemas/Workbench'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '429':
          description: If the user has sent too many requests
  /workbench/update:
    put:
      tags:
      - Workbench
      description: Update or add an indicator to the existing workbench specified by the given ID.
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateWorkbenchIndicatorRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkbenchIndicatorRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkbenchIndicatorRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateWorkbenchIndicatorRequest'
      responses:
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseMessage'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseMessage'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseMessage'
        '429':
          description: If the user has sent too many requests
  /workbench/series/{WorkbenchId}:
    get:
      tags:
      - Workbench
      description: Retrieve the workbench series information for the given workbench id and categories
      parameters:
      - name: WorkbenchId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: includeHidden
        in: query
        schema:
          type: boolean
      - name: categoryNames
        in: query
        schema:
          type: array
          items:
            type: string
      - name: categoryIds
        in: query
        schema:
          type: array
          items:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/WorkbenchSeries'
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbenchSeries'
            text/json:
              schema:
                $ref: '#/components/schemas/WorkbenchSeries'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
            text/json:
              schema:
                $ref: '#/components/schemas/ResponseMessage'
        '429':
          description: If the user has sent too many requests
  /workbenches:
    get:
      tags:
      - Workbench
      description: Retrieves the list of accessible workbenches for the company
      parameters:
      - name: Query
        in: query
        required: true
        schema:
          type: string
          default: '*'
      - name: Page
        in: query
        schema:
          type: integer
          format: int32
          default: 0
      - name: PageSize
        in: query
        schema:
          type: integer
          format: int32
          default: 25
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/WorkbenchInfoSearchResults'
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbenchInfoSearchResults'
            text/json:
              schema:
                $ref: '#/components/schemas/WorkbenchInfoSearchResults'
        '429':
          description: If the user has sent too many requests
components:
  schemas:
    IndicatorType:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      type: integer
      format: int32
    Provider:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        id:
          type: string
          format: uuid
        source:
          type:
          - string
          - 'null'
      additionalProperties: false
    DisplayInformation:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: The display name to be used in the application. Limited to 50 characters.
        description:
          type:
          - string
          - 'null'
          description: The description to be shown in the application. Limited to 1,000 characters.
        color:
          type:
          - string
          - 'null'
          description: The color to use in the application. Must be a valid hex color code.
        category:
          type:
          - string
          - 'null'
          description: The category of the indicator. Limited to 1,000 characters.
      additionalProperties: false
    Transformation:
      type: object
      properties:
        order:
          type: integer
          format: int32
        required:
          type: boolean
      additionalProperties: false
    IndicatorCorrelation:
      type: object
      properties:
        correlationCoefficient:
          type: number
          format: double
        rSquared:
          type: number
          format: double
        proCyclic:
          type: number
          format: double
        counterCyclic:
          type: number
          format: double
      additionalProperties: false
    AggregationMethod:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      type: integer
      format: int32
    Classification:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      type: integer
      format: int32
    WorkbenchInfoSearchResults:
      type: object
      properties:
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WorkbenchInfo'
          readOnly: true
        page:
          type: integer
          format: int32
          readOnly: true
        pageSize:
          type: integer
          format: int32
          readOnly: true
        totalResults:
          type: integer
          format: int64
          readOnly: true
      additionalProperties: false
    Seasonality:
      enum:
      - 0
      - 1
      - 999
      type: integer
      format: int32
    WorkbenchIndicatorSeries:
      type: object
      properties:
        provider:
          type: string
          format: uuid
        providerId:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
          description: Indicator name.
        offset:
          type: integer
          description: The offset applied to the indicator in the workbench.
          format: int32
        incompatible:
          type: boolean
          description: If the indicator is compatible with the workbench's selected calculation and frequency.
        points:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Point'
          description: Indicator points converted to workbench frequency and calculation with offset.
        transformations:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Transformation'
          description: The transformations applied to the series and the order they were applied
      additionalProperties: false
    PeriodAlignment:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
    Workbench:
      type: object
      properties:
        id:
          type: string
          description: The id of the workbench.
          format: uuid
        name:
          type:
          - string
          - 'null'
          description: The name of the workbench.
        description:
          type:
          - string
          - 'null'
          description: The description of the workbench.
        created:
          type: string
          description: The timestamp in UTC for when the workbench was created.
          format: date-time
        owner:
          type:
          - string
          - 'null'
          description: The username of the owner of the workbench.
        lastModified:
          type: string
          description: The timestamp in UTC when the workbench was last saved.
          format: date-time
        frequency:
          type:
          - string
          - 'null'
          description: The frequency of the workbench in string format.
        calculation:
          type:
          - string
          - 'null'
          description: The calculation of the workbench in string format.
        primaryIndicator:
          $ref: '#/components/schemas/Indicator'
        indicators:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WorkbenchIndicator'
          description: A list of the indicators that are in the workbench. Includes hidden indicators as well.
        categories:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WorkbenchCategoryInfo'
          description: A list of the categories that are in the workbench.
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
          description: A list of tags that are assigned to the workbench.
        cutoffDate:
          type:
          - string
          - 'null'
          description: The cut off date of the workbench. This is used to front trim the workbench's dependent and independent variables.
          format: date-time
        calculatedStartDate:
          type: string
          description: The calculated common start date of the workbench.
          format: date-time
        endDate:
          type:
          - string
          - 'null'
          description: The cut off end date of the workbench.
          format: date-time
        url:
          type:
          - string
          - 'null'
          description: The url of the workbench.
        notes:
          type:
          - string
          - 'null'
          description: The notes of the workbench.
        notesLastModified:
          type:
          - string
          - 'null'
          description: The last modified date of the notes of the workbench.
          format: date-time
      additionalProperties: false
      description: This schema contains information about the Workbench, the dependent variable or Primary Indicator of the workbench under the Indicator subschema, and independent variables or Explanatory Indicators in the WorkbenchIndicator subschema.
    IndicatorKey:
      type: object
      properties:
        provider:
          type: string
          description: The ID of the provider for the indicator.
          format: uuid
        providerId:
          type:
          - string
          - 'null'
          description: The provider id of the indicator.
      additionalProperties: false
      description: The provider:providerId pair. This is used to identify an indicator in the system.
    ProviderAccess:
      enum:
      - 0
      - 1
      - 2
      type: integer
      format: int32
    Calculation:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      type: integer
      description: 'The transformation applied to the data.



        Possible options:



        None 1



        PeriodOverPeriod 2



        YearOverYear 3



        ThreePeriodYearOverYear 6'
      format: int32
    Point:
      type: object
      properties:
        value:
          type: number
          format: double
        date:
          type: string
          format: date-time
        annotation:
          type:
          - string
          - 'null'
        manuallyAdjusted:
          type: boolean
        isForecasted:
          type:
          - boolean
          - 'null'
      additionalProperties: false
    UpdateWorkbenchIndicatorRequest:
      type: object
      properties:
        indicatorProvider:
          type:
          - string
          - 'null'
          description: The provider's UUID for the indicator.
        indicatorProviderId:
          type:
          - string
          - 'null'
          description: The provider id of the indicator.
        workbenchId:
          type:
          - string
          - 'null'
          description: The workbench id to update or add the indicator to.
        offset:
          type:
          - integer
          - 'null'
          description: The offset to shift the indicator by. Defaults to 0.
          format: int32
        expectedSign:
          type:
          - string
          - 'null'
          description: 'The expected sign of the coefficient. Possible options are: Unspecified, Positive, Negative. Defaults to Unspecified.'
        locked:
          type:
          - boolean
          - 'null'
          description: Whether to lock the indicator for editing in the application. Defaults to False.
        visible:
          type:
          - boolean
          - 'null'
          description: Whether to show the indicator or hide it in the application. Defaults to True.
        displayInformation:
          $ref: '#/components/schemas/DisplayInformation'
      additionalProperties: false
    IndicatorDataSource:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
        dataSourceType:
          $ref: '#/components/schemas/IndicatorType'
      additionalProperties: false
    Indicator:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        aggregate:
          $ref: '#/components/schemas/AggregationMethod'
        calculation:
          $ref: '#/components/schemas/Calculation'
        color:
          type:
          - string
          - 'null'
        displayInformation:
          $ref: '#/components/schemas/DisplayInformation'
        count:
          type: integer
          format: int32
        created:
          type: string
          format: date-time
        startTime:
          type:
          - string
          - 'null'
          format: date-time
        endTime:
          type:
          - string
          - 'null'
          format: date-time
        transformedStartTime:
          type:
          - string
          - 'null'
          format: date-time
        transformedEndTime:
          type:
          - string
          - 'null'
          format: date-time
        frequency:
          $ref: '#/components/schemas/Frequency'
        deprecated:
          type: boolean
        deprecationReason:
          type:
          - string
          - 'null'
        lastModified:
          type: string
          format: date-time
        provider:
          $ref: '#/components/schemas/Provider'
        providerId:
          type:
          - string
          - 'null'
        seasonality:
          $ref: '#/components/schemas/Seasonality'
        source:
          type:
          - string
          - 'null'
        classification:
          $ref: '#/components/schemas/Classification'
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
        type:
          type:
          - string
          - 'null'
        units:
          type:
          - string
          - 'null'
        accessibility:
          $ref: '#/components/schemas/ProviderAccess'
        periodAlignment:
          $ref: '#/components/schemas/PeriodAlignment'
        path:
          type:
          - string
          - 'null'
        notes:
          type:
          - string
          - 'null'
        citation:
          type:
          - string
          - 'null'
        dataSources:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IndicatorDataSource'
        industryCodes:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IndustryCode'
        hasZeroVariance:
          type:
          - boolean
          - 'null'
        interval:
          type:
          - string
          - 'null'
        countryCode:
          type:
          - string
          - 'null'
      additionalProperties: false
    ResponseMessage:
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
    IndustryCode:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        code:
          type:
          - string
          - 'null'
      additionalProperties: false
    WorkbenchIndicator:
      type: object
      properties:
        indicator:
          $ref: '#/components/schemas/Indicator'
        offset:
          type: integer
          description: The offset applied to the indicator in the workbench.
          format: int32
        sort:
          type: integer
          description: The overall sort position of the indicator in the workbench.
          format: int32
        locked:
          type: boolean
          description: If the indicator is locked in the workbench.
        visible:
          type: boolean
          description: If the indicator is visible in the workbench.
        isLoggable:
          type: boolean
          description: If the indicator series trimmed to the workbench's dates are loggable.
        incompatible:
          type: boolean
          description: If the indicator is compatible with the workbench's selected calculation and frequency.
        correlation:
          $ref: '#/components/schemas/IndicatorCorrelation'
        expectedSign:
          type:
          - string
          - 'null'
          description: 'The user defined expected sign of the indicator in relation to the primary.

            Current values: Unspecified, Positive, Negative'
        transformations:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Transformation'
          description: The transformations applied to the indicator in the workbench.
      additionalProperties: false
    WorkbenchInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        created:
          type: string
          format: date-time
        lastModified:
          type: string
          format: date-time
        frequency:
          $ref: '#/components/schemas/Frequency'
        owner:
          type:
          - string
          - 'null'
        count:
          type: integer
          format: int32
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
      additionalProperties: false
    WorkbenchSeries:
      type: object
      properties:
        primaryIndicator:
          $ref: '#/components/schemas/WorkbenchIndicatorSeries'
        workbenchIndicators:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WorkbenchIndicatorSeries'
          description: Indicator series information for indicators on workbench.
      additionalProperties: false
    Frequency:
      enum:
      - 0
      - 1
      - 2
      - 4
      - 12
      - 52
      - 365
      - 1000
      type: integer
      description: 'The frequency of the data.



        Daily: 365



        Weekly: 52



        Monthly: 12



        Quarterly: 4



        SemiAnnual: 2



        Annual: 1'
      format: int32
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    WorkbenchCategoryInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
        sort:
          type: integer
          format: int32
        note:
          type:
          - string
          - 'null'
        indicators:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/IndicatorKey'
      additionalProperties: false
  securitySchemes:
    api_key:
      type: apiKey
      name: ApiKey
      in: query