Skip to content
Developers
Get an API token

Save a forecast source

Reads a file as POST /forecast-sources/read does and keeps the read as a forecast source: its curves, the read report's rows, and the file's name, bytes and SHA-256, but not the file.

Save a forecast source

POST/forecast-sources

Reads a file as POST /forecast-sources/read does and keeps the read as a forecast source: its curves, the read report's rows, and the file's name, bytes and SHA-256, but not the file. Send the read's body plus name; the answer is the read with the saved source.

Send a Novi API token as a bearer token on every request. Authentication
Visibility

Anyone but its creator gets 404 for a private source. Without a signed-in user (a server's configured user), private is a 400: send tenant.

A linked plan

plan_id names a done plan the caller can read: else a 404, or a 409 while it runs or after it failed. Deleting the plan keeps the source, which then reads its plan_id and pairs with plan_linked: false.

Retries

An Idempotency-Key makes a retry safe, per tenant and creator: the same key with the same file (by its SHA-256 and the text parts, or the same JSON body) returns the first source with Idempotent-Replayed: true. With another file it is a 409.

Errors

A file that reads no curves is a 400. A server without a state store answers 409 "Forecast sources need a state store; this server keeps plans in memory".

Parameters

Header parameters

  • Idempotency-KeystringOptional

    pattern ^[A-Za-z0-9._:-]{1,128}$

    Makes a retry safe: send your own key (a UUID, or your request id) and the same key on every retry. Without the header, nothing changes.

    The same key and body (compared as JSON, key order ignored) within 24 hours replays what the first request made, with its id, in its current state, with Idempotent-Replayed: true, and starts nothing. A different body is a 409 (details.field Idempotency-Key).

    • Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.
    • With Redis, POST /saved/{collection}, /forecast-sources and /area-sets keep keys there, as do POST /plans and /exports on a server with a state store: every server task shares them and a restart keeps them. While Redis isn't answering, these answer 503.
      • A retry while the first request is still being made waits up to 30 s for it, then answers 409: retry shortly with the same key.
      • A key the first request hasn't recorded within a minute (its task stopped, or Redis failed as it finished) lapses; a retry then makes the resource again.
    • Otherwise keys live in the server process's memory, the latest 1,000 per operation: a restart (a deploy is one) forgets them, and a retry during the first request waits for it.
    • POST /forecasts with async: true and POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans with dry_run: true neither keeps nor replays its key.
    • A replay of a plan or export the server has dropped is a 404.

Request bodyRequired

The file and its name: uploaded as multipart/form-data, or in a JSON body.

  • filestringRequired

    File

    As in POST /forecast-sources/read; a file part's name is kept with the source.

  • namestringRequired

    The source's name, 1 to 100 characters.

  • constantsstringOptional

    File

  • optionsstringOptional

  • includestringOptional

    As include in the JSON body, as JSON text: ["warning_codes", "sheets"].

  • visibilitystringOptional

    private or tenant, as in the JSON body.

  • plan_idstringOptional

    A done plan's id to link.

Responses

201 Created

The read and the saved source, with its ETag.

  • formatstringRequired

    The format read.

    "valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"
  • detected_fromarray of stringsRequired

    The headers that picked the format; ARIES text gives ["PRODUCTION"], also when options.format named it.

  • unitsobjectRequired

    Units.

    ShowHide 5 child fields
    • systemstringRequired

      The unit system read.

      "imperial""metric"
    • fromstringRequired

      What set it.

      "options""units row""format""default"
    • ratesobjectRequired

      The rate units read, converted to bbl/d and mcf/d.

      ShowHide 3 child fields
      • oilstringRequired

        Its rate unit.

      • gasstringRequired

        Its rate unit.

      • waterstringRequired

        Its rate unit.

    • ratiosobjectRequired

      A ratio product to its unit.

    • rowobject or nullRequired

      A Val Nav units row or a Mosaic file's header unit labels, header to unit, or null.

  • productsobjectRequired

    Products.

    ShowHide 3 child fields
    • foundarray of objectsRequired

      Every product in the file.

      ShowHide 2 child fields in each item
      • valuestringRequired

        As the file has it.

      • curvesintegerRequired

        ≥ 0

        Curves.

    • mappedarray of objectsRequired

      Products read.

      ShowHide 3 child fields in each item
      • valuestringRequired

        The product.

      • streamstringRequired

        The stream it reads as.

        "oil""gas""water"
      • fromstring or nullRequired

        The parent stream of a ratio.

        "oil""gas"
    • skippedarray of objectsRequired

      Products left out.

      ShowHide 2 child fields in each item
      • valuestringRequired

        As the file has it.

      • curvesintegerRequired

        ≥ 0

        Curves.

  • gas_basisstringRequired

    raw or sales gas.

    "raw""sales"
  • reserves_categoriesarray of objectsRequired

    Every reserves category with a curve.

    ShowHide 3 child fields in each item
    • valuestringRequired

      As the file has it.

    • curvesintegerRequired

      ≥ 0

      Curves.

    • keptbooleanRequired

      Whether options.reserves_categories keeps it.

  • curvesarray of objectsRequired

    The curves read, in file order.

    ShowHide 10 child fields in each item
    • well_idstringRequired

      The Well ID, as the file has it.

    • reserves_categorystringRequired

      Its reserves category (a Novi P-level reads as P50 or its options.p_levels category).

    • designstring or nullRequired

      Its completion design (Novi arps.csv), or null.

    • streamstringRequired

      The stream it forecasts.

      "oil""gas""water"
    • productstringRequired

      The file's product it came from.

    • ratiostring or nullRequired

      The ratio it is, its stream from its parent's, or null.

      "gor""ogr""cgr""wor""wgr"
    • profilestringRequired

      The decline conventions it runs under (GET /conventions include=decline_profiles).

      "valnav""mosaic""combocurve""novi""aries"
    • start_datestring or nullRequired

      The date of day 0, or null when the file counts ip days.

    • templatestring or nullRequired

      The Val Nav template it matched, ComboCurve's Segment Types in order, or null.

    • segmentsarray of objectsRequired

      Its segments in order, each starting where the one before ends.

      ShowHide 9 child fields in each item
      • startnumberRequired

        The day it starts, from day 0.

      • qinumberRequired

        Rate at start: bbl/d for oil and water, mcf/d for gas; for a ratio, the ratio (GOR scf/bbl, OGR, CGR and WGR bbl/MMcf, WOR bbl/bbl).

      • dinumberRequired

        Nominal decline per year at start; below 0 for an incline.

      • bnumberRequired

        Arps b: 0 exponential, 1 harmonic, -1 a straight line.

      • endnumber or nullOptional

        The day it ends; absent or null runs to qf, df or the curve's end.

      • qfnumber or nullOptional

        The rate it ends at.

      • dfnumber or nullOptional

        The nominal decline it ends at.

      • max_ratenumber or nullOptional

        A cap on the rate.

      • slopestringOptional

        What a ratio declines with: time or the parent stream's cumulative volume.

        "time""volume"
  • rowsarray of objectsRequired

    Only the rows with an issue.

    ShowHide 7 child fields in each item
    • filestringRequired

      The part or field the row is in: file, constants, csv or constants_csv.

    • idintegerRequired

      ≥ 0

      Its data row in that file, from 0.

    • well_idstring or nullRequired

      Its Well ID, or null.

    • productstring or nullRequired

      Its product, or null.

    • segmentinteger or nullRequired

      Its segment number, or null.

    • left_outbooleanRequired

      True when its curve was left out.

    • issuesarray of stringsRequired

      What was wrong with it.

  • warningsarray of stringsRequired

    What to check.

  • sourceobjectRequired

    A forecast source.

    ShowHide 20 child fields
    • idstringRequired

      Format uuid

      Source id.

    • namestringRequired

      Name.

    • formatstringRequired

      The file's format.

      "valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"
    • unitsstringRequired

      The file's unit system; curves are stored in bbl/d and mcf/d.

      "imperial""metric"
    • conventionsstringRequired

      The decline conventions its curves run under.

      "valnav""mosaic""combocurve""novi""aries"
    • gas_basisstringRequired

      raw or sales gas.

      "raw""sales"
    • curve_countintegerRequired

      ≥ 0

      Curves.

    • well_countintegerRequired

      ≥ 0

      Distinct Well IDs.

    • fileobjectRequired

      The file read; the file itself isn't kept.

      ShowHide 3 child fields
      • namestring or nullRequired

        The uploaded file's name, or JSON file_name; null without one.

      • bytesintegerRequired

        ≥ 0

        Its size.

      • sha256stringRequired

        Its SHA-256, hex.

    • visibilitystringRequired

      private answers only its creator; tenant every user of the tenant.

      "private""tenant"
    • created_bystring or nullRequired

      The signed-in creator's email; null for a server's configured user.

    • created_atstringRequired

      Format date-time

      Creation time.

    Show all 20 fields
    • updated_atstringRequired

      Format date-time

      Last change.

    • plan_idstring or nullRequired

      Format uuid

      The linked plan, or null when none is linked. A plan that is gone or that the caller can't read stays here with plan_linked: false.

    • plan_linkedbooleanRequired

      Whether plan_id names a plan the caller can read: false with a plan_id when that plan is gone or hidden from the caller.

    • etagstringRequired

      Current ETag including quotes; send as If-Match.

    • reserves_categoriesarray of objectsRequired

      Its reserves categories.

      ShowHide 2 child fields in each item
      • valuestringRequired

        As the file has it.

      • curvesintegerRequired

        ≥ 0

        Curves.

    • pairsobject or nullRequired

      Source Well IDs to the linked plan's well indexes; null without pairs. A gone link (plan_linked: false) keeps them, a start for pairing with another plan: PATCH with plan_id and pairs.

    • read_reportobjectRequired

      What the read left out.

      ShowHide 1 child field
      • rowsarray of objectsRequired

        The rows with an issue.

        ShowHide 3 child fields in each item
        • filestringRequired

          The part or field the row is in: file, constants, csv or constants_csv.

        • idintegerRequired

          ≥ 0

          Its data row in that file, from 0.

        • issuesarray of stringsRequired

          What was wrong.

    • curvesarray of objectsOptional

      Only with include=volumes: the stored curves, in file order.

      ShowHide 11 child fields in each item
      • well_idstringRequired

        The Well ID, as the file has it.

      • reserves_categorystringRequired

        Its reserves category (a Novi P-level reads as P50 or its options.p_levels category).

      • designstring or nullRequired

        Its completion design (Novi arps.csv), or null.

      • streamstringRequired

        The stream it forecasts.

        "oil""gas""water"
      • productstringRequired

        The file's product it came from.

      • ratiostring or nullRequired

        The ratio it is, its stream from its parent's, or null.

        "gor""ogr""cgr""wor""wgr"
      • profilestringRequired

        The decline conventions it runs under (GET /conventions include=decline_profiles).

        "valnav""mosaic""combocurve""novi""aries"
      • start_datestring or nullRequired

        The date of day 0, or null when the file counts ip days.

      • templatestring or nullRequired

        The Val Nav template it matched, ComboCurve's Segment Types in order, or null.

      • segmentsarray of objectsRequired

        Its segments in order, each starting where the one before ends.

        Same fields as SourceSegment.

      • volumesobjectRequired

        Volumes from Novi's Arps decline calculation.

        ShowHide 5 child fields
        • unitstringRequired

          bbl for oil and water, mcf for gas.

          "bbl""mcf"
        • ip_daysarray of integersRequired

          The days asked, ascending.

        • valuesarray of numbers or nullRequired

          Cumulative volume at each ip_day, rounded to 0.1; null when the engine can't run the curve.

        • eurnumber or nullRequired

          Volume to the curve's end, rounded to 0.1.

        • errorstringOptional

          Why the engine can't run it.

  • sheetstringOptional

    The sheet read; only with include ["sheets"], for a workbook file.

  • sheetsarray of stringsOptional

    Every sheet in workbook order, chartsheets included, so a position is the index options.sheet takes; only with include ["sheets"], for a workbook file, never the constants part's.

  • warning_detailsarray of objectsOptional

    Only with include warning_codes: each warning's code and fields, one per warning, in the same order.

    ShowHide 22 child fields in each item
    • codestringRequired

      Stable code; more may come. Each code carries only the fields listed with it.

      • workbook_first_sheet: file, sheet, sheet_count
      • formulas_without_values: file, sheet, cell_count
      • constants_without_units: file
      • constants_on_time: file, row_count
      • constants_cut_off: file, row_count
      • series_left_out: file, row_count, series
      • product_not_found: product
      • reserves_category_not_found: reserves_category
      • unit_not_recognized: label, from, quantity, unit
      • curves_left_out: curve_count, total_curve_count
      • rows_without_curve: row_count
      • p_levels_not_read: format
      • p_levels_left_out: curve_count
      • condensate_as_oil: product
      • sales_gas: product
      • mixed_gas_basis: sales_product, raw_product
      • default_units: system, rates
      • constants_only
      • multiple_reserves_categories: well_count
      • multiple_designs: well_count
      • sections_not_read: file, row_count
    • messagestringRequired

      Its sentence in warnings, written for API callers.

    • filestringOptional

      The part or field it is about: file, constants, csv or constants_csv.

    • sheetstringOptional

      The workbook sheet read, as the sentence names it.

    • sheet_countintegerOptional

      ≥ 0

      Sheets in the workbook.

    • cell_countintegerOptional

      ≥ 0

      Formula cells without a saved value.

    • row_countintegerOptional

      ≥ 0

      Rows it counts.

    • seriesarray of stringsOptional

      The series left out.

    • productstringOptional

      The product, as the file or options.products spells it.

    • reserves_categorystringOptional

      The category, as options.reserves_categories sent it.

    • labelstringOptional

      The unit label the file gives.

    • fromstringOptional

      Where the label is.

      "header""units row"
    Show all 22 fields
    • quantitystringOptional

      What the label was read for: oil and water rates, gas rates or a ratio.

      "oil_water_rates""gas_rates""gor""ogr""cgr""wor""wgr"
    • unitstringOptional

      The unit it reads in instead.

    • curve_countintegerOptional

      ≥ 0

      Curves it counts.

    • total_curve_countintegerOptional

      ≥ 0

      Curves the file made.

    • formatstringOptional

      The format read.

      "valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"
    • sales_productstringOptional

      The sales gas product.

    • raw_productstringOptional

      The raw gas product.

    • systemstringOptional

      The unit system read.

      "imperial""metric"
    • ratesobjectOptional

      The rate units read, as units.rates.

      ShowHide 3 child fields
      • oilstringRequired

        Its rate unit.

      • gasstringRequired

        Its rate unit.

      • waterstringRequired

        Its rate unit.

    • well_countintegerOptional

      ≥ 0

      Wells it counts.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The linked plan is still running or failed, or the Idempotency-Key was already used with another file; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key. A server without a state store answers 409 "Forecast sources need a state store; this server keeps plans in memory".

413

The request body is over 64 MB.

503

With Redis, the Redis that keeps Idempotency-Key records isn't answering; retry with the same key.

Shared errors400401403500What they mean