Forecast Parameters API Documentation

This API enables users to add, update, or delete forecast parameters for deterministic forecasts. Forecast parameters define how production rates decline over time using various mathematical models (segments).

Overview

There are two versions of the PUT endpoint for updating forecast parameters:

V1 Endpoints (Single Well/Phase/Series)

POST /v1/projects/{projectId}/forecasts/{forecastId}/parameters/{wellId}/{phase}/{series}

Inserts segments for a well/phase/series combination. Will fail if segments already exist for this combination.

Response: 201 Created on success, 400 Bad Request if segments already exist or validation fails

PUT /v1/projects/{projectId}/forecasts/{forecastId}/parameters/{wellId}/{phase}/{series}

Updates all segments for a single well, phase, and series combination. This endpoint replaces all existing segments for the specified combination with the provided segments.

Path Parameters:

projectId: The project's ID
forecastId: The forecast's ID
wellId: The well's ID
phase: The phase (oil | gas | water)
series: The series (p10 | p50 | p90 | best)

Request Body: Array of segment objects (max 25 items)

Response: 201 Created on success, 400 Bad Request on validation error

V2 Endpoint (Multiple Wells/Phases/Series)

PUT /v1/projects/{projectId}/forecasts/{forecastId}/parameters

Updates segments for multiple wells, phases, and series in a single request. This is the preferred endpoint for bulk updates as it reduces the number of API calls needed.

Path Parameters:

projectId: The project's ID
forecastId: The forecast's ID

Request Body: Array of forecast parameter objects (max 25 items), each containing well, phase, series, and segments

Response: 207 Multi-Status with individual status for each operation

Key Differences:

V1: Updates one well/phase/series per request, requires well/phase/series in URL path
V2: Updates multiple well/phase/series combinations per request, well/phase/series specified in request body
V2: Supports additional options like forecastType, dataFrequency, and basePhase
V2: Returns multi-status response with detailed results for each operation

DELETE Endpoint

DELETE /v1/projects/{projectId}/forecasts/{forecastId}/parameters/{wellId}/{phase}/{series}

Removes all segments for the specified well/phase/series combination.

Response: 204 No Content with X-Delete-Count header indicating number of deleted records

Supported Segment Types

Forecasts are divided into contiguous date-based segments. Each segment has a type that determines its decline curve behavior:

arps
arps_inc
exp_dec
exp_inc
flat
linear
arps_modified
empty

Common Segment Properties

All segments require:

segmentType: The type of segment
startDate: Start date in YYYY-MM-DD format (range: 1900-01-01 to 2262-04-01)
endDate: End date in YYYY-MM-DD format (range: 1900-01-01 to 2262-04-01)

Most segments also require:

qStart: Initial production rate at segment start (BBL/D or MCF/D depending on phase)

Segment Type Details & Examples

1. ARPS (Hyperbolic Decline)

Represents hyperbolic decline using the Arps equation. Most common for oil & gas production forecasting.

{
  "segmentType": "arps",
  "startDate": "2023-01-01",
  "endDate": "2028-12-31",
  "qStart": 1500,
  "d": 0.25,
  "b": 1.2
}

Required Properties:

qStart
b
Either d OR dEff - at least one required

2. ARPS Incline (Hyperbolic Incline)

Similar to ARPS but for increasing production (e.g., well ramp-up phase).

{
  "segmentType": "arps_inc",
  "startDate": "2023-01-01",
  "endDate": "2023-06-30",
  "qStart": 100,
  "dEff": 0.15,
  "b": 0.8
}

Required Properties:

qStart: Initial rate
b: Arps b-factor
Either d OR dEff - at least one required

3. Exponential Decline

Constant percentage decline rate (b-factor = 0).

{
  "segmentType": "exp_dec",
  "startDate": "2023-01-01",
  "endDate": "2025-12-31",
  "qStart": 700,
  "d": 0.15
}

Required Properties:

qStart: Initial rate
Either d OR dEff - at least one required

4. Exponential Incline

Exponential increase in production rate.

{
  "segmentType": "exp_inc",
  "startDate": "2023-01-01",
  "endDate": "2023-03-31",
  "qStart": 50,
  "dEff": 0.20
}

Required Properties:

qStart: Initial rate
Either d OR dEff - at least one required

5. Flat Production

Constant production rate over time.

{
  "segmentType": "flat",
  "startDate": "2023-01-01",
  "endDate": "2024-12-31",
  "qStart": 500
}

Required Properties:

qStart: Constant production rate

6. Linear Change

Linear increase or decrease in production rate.

{
  "segmentType": "linear",
  "startDate": "2023-01-01",
  "endDate": "2023-12-31",
  "qStart": 950,
  "slope": -0.00137
}

Required Properties:

qStart: Initial rate
slope: Rate of change (BBL/D/D or MCF/D/D)

7. Modified ARPS

{
  "segmentType": "arps_modified",
  "startDate": "2023-01-01",
  "endDate": "2030-12-31",
  "qStart": 450,
  "d": 0.18,
  "b": 0.9,
  "realizedDEffSw": 0.06
}

Required Properties:

qStart: Initial rate
b: Arps b-factor
realizedDEffSw: Realized effective decline switch point (as decimal)
Either d OR dEff - at least one required

8. Empty Segment

Represents a period with no production.

{
  "segmentType": "empty",
  "startDate": "2023-01-01",
  "endDate": "2023-03-31"
}

Complete Examples

V1 Endpoint Example (Single Well)

PUT /v1/projects/507f1f77bcf86cd799439011/forecasts/507f191e810c19729de860ea/parameters/5e61a3afbc3de5d21ee23364/oil/best

[
    {
        "segmentType": "arps_modified",
        "startDate": "2022-07-28",
        "endDate": "2028-07-26",
        "qStart": 497.54078888022735,
        "qEnd": 169.85103,
        "diEffSec": 0.2708,
        "b": 1.3,
        "targetDSwEffSec":0.06
    },
    {
        "segmentType": "arps_modified",
        "startDate": "2028-07-27",
        "endDate": "2037-07-14",
        "qStart": 497.54078888022735,
        "qEnd": 108.2303,
        "diEffSec": 0.2708,
        "b": 0.9,
        "targetDSwEffSec": 0.06
    },
    {
        "segmentType": "arps_inc",
        "startDate": "2037-07-15",
        "endDate": "2042-07-14",
        "qStart": 108.2303,
        "qEnd": 428.063247,
        "diEffSec": -0.5572,
        "b": -0.9
    }
]

Response:

{
  "message": "Successfully created 3 segments",
  "segmentsCount": 3,
  "id": "507f191e810c19729de860ea"
}

V2 Endpoint Example (Multiple Wells)

PUT /v1/projects/507f1f77bcf86cd799439011/forecasts/507f191e810c19729de860ea/parameters

[
  {
    "well": "5e61a3afbc3de5d21ee23364",
    "forecastType": "rate",
    "phase": "oil",
    "series": "best",
    "dataFrequency": "monthly",
    "segments": [
      {
        "segmentType": "arps",
        "startDate": "2023-01-01",
        "endDate": "2028-12-31",
        "qStart": 1500,
        "d": 0.25,
        "b": 1.2
      },
      {
        "segmentType": "linear",
        "startDate": "2029-01-01",
        "endDate": "2030-12-31",
        "qStart": 950,
        "slope": -0.00137
      }
    ]
  },
  {
    "well": "5e61a3afbc3de5d21ee23365",
    "forecastType": "rate",
    "phase": "gas",
    "series": "best",
    "dataFrequency": "daily",
    "segments": [
      {
        "segmentType": "exp_dec",
        "startDate": "2023-01-01",
        "endDate": "2027-12-31",
        "qStart": 700,
        "dEff": 0.15
      },
      {
        "segmentType": "flat",
        "startDate": "2028-01-01",
        "endDate": "2035-12-31",
        "qStart": 500
      }
    ]
  },
  {
    "well": "5e61a3afbc3de5d21ee23366",
    "forecastType": "ratio",
    "phase": "water",
    "series": "best",
    "basePhase": "oil",
    "segments": [
      {
        "segmentType": "empty",
        "startDate": "2023-01-01",
        "endDate": "2023-06-30"
      },
      {
        "segmentType": "arps_inc",
        "startDate": "2023-07-01",
        "endDate": "2025-12-31",
        "qStart": 0.5,
        "d": 0.10,
        "b": 0.8
      }
    ]
  }
]

Response (207 Multi-Status):

{
    "generalErrors": [
        {
            "name": "ValidationError",
            "message": "Segment validation failed while trying to save it to database. Please contact support to get more details.",
            "location": "[4]"
        }
    ],
  "results": [
    {
      "code": 201,
      "status": "Created",
      "message": "Successfully updated segments",
    },
    {
      "code": 201,
      "status": "Created",
      "message": "Successfully updated segments",
    },
    {
      "code": 201,
      "status": "Created",
      "message": "Successfully updated segments",
    }
  ],
  "successCount": 3,
  "failedCount": 1
}

V2 Endpoint Parameters

ForecastParametersV2Input Object

Each object in the V2 request array must include:

Required:

well (string): The well ID
forecastType (string): rate or ratio
phase (string): oil, gas, or water
series (string): Currently only best is fully supported
segments (array): Array of segment objects (see segment types above)

Optional:

dataFrequency (string): daily or monthly (default: monthly)
basePhase (string): Required for ratio forecasts - the phase the ratio is based on (oil, gas, or water)

Notes:

Rate Forecasts:
Ratio Forecasts: Production as a ratio to another phase.
Maximum 25 items per request

Validation Rules

Segment Dates:
- Must be in YYYY-MM-DD format
- Must be between 1900-01-01 and 2262-04-01
- Segments must be contiguous (no gaps or overlaps)
- endDate must be after startDate
Segment Count:
- Maximum 25 segments per request
Numeric Values:
- qStart: Must be a valid number (can be 0 for some segment types)
- d, dEff: Decline rates, typically 0-1 range (percentages as decimals)
- b: Typically 0-2 range
- slope: Can be positive or negative
Well/Phase/Series:
- Well must exist in the forecast
- Phase must be one of: oil, gas, water
- Series must be one of: p10, p50, p90, best (currently only best fully supported)
Decline Parameters:
- For ARPS-type and exponential segments: must provide either d OR dEff (at least one)
- Cannot provide both if using schema validation

Error Responses

400 Bad Request

{
    "generalErrors": [
        {
            "name": "ValidationError",
            "message": "Segment validation failed while trying to save it to database. Please contact support to get more details.",
            "location": "[1]"
        }
    ],
  "results":[
    {
      "errors": [
        {
          "message": "Invalid segment type",
          "field": "segmentType",
          "value": "invalid_type",
          "recordIndex": 0
        }
      ]
    }
  ]
}

404 Not Found

{
  "message": "Forecast not found",
  "code": 404
}

Best Practices

Use V2 for Bulk Operations: When updating multiple wells or phases, use the V2 endpoint to reduce API calls and improve performance.
Contiguous Segments: Ensure segments are contiguous without gaps. Use empty segments for periods with no production.
Appropriate Segment Types:
- Use arps for most oil/gas decline forecasting
- Use flat for artificial lift or stable production periods
- Use linear for short transition periods
- Use empty for shut-in or non-producing periods
Data Frequency: Choose daily for high-resolution forecasts or monthly for long-term forecasts.
Error Handling: The V2 endpoint returns 207 Multi-Status, so check individual results even with a successful HTTP response.

Deprecated Fields

The following fields appear in older documentation but are deprecated:

qEnd: End rate (calculated automatically)
diEffSec: Use dEff instead
targetDSwEffSec: Use realizedDEffSw instead
flatValue: Use qStart instead

These fields may still be accepted for backward compatibility but should not be used in new implementations.

Overview​

V1 Endpoints (Single Well/Phase/Series)​

V2 Endpoint (Multiple Wells/Phases/Series)​

DELETE Endpoint​

Supported Segment Types​

Common Segment Properties​

Segment Type Details & Examples​

1. ARPS (Hyperbolic Decline)​

2. ARPS Incline (Hyperbolic Incline)​

3. Exponential Decline​

4. Exponential Incline​

5. Flat Production​

6. Linear Change​

7. Modified ARPS​

8. Empty Segment​

Complete Examples​

V1 Endpoint Example (Single Well)​

V2 Endpoint Example (Multiple Wells)​

V2 Endpoint Parameters​

ForecastParametersV2Input Object​

Validation Rules​

Error Responses​

400 Bad Request​

404 Not Found​

Best Practices​

Deprecated Fields​

Overview

V1 Endpoints (Single Well/Phase/Series)

V2 Endpoint (Multiple Wells/Phases/Series)

DELETE Endpoint

Supported Segment Types

Common Segment Properties

Segment Type Details & Examples

1. ARPS (Hyperbolic Decline)

2. ARPS Incline (Hyperbolic Incline)

3. Exponential Decline

4. Exponential Incline

5. Flat Production

6. Linear Change

7. Modified ARPS

8. Empty Segment

Complete Examples

V1 Endpoint Example (Single Well)

V2 Endpoint Example (Multiple Wells)

V2 Endpoint Parameters

ForecastParametersV2Input Object

Validation Rules

Error Responses

400 Bad Request

404 Not Found

Best Practices

Deprecated Fields