Mantic Scenarios API

openapi: 3.2.0
info:
  title: Fast Scenarios API
  version: 0.1.0
tags:
- name: Scenarios
paths:
  /scenarios/{scenario_id}/cdfs:
    get:
      tags:
      - Scenarios
      summary: Get Scenario Cdfs
      operationId: get_scenario_cdfs_scenarios__scenario_id__cdfs_get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: scenario_id
        in: path
        required: true
        schema:
          type: integer
          title: Scenario Id
      - name: ticks
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticks
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScenarioCdfsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /beta/scenarios/{scenario_id}/cdfs:
    get:
      tags:
      - Scenarios
      summary: Get Scenario Cdfs
      operationId: get_scenario_cdfs_beta_scenarios__scenario_id__cdfs_get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: scenario_id
        in: path
        required: true
        schema:
          type: integer
          title: Scenario Id
      - name: ticks
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticks
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScenarioCdfsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/questions/{question_id}/scenario-suggestions:
    get:
      tags:
      - Scenarios
      summary: Get Scenario Suggestions
      description: 'The base question''s pooled candidates the viewer may add, building the pool when due.


        Suggestions backed by a question outside the viewer''s reach, already in their organisation''s

        scenarios, or past their date are left out; so are new conditions when the base belongs to

        another organisation, since minting would create a question the viewer cannot use.'
      operationId: get_scenario_suggestions_webapp_questions__question_id__scenario_suggestions_get
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: question_id
        in: path
        required: true
        schema:
          type: integer
          title: Question Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioSuggestionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/questions/{question_id}/scenario-suggestions/more:
    post:
      tags:
      - Scenarios
      summary: Request More Scenario Suggestions
      description: 'Start a candidates-only run now, however fresh the pool, and answer as the suggestions

        read does, building.


        A generation already in flight is waited for instead. Otherwise a request is refused with

        429 until the newest candidates-only run is ``REQUESTED_POOL_RUN_AFTER`` old, or

        ``FAILED_POOL_BACKOFF`` old when it failed (see :func:`requested_pool_run_wait`).'
      operationId: request_more_scenario_suggestions_webapp_questions__question_id__scenario_suggestions_more_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: question_id
        in: path
        required: true
        schema:
          type: integer
          title: Question Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioSuggestionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/questions/{question_id}/scenarios:
    post:
      tags:
      - Scenarios
      summary: Add Scenario
      description: 'Add a pooled suggestion, or a question the caller names, to the caller''s organisation''s

        scenarios, and report or start its compute.


        A suggestion backed by an existing question adds exactly that question; a new one is matched

        or minted under the base''s owner, as generation does. A named question must be one the

        caller may build scenarios from. Adding one the organisation already holds answers with that

        scenario as it stands, running it when asked, and sets its auto-run only when the request

        gives one.'
      operationId: add_scenario_webapp_questions__question_id__scenarios_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: question_id
        in: path
        required: true
        schema:
          type: integer
          title: Question Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddScenarioRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddScenarioResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/questions/{question_id}/scenarios/preview:
    post:
      tags:
      - Scenarios
      summary: Preview Scenario
      description: 'A question the caller names as a condition on this one: the range or window its threshold

        may take, a suggested threshold, and the probability each threshold gives. Writes nothing.


        Refused with 409 as :func:`add_scenario` refuses the question, before checking whether the

        forecast weighs it, which only the add does.'
      operationId: preview_scenario_webapp_questions__question_id__scenarios_preview_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: question_id
        in: path
        required: true
        schema:
          type: integer
          title: Question Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConditionPreviewRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConditionPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/scenarios/{scenario_id}/run:
    post:
      tags:
      - Scenarios
      summary: Run Scenario
      description: 'Compute a scenario the caller''s organisation holds, unless it is current or already

        underway.'
      operationId: run_scenario_webapp_scenarios__scenario_id__run_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: scenario_id
        in: path
        required: true
        schema:
          type: integer
          title: Scenario Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunScenarioResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/scenarios/{scenario_id}:
    patch:
      tags:
      - Scenarios
      summary: Update Scenario
      description: Turn auto-run on or off for a scenario the caller's organisation holds.
      operationId: update_scenario_webapp_scenarios__scenario_id__patch
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: scenario_id
        in: path
        required: true
        schema:
          type: integer
          title: Scenario Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScenarioRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateScenarioResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Scenarios
      summary: Remove Scenario
      description: 'Remove the scenario from the caller''s organisation''s scenarios.


        Closes only the organisation''s membership and withdraws its own pending run request. The shared

        scenario, other organisations'' and Mantic''s memberships and run requests, and its forecasts

        are kept.'
      operationId: remove_scenario_webapp_scenarios__scenario_id__delete
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: scenario_id
        in: path
        required: true
        schema:
          type: integer
          title: Scenario Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AddScenarioRequest:
      properties:
        candidate:
          anyOf:
          - $ref: '#/components/schemas/CandidateRef'
          - type: 'null'
        condition_question_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Condition Question Id
        threshold:
          anyOf:
          - $ref: '#/components/schemas/NumericalThreshold'
          - $ref: '#/components/schemas/DateThreshold'
          - type: 'null'
          title: Threshold
        run_now:
          type: boolean
          title: Run Now
          default: false
        auto_run:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Auto Run
      additionalProperties: false
      type: object
      title: AddScenarioRequest
    ScenarioSuggestion:
      properties:
        run_id:
          type: integer
          title: Run Id
        index:
          type: integer
          title: Index
        condition_statement:
          type: string
          title: Condition Statement
        event_label:
          type: string
          title: Event Label
        resolution_event:
          type: string
          title: Resolution Event
        expected_resolution_date:
          type: string
          title: Expected Resolution Date
        causal_rationale:
          type: string
          title: Causal Rationale
        condition_output_type:
          type: string
          title: Condition Output Type
        threshold_comparator:
          anyOf:
          - type: string
          - type: 'null'
          title: Threshold Comparator
        threshold_numeric:
          anyOf:
          - type: number
          - type: 'null'
          title: Threshold Numeric
        threshold_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Threshold Date
        numerical_range_min:
          anyOf:
          - type: number
          - type: 'null'
          title: Numerical Range Min
        numerical_range_max:
          anyOf:
          - type: number
          - type: 'null'
          title: Numerical Range Max
        numerical_unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Numerical Unit
        short_label_if_yes:
          anyOf:
          - type: string
          - type: 'null'
          title: Short Label If Yes
        short_label_if_no:
          anyOf:
          - type: string
          - type: 'null'
          title: Short Label If No
        existing_question_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Existing Question Id
      type: object
      required:
      - run_id
      - index
      - condition_statement
      - event_label
      - resolution_event
      - expected_resolution_date
      - causal_rationale
      - condition_output_type
      title: ScenarioSuggestion
      description: A pooled candidate the viewer may add to their scenarios.
    ScenarioSuggestionsResponse:
      properties:
        candidates:
          items:
            $ref: '#/components/schemas/ScenarioSuggestion'
          type: array
          title: Candidates
        status:
          type: string
          enum:
          - ready
          - building
          title: Status
        latest_run_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Run Status
        retry_after:
          anyOf:
          - type: integer
          - type: 'null'
          title: Retry After
      type: object
      required:
      - candidates
      - status
      title: ScenarioSuggestionsResponse
    GetScenarioCdfsResponse:
      properties:
        outcomes:
          additionalProperties:
            $ref: '#/components/schemas/GetScenarioOutcomeCdf'
          type: object
          title: Outcomes
      type: object
      required:
      - outcomes
      title: GetScenarioCdfsResponse
    UpdateScenarioRequest:
      properties:
        auto_run:
          type: boolean
          title: Auto Run
      additionalProperties: false
      type: object
      required:
      - auto_run
      title: UpdateScenarioRequest
    DateThreshold:
      properties:
        comparator:
          type: string
          title: Comparator
        date:
          type: string
          title: Date
      additionalProperties: false
      type: object
      required:
      - comparator
      - date
      title: DateThreshold
      description: One threshold on a date question, as an ISO calendar date with no time of day.
    NumericalThreshold:
      properties:
        comparator:
          type: string
          title: Comparator
        value:
          type: number
          title: Value
      additionalProperties: false
      type: object
      required:
      - comparator
      - value
      title: NumericalThreshold
      description: One threshold on a numerical question.
    GetScenarioOutcomeCdf:
      properties:
        cdf:
          $ref: '#/components/schemas/ForecastCdf_float_'
      type: object
      required:
      - cdf
      title: GetScenarioOutcomeCdf
    UpdateScenarioResponse:
      properties:
        instance_id:
          type: integer
          title: Instance Id
        membership_id:
          type: integer
          title: Membership Id
        auto_run:
          type: boolean
          title: Auto Run
      type: object
      required:
      - instance_id
      - membership_id
      - auto_run
      title: UpdateScenarioResponse
    AddScenarioResponse:
      properties:
        instance_id:
          type: integer
          title: Instance Id
        membership_id:
          type: integer
          title: Membership Id
        outcome:
          $ref: '#/components/schemas/AddOutcome'
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
      type: object
      required:
      - instance_id
      - membership_id
      - outcome
      title: AddScenarioResponse
    ConditionThresholdPreview:
      properties:
        p_a:
          anyOf:
          - type: number
          - type: 'null'
          title: P A
        expected_settles_on:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Expected Settles On
        unavailable_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Unavailable Reason
        listed:
          type: boolean
          title: Listed
          default: false
      type: object
      title: ConditionThresholdPreview
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RunScenarioResponse:
      properties:
        instance_id:
          type: integer
          title: Instance Id
        outcome:
          $ref: '#/components/schemas/AddOutcome'
      type: object
      required:
      - instance_id
      - outcome
      title: RunScenarioResponse
    ConditionPreviewRequest:
      properties:
        condition_question_id:
          type: integer
          title: Condition Question Id
        thresholds:
          items:
            anyOf:
            - $ref: '#/components/schemas/NumericalThreshold'
            - $ref: '#/components/schemas/DateThreshold'
          type: array
          title: Thresholds
      additionalProperties: false
      type: object
      required:
      - condition_question_id
      title: ConditionPreviewRequest
    MembershipResponse:
      properties:
        membership_id:
          type: integer
          title: Membership Id
        instance_id:
          type: integer
          title: Instance Id
        position:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Position
        detached:
          type: boolean
          title: Detached
          default: false
      type: object
      required:
      - membership_id
      - instance_id
      title: MembershipResponse
    ConditionPreviewResponse:
      properties:
        question_id:
          type: integer
          title: Question Id
        title:
          type: string
          title: Title
        output_type:
          type: string
          enum:
          - binary
          - numerical
          - date
          title: Output Type
        resolution_time:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Resolution Time
        range_min:
          anyOf:
          - type: number
          - type: 'null'
          title: Range Min
        range_max:
          anyOf:
          - type: number
          - type: 'null'
          title: Range Max
        unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit
        window_start:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Window Start
        window_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Window End
        suggested_threshold:
          anyOf:
          - $ref: '#/components/schemas/NumericalThreshold'
          - $ref: '#/components/schemas/DateThreshold'
          - type: 'null'
          title: Suggested Threshold
        thresholds:
          items:
            $ref: '#/components/schemas/ConditionThresholdPreview'
          type: array
          title: Thresholds
      type: object
      required:
      - question_id
      - title
      - output_type
      - thresholds
      title: ConditionPreviewResponse
    ForecastCdf_float_:
      additionalProperties:
        type: number
      type: object
    AddOutcome:
      type: string
      enum:
      - reused
      - queued
      - in_flight
      - awaiting_pa
      - not_started
      title: AddOutcome
      description: What adding a scenario to a set did about computing it.
    CandidateRef:
      properties:
        run_id:
          type: integer
          title: Run Id
        index:
          type: integer
          minimum: 0.0
          title: Index
      type: object
      required:
      - run_id
      - index
      title: CandidateRef
  securitySchemes:
    OAuth2AuthorizationCodeBearer:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: https://app.mantic.com/auth/oauth2/authorize
          tokenUrl: https://app.mantic.com/auth/oauth2/token