swagger: "2.0"
info:
  title: Uncertainty API
  version: 1.0.0
  description: |
    ```plain {% title="Client ID" %}
    prod-nam-services-fdplan.slbservice.com
    prod-eu-services-fdplan.slbservice.com
    prod-au-services-fdplan.slbservice.com
    prod-id-services-fdplan.slbservice.com
    production-services-fdplan.slbservice.com
    ```

    The Uncertainty API exposes the ensembles, realizations, and per-realization
    results that FDPlan produces when a scenario or virtual scenario is evaluated.

    A study's uncertainty method controls how realizations are produced for each
    ensemble. With MonteCarlo, realizations are created automatically by Monte
    Carlo sampling of the input data sources, and the study's number of
    realizations controls how many are generated per scenario. With Deterministic,
    you provide the outcomes directly in the input data sources and choose which
    realizations to evaluate, for example a curated set of P10, P50, and P90 cases
    from an external domain study. Evaluation results are then presented as a range of
    outcomes that you can use to interpret uncertainty in the key performance
    indicators (KPIs) of decision alternatives.

    An ensemble is a collection of realizations produced for a single scenario or
    virtual scenario, scoped to a version of a workflow specification. Each
    realization pins one container reference per workflow-specification node so
    that downstream computations and visualizations read deterministic inputs and
    outputs.

    Use this API to retrieve an ensemble and its realizations, update an ensemble,
    read the per-realization indicator values produced by an evaluation, and read
    the computation-event log of a single realization.
  contact:
    name: SLB Customer Support for Digital
    url: https://customersupport.digital.slb.com
  x-product-id: FDPlan-Uncertainty-v1
host: api.delfi.slb.com
basePath: /fdplan/uncertainty
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /v1/ensembles/{id}:
    get:
      tags:
        - Ensembles
      summary: Get an ensemble
      description: |-
        Get an ensemble by its identifier, including the realizations it holds and
        the container references that each realization pins for every
        workflow-specification node.
      operationId: getEnsemble
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The identifier of the ensemble to get.
          name: id
          type: string
      responses:
        "200":
          description: The ensemble was retrieved successfully.
          schema:
            $ref: '#/definitions/Ensemble'
        "400":
          description: Invalid request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The ensemble was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      tags:
        - Ensembles
      summary: Update an ensemble
      description: |-
        Update an existing ensemble. The request body is a JSON Patch document, and
        only the replace operation is supported. Use it to change mutable fields,
        such as the realizations selected for evaluation.
      operationId: patchEnsemble
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The identifier of the ensemble to update.
          name: id
          type: string
        - description: The patches to apply to the ensemble. Only the replace operation is supported.
          name: patches
          in: body
          required: true
          schema:
            $ref: '#/definitions/PatchReq'
      responses:
        "200":
          description: The ensemble was updated successfully.
          schema:
            $ref: '#/definitions/Ensemble'
        "400":
          description: Invalid request body.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "403":
          description: The request is forbidden.
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The ensemble was not found.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v1/ensembles/{id}/realization-indicators:
    get:
      tags:
        - Results
      summary: Get realization indicators
      description: |-
        Get the per-realization indicator values produced by the evaluation of the
        ensemble. Each entry is keyed on a realization URI and groups its results by
        workflow-specification node address. Results are returned in pages controlled
        by offset and limit.
      operationId: getRealizationIndicators
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The identifier of the ensemble to get the realization indicators for.
          name: id
          type: string
          x-nullable: false
        - required: true
          in: query
          description: The number of realizations to skip before returning indicator results.
          name: offset
          type: integer
        - required: true
          in: query
          description: The maximum number of realizations for which to return indicator results after the offset.
          name: limit
          type: integer
          maximum: !!float 100
          minimum: !!float 1
      responses:
        "200":
          description: The realization indicators were retrieved successfully.
          schema:
            $ref: '#/definitions/RealizationIndicatorCollection'
        "400":
          description: Invalid request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The ensemble was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v1/realization-events:
    get:
      tags:
        - RealizationEvents
      summary: Get realization computation events
      description: |-
        Get the computation-event log for a single realization, identified by its
        URI. The log records each computation event, including its status,
        timestamp, and any generated log files.
      operationId: getRealizationEvents
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: query
          description: The URI of the realization to get the computation events for, for example 01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V.
          name: realizationURI
          type: string
          x-nullable: false
      responses:
        "200":
          description: The realization computation events were retrieved successfully.
          schema:
            $ref: '#/definitions/RealizationEvents'
        "400":
          description: Invalid request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The realization was not found.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
definitions:
  Ensemble:
    description: A collection of realizations produced for a single scenario or virtual scenario, scoped to a version of a workflow specification.
    required:
      - Id
      - workflowSpecId
      - version
      - realizations
    type: object
    properties:
      Id:
        description: The identifier of the ensemble.
        type: string
        example: 01J55M2WX7Z2NM9APBZ92NTNXY
        x-nullable: false
      version:
        format: int32
        description: The version of the ensemble.
        type: integer
        example: 3
        x-nullable: false
      workflowSpecId:
        $ref: '#/definitions/VersionId'
      realizations:
        description: The list of realizations associated with the ensemble.
        type: array
        items:
          $ref: '#/definitions/Realization'
      uncertaintyMethod:
        description: |-
          The methodology used to produce the realizations of the ensemble.
            - MonteCarlo - Realizations are created automatically by Monte Carlo sampling of the input data sources.
            - Deterministic - You provide the outcomes directly in the input data sources and choose which realizations to evaluate.
        default: MonteCarlo
        enum:
          - MonteCarlo
          - Deterministic
        type: string
        example: Deterministic
        x-nullable: false
      tags:
        description: The list of tags associated with the ensemble, such as StudyId and ScenarioId, that link it back to its scenario.
        type: array
        items:
          type: string
        example:
          - StudyId:01J55K2V6T77MRHGT1EZ60KMJ2
          - ScenarioId:01J55M2W4BJA6CGBRCNCK412XZ
      cases:
        description: The cases that the ensemble is associated with.
        type: array
        items:
          $ref: '#/definitions/Case'
    example:
      Id: 01J55M2WX7Z2NM9APBZ92NTNXY
      version: 3
      workflowSpecId:
        Id: 01E86SDT0780JMFFZHPBV3KVHV
        version: 1
      uncertaintyMethod: Deterministic
      tags:
        - StudyId:01J55K2V6T77MRHGT1EZ60KMJ2
        - ScenarioId:01J55M2W4BJA6CGBRCNCK412XZ
      cases: []
      realizations:
        - Id: 01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V
          status: Active
          version: 7
          containers:
            - address:
                type: DataTypeInput
                computationIndex: 0
                dataTypeIndex: 0
              dataType:
                Id: production-forecast
                version: 1
              labels:
                name: Field_Profile Upside Base.xlsx
              uri: 01J55K2V6T77MRHGT1EZ60KMJ2/containers/production-forecast/01J55M6YHKR877H2M7C31F3MQY
            - address:
                type: DataTypeOutput
                computationIndex: 0
                dataTypeIndex: 0
              dataType:
                Id: peep-output
                version: 1
              uri: 01J55K2V6T77MRHGT1EZ60KMJ2/containers/peep-output/01J55MH0FYX437F6RDK87BF434
  Realization:
    description: One concrete execution of a study's workflow specification for a given scenario or virtual scenario, that is, a single combination of inputs drawn from the ensemble.
    required:
      - Id
    type: object
    properties:
      Id:
        description: The URI of the realization, of the shape scenarioId/realizations/realizationId.
        type: string
        example: 01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V
        x-nullable: false
      status:
        description: |-
          The status of the realization.
            - Active - The realization is added for evaluation.
            - Proposed - The realization is a candidate that is not set for evaluation.
        enum:
          - Active
          - Proposed
        type: string
        example: Active
        x-nullable: false
      containers:
        description: The container references pinned by the realization, one per workflow-specification node, so that every computation reads deterministic inputs and outputs.
        type: array
        items:
          $ref: '#/definitions/ContainerReference'
      version:
        format: int32
        description: The version of the realization.
        type: integer
        example: 7
        x-nullable: false
  VersionId:
    description: An identifier and version pair used to reference a specific version of a resource, such as a workflow specification or a data type.
    required:
      - Id
      - version
    type: object
    properties:
      Id:
        description: The identifier of the resource.
        type: string
        example: 01DV2RPKYS5NYBAR6TNMJ8TNT9
        x-nullable: false
      version:
        format: int64
        description: The version of the resource.
        minimum: !!float 1
        type: integer
        example: 1
        x-nullable: false
    example:
      Id: 01E86SDT0780JMFFZHPBV3KVHV
      version: 1
  SpecAddress:
    description: An address that describes the location of a node within a workflow specification.
    required:
      - type
      - computationIndex
      - dataTypeIndex
    type: object
    properties:
      type:
        description: The type of node that the address refers to, for example a data type input, a data type output, or a computation specification.
        enum:
          - Invalid
          - Computation
          - DataTypeInput
          - DataTypeOutput
          - Workflow
        type: string
        example: DataTypeInput
        x-nullable: false
      computationIndex:
        description: The zero-based index of the computation specification.
        type: integer
        example: 0
        x-nullable: true
      dataTypeIndex:
        description: The zero-based index of a data type with respect to a computation specification. Inputs and outputs are treated as separate ordered lists.
        type: integer
        example: 0
        x-nullable: true
  ContainerReference:
    description: A reference to the container that a realization pins for a single workflow-specification node address.
    required:
      - uri
      - address
    type: object
    properties:
      address:
        $ref: '#/definitions/SpecAddress'
      uri:
        description: The URI of the container.
        type: string
        example: 01J55K2V6T77MRHGT1EZ60KMJ2/containers/production-forecast/01J55M6YHKR877H2M7C31F3MQY
        x-nullable: false
      dataType:
        $ref: '#/definitions/VersionId'
      labels:
        description: The labels of the container.
        additionalProperties:
          type: string
        type: object
        example:
          name: Field_Profile Upside Base.xlsx
        x-nullable: false
  PatchReq:
    description: A JSON Patch document as defined by RFC 6902.
    type: array
    items:
      $ref: '#/definitions/PatchItem'
    example:
      - op: replace
        path: 01K21TCP8YRHJP29K3WXACFPKP/realizations/01K21TRKZG07FYG68EW3Y45X7B/status
        value: Active
  PatchItem:
    description: A single JSON Patch operation as defined by RFC 6902.
    required:
      - op
      - path
    properties:
      op:
        description: The operation to perform. Only the replace operation is supported.
        enum:
          - replace
        type: string
        example: replace
        x-nullable: false
      path:
        description: A JSON Pointer to the field to update.
        type: string
        example: 01K21TCP8YRHJP29K3WXACFPKP/realizations/01K21TRKZG07FYG68EW3Y45X7B/status
        x-nullable: false
      value:
        description: The value to use within the operation.
        example: Active
  Error:
    description: A generic error response.
    required:
      - data
    type: object
    properties:
      data:
        required:
          - code
        type: object
        properties:
          code:
            format: int32
            description: The HTTP status code.
            type: integer
            example: 500
            x-nullable: false
          message:
            description: The error message.
            type: string
            example: internal server error
    example:
      data:
        code: 500
        message: internal server error
  Case:
    description: A case that a realization is associated with.
    required:
      - name
    type: object
    properties:
      name:
        description: The name of the case.
        maxLength: 50
        type: string
        example: case1
        x-nullable: false
  RealizationIndicatorCollection:
    description: A page of per-realization indicator values produced by the evaluation of an ensemble.
    required:
      - items
    type: object
    properties:
      items:
        description: The list of realization indicators.
        type: array
        items:
          $ref: '#/definitions/RealizationIndicators'
    example:
      items:
        - realizationURI: 01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V
          results:
            - address:
                type: DataTypeOutput
                computationIndex: 0
                dataTypeIndex: 0
              indicators:
                - name: NPV
                  unit: M$
                  value: "83.59"
                - name: Total CAPEX
                  unit: M$
                  value: "9.33"
                - name: First Oil
                  value: 2020 01
  RealizationIndicators:
    description: The indicator values for a single realization, grouped by workflow-specification node address.
    required:
      - realizationURI
      - results
    type: object
    properties:
      realizationURI:
        description: The URI of the realization.
        type: string
        example: 01J55K2V6T77MRHGT1EZ60KMJ2/realizations/01J55M7D63XFJM64GS1N2NNE5V
        x-nullable: false
      results:
        description: The indicator results of each computation in the realization.
        type: array
        items:
          $ref: '#/definitions/Indicators'
  Indicators:
    description: The indicator results produced at a single workflow-specification node address.
    required:
      - address
      - indicators
    type: object
    properties:
      address:
        $ref: '#/definitions/SpecAddress'
      indicators:
        description: The list of indicator results.
        type: array
        items:
          $ref: '#/definitions/Indicator'
  Indicator:
    description: A single named indicator value produced by a realization.
    required:
      - name
      - value
    type: object
    properties:
      name:
        description: The name of the indicator.
        type: string
        example: NPV
        x-nullable: false
      secondaryName:
        description: The secondary name of the indicator.
        type: string
        x-nullable: false
      unit:
        description: The unit of the indicator.
        type: string
        example: M$
        x-nullable: false
      value:
        description: The value of the indicator.
        type: string
        example: "83.59"
        x-nullable: false
      entityName:
        description: The name of the entity.
        type: string
        x-nullable: false
      entityType:
        description: The type of the entity.
        type: string
        x-nullable: false
      caseName:
        description: The name of the case.
        type: string
        x-nullable: false
  RealizationEvents:
    description: The list of computation events related to a realization.
    type: object
    properties:
      computationEvents:
        description: The computation events grouped by computation.
        type: array
        items:
          $ref: '#/definitions/ComputationEvents'
    example:
      computationEvents:
        - computationID: 8eec8a4a52b64d540bdfbf6f534995ea73fb449771d2626e42c36be339bbd315
          computationName: economics
          cases: []
          computationEvent:
            - eventType: computation required
              status: Running
              message: Running
              timestamp: "2024-08-13T10:28:49.038Z"
              generatedFiles: []
            - eventType: computation completed
              status: CompletedSuccessfully
              message: Completed successfully
              timestamp: "2024-08-13T10:28:56.155Z"
              generatedFiles: []
  ComputationEvents:
    description: The computation events related to a specific computation.
    type: object
    properties:
      computationID:
        description: The identifier of the computation.
        type: string
        example: 8eec8a4a52b64d540bdfbf6f534995ea73fb449771d2626e42c36be339bbd315
      computationName:
        description: The name of the computation.
        type: string
        example: economics
      cases:
        description: The cases that the events are related to.
        type: array
        items:
          $ref: '#/definitions/Case'
      computationEvent:
        description: The list of events recorded for the computation.
        type: array
        items:
          $ref: '#/definitions/ComputationEvent'
  ComputationEvent:
    description: A single event recorded for a specific computation.
    type: object
    properties:
      source:
        description: The source that produced the event.
        type: string
      status:
        description: The status reported by the event.
        type: string
        example: CompletedSuccessfully
      eventType:
        description: The type of the event.
        type: string
        example: computation completed
      timestamp:
        format: date-time
        description: The time when the event was recorded.
        type: string
        example: "2024-08-13T10:28:56.155Z"
      message:
        description: The message associated with the event.
        type: string
        example: Completed successfully
      generatedFiles:
        description: The log files generated and stored with the event.
        type: array
        items:
          $ref: '#/definitions/GeneratedFile'
  GeneratedFile:
    description: A log file generated and stored in an event related to a specific computation.
    type: object
    properties:
      description:
        description: The description of the generated file.
        type: string
      link:
        description: The link to the generated file.
        type: string
parameters:
  SlbPartitionId:
    required: true
    in: header
    description: Data partition id.
    name: slb-partition-id
    type: string
security:
  - bearer: []
    appkey: []
securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header
  appkey:
    type: apiKey
    name: appkey
    in: header
tags:
  - name: Ensembles
    description: Getting and updating ensembles.
  - name: RealizationEvents
    description: Getting the computation-event log of a realization.
  - name: Results
    description: Getting per-realization indicator results.