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
/forecast-sourcesReads 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.
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-KeystringOptionalpattern ^[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.fieldIdempotency-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: trueand POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans withdry_run: trueneither keeps nor replays its key. - A replay of a plan or export the server has dropped is a 404.
Request body
The file and its name: uploaded as multipart/form-data, or in a JSON body.
filestringRequiredFile
As in POST /forecast-sources/read; a file part's name is kept with the source.
namestringRequiredThe source's name, 1 to 100 characters.
constantsstringOptionalFile
As in POST /forecast-sources/read.
optionsstringOptionalAs in POST /forecast-sources/read.
includestringOptionalAs include in the JSON body, as JSON text: ["warning_codes", "sheets"].
visibilitystringOptionalprivate or tenant, as in the JSON body.
plan_idstringOptionalA done plan's id to link.
csvstringRequiredAs in POST /forecast-sources/read.
namestringRequired1 to 100 characters
The source's name.
constants_csvstringOptionalAs in POST /forecast-sources/read.
optionsobjectOptionalHow to read the file; every member is optional.
ShowHide 8 child fields
formatstringOptionalThe file's format, when its header could read as another; absent, the header decides.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"unitsstringOptionalThe file's unit system; absent, a Val Nav units row or a Mosaic file's header unit labels decide, else imperial (bbl/d, Mcf/d; metric m³/d, e³m³/d).
"imperial""metric"productsobjectOptionalup to 100 keys
A file product (any case and spacing) to the stream it reads as, or skip, as {"CONDENSATE": "skip"}; a ratio product (GOR, OGR, CGR, WOR, WGR) maps only to its own stream or skip.
gas_basisstringOptionalraw or sales gas; absent, sales when the file names sales gas, else raw.
"raw""sales"reserves_categoriesarray of stringsOptionalup to 100 itemsItems 1 to 200 characters
The categories to keep; absent keeps every one.
p_levelsobjectOptionalNovi arps.csv only: the reserves category each P-level reads as, each its own, as {"P10": "1P"}.
ShowHide 3 child fields
P10stringOptionalIts reserves category.
P50stringOptionalIts reserves category; absent, P50.
P90stringOptionalIts reserves category.
columnsobjectOptionalup to 100 keys
A role to the file's header for it, when the file names a column otherwise, as {"uwi": "Well ID"}; a role the format lacks or a header the file lacks is a 400.
sheetstring or integerOptional≥ 01 to 200 characters
An .xlsx file's sheet to read: its name, exact or in any case, or its index from 0, as "Declines" or 0; absent, the first. A sheet the workbook lacks is a 400 with details.sheets, and sheet with CSV text a 400.
includearray of stringsOptionalup to 2 items
warning_codes adds warning_details, each warning's code and fields beside its sentence; sheets adds a workbook's sheet and sheets. Each at most once.
"warning_codes""sheets"visibilitystringOptionalprivate (the default) answers only its signed-in creator; tenant every user of the tenant.
"private""tenant"plan_idstring or nullOptionalFormat
uuidA done plan to link, which linking saves; null or absent links none.
file_namestringOptional1 to 200 characters
The file's name, kept with the source; absent, null.
Responses
201 Created
The read and the saved source, with its ETag.
formatstringRequiredThe format read.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"detected_fromarray of stringsRequiredThe headers that picked the format; ARIES text gives ["PRODUCTION"], also when options.format named it.
unitsobjectRequiredUnits.
ShowHide 5 child fields
systemstringRequiredThe unit system read.
"imperial""metric"fromstringRequiredWhat set it.
"options""units row""format""default"ratesobjectRequiredThe rate units read, converted to bbl/d and mcf/d.
ShowHide 3 child fields
oilstringRequiredIts rate unit.
gasstringRequiredIts rate unit.
waterstringRequiredIts rate unit.
ratiosobjectRequiredA ratio product to its unit.
rowobject or nullRequiredA Val Nav units row or a Mosaic file's header unit labels, header to unit, or null.
productsobjectRequiredProducts.
ShowHide 3 child fields
foundarray of objectsRequiredEvery product in the file.
ShowHide 2 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
mappedarray of objectsRequiredProducts read.
ShowHide 3 child fields in each item
valuestringRequiredThe product.
streamstringRequiredThe stream it reads as.
"oil""gas""water"fromstring or nullRequiredThe parent stream of a ratio.
"oil""gas"
skippedarray of objectsRequiredProducts left out.
ShowHide 2 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
gas_basisstringRequiredraw or sales gas.
"raw""sales"reserves_categoriesarray of objectsRequiredEvery reserves category with a curve.
ShowHide 3 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
keptbooleanRequiredWhether options.reserves_categories keeps it.
curvesarray of objectsRequiredThe curves read, in file order.
ShowHide 10 child fields in each item
well_idstringRequiredThe Well ID, as the file has it.
reserves_categorystringRequiredIts reserves category (a Novi P-level reads as P50 or its options.p_levels category).
designstring or nullRequiredIts completion design (Novi arps.csv), or null.
streamstringRequiredThe stream it forecasts.
"oil""gas""water"productstringRequiredThe file's product it came from.
ratiostring or nullRequiredThe ratio it is, its stream from its parent's, or null.
"gor""ogr""cgr""wor""wgr"profilestringRequiredThe decline conventions it runs under (GET /conventions include=decline_profiles).
"valnav""mosaic""combocurve""novi""aries"start_datestring or nullRequiredThe date of day 0, or null when the file counts ip days.
templatestring or nullRequiredThe Val Nav template it matched, ComboCurve's Segment Types in order, or null.
segmentsarray of objectsRequiredIts segments in order, each starting where the one before ends.
ShowHide 9 child fields in each item
startnumberRequiredThe day it starts, from day 0.
qinumberRequiredRate 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).
dinumberRequiredNominal decline per year at start; below 0 for an incline.
bnumberRequiredArps b: 0 exponential, 1 harmonic, -1 a straight line.
endnumber or nullOptionalThe day it ends; absent or null runs to qf, df or the curve's end.
qfnumber or nullOptionalThe rate it ends at.
dfnumber or nullOptionalThe nominal decline it ends at.
max_ratenumber or nullOptionalA cap on the rate.
slopestringOptionalWhat a ratio declines with: time or the parent stream's cumulative volume.
"time""volume"
rowsarray of objectsRequiredOnly the rows with an issue.
ShowHide 7 child fields in each item
filestringRequiredThe 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 nullRequiredIts Well ID, or null.
productstring or nullRequiredIts product, or null.
segmentinteger or nullRequiredIts segment number, or null.
left_outbooleanRequiredTrue when its curve was left out.
issuesarray of stringsRequiredWhat was wrong with it.
warningsarray of stringsRequiredWhat to check.
sourceobjectRequiredA forecast source.
ShowHide 20 child fields
idstringRequiredFormat
uuidSource id.
namestringRequiredName.
formatstringRequiredThe file's format.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"unitsstringRequiredThe file's unit system; curves are stored in bbl/d and mcf/d.
"imperial""metric"conventionsstringRequiredThe decline conventions its curves run under.
"valnav""mosaic""combocurve""novi""aries"gas_basisstringRequiredraw or sales gas.
"raw""sales"curve_countintegerRequired≥ 0
Curves.
well_countintegerRequired≥ 0
Distinct Well IDs.
fileobjectRequiredThe file read; the file itself isn't kept.
ShowHide 3 child fields
namestring or nullRequiredThe uploaded file's name, or JSON file_name; null without one.
bytesintegerRequired≥ 0
Its size.
sha256stringRequiredIts SHA-256, hex.
visibilitystringRequiredprivate answers only its creator; tenant every user of the tenant.
"private""tenant"created_bystring or nullRequiredThe signed-in creator's email; null for a server's configured user.
created_atstringRequiredFormat
date-timeCreation time.
Show all 20 fields
updated_atstringRequiredFormat
date-timeLast change.
plan_idstring or nullRequiredFormat
uuidThe 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_linkedbooleanRequiredWhether plan_id names a plan the caller can read: false with a plan_id when that plan is gone or hidden from the caller.
etagstringRequiredCurrent ETag including quotes; send as If-Match.
reserves_categoriesarray of objectsRequiredIts reserves categories.
ShowHide 2 child fields in each item
valuestringRequiredAs the file has it.
curvesintegerRequired≥ 0
Curves.
pairsobject or nullRequiredSource 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_reportobjectRequiredWhat the read left out.
ShowHide 1 child field
rowsarray of objectsRequiredThe rows with an issue.
ShowHide 3 child fields in each item
filestringRequiredThe 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 stringsRequiredWhat was wrong.
curvesarray of objectsOptionalOnly with include=volumes: the stored curves, in file order.
ShowHide 11 child fields in each item
well_idstringRequiredThe Well ID, as the file has it.
reserves_categorystringRequiredIts reserves category (a Novi P-level reads as P50 or its options.p_levels category).
designstring or nullRequiredIts completion design (Novi arps.csv), or null.
streamstringRequiredThe stream it forecasts.
"oil""gas""water"productstringRequiredThe file's product it came from.
ratiostring or nullRequiredThe ratio it is, its stream from its parent's, or null.
"gor""ogr""cgr""wor""wgr"profilestringRequiredThe decline conventions it runs under (GET /conventions include=decline_profiles).
"valnav""mosaic""combocurve""novi""aries"start_datestring or nullRequiredThe date of day 0, or null when the file counts ip days.
templatestring or nullRequiredThe Val Nav template it matched, ComboCurve's Segment Types in order, or null.
segmentsarray of objectsRequiredIts segments in order, each starting where the one before ends.
Same fields as SourceSegment.
volumesobjectRequiredVolumes from Novi's Arps decline calculation.
ShowHide 5 child fields
unitstringRequiredbbl for oil and water, mcf for gas.
"bbl""mcf"ip_daysarray of integersRequiredThe days asked, ascending.
valuesarray of numbers or nullRequiredCumulative volume at each ip_day, rounded to 0.1; null when the engine can't run the curve.
eurnumber or nullRequiredVolume to the curve's end, rounded to 0.1.
errorstringOptionalWhy the engine can't run it.
sheetstringOptionalThe sheet read; only with include ["sheets"], for a workbook file.
sheetsarray of stringsOptionalEvery 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 objectsOptionalOnly with include warning_codes: each warning's code and fields, one per warning, in the same order.
ShowHide 22 child fields in each item
codestringRequiredStable code; more may come. Each code carries only the fields listed with it.
workbook_first_sheet: file, sheet, sheet_countformulas_without_values: file, sheet, cell_countconstants_without_units: fileconstants_on_time: file, row_countconstants_cut_off: file, row_countseries_left_out: file, row_count, seriesproduct_not_found: productreserves_category_not_found: reserves_categoryunit_not_recognized: label, from, quantity, unitcurves_left_out: curve_count, total_curve_countrows_without_curve: row_countp_levels_not_read: formatp_levels_left_out: curve_countcondensate_as_oil: productsales_gas: productmixed_gas_basis: sales_product, raw_productdefault_units: system, ratesconstants_onlymultiple_reserves_categories: well_countmultiple_designs: well_countsections_not_read: file, row_count
messagestringRequiredIts sentence in warnings, written for API callers.
filestringOptionalThe part or field it is about: file, constants, csv or constants_csv.
sheetstringOptionalThe 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 stringsOptionalThe series left out.
productstringOptionalThe product, as the file or options.products spells it.
reserves_categorystringOptionalThe category, as options.reserves_categories sent it.
labelstringOptionalThe unit label the file gives.
fromstringOptionalWhere the label is.
"header""units row"
Show all 22 fields
quantitystringOptionalWhat the label was read for: oil and water rates, gas rates or a ratio.
"oil_water_rates""gas_rates""gor""ogr""cgr""wor""wgr"unitstringOptionalThe unit it reads in instead.
curve_countintegerOptional≥ 0
Curves it counts.
total_curve_countintegerOptional≥ 0
Curves the file made.
formatstringOptionalThe format read.
"valnav_decline""valnav_constants""novi_arps""combocurve_parameters""mosaic_decline""aries"sales_productstringOptionalThe sales gas product.
raw_productstringOptionalThe raw gas product.
systemstringOptionalThe unit system read.
"imperial""metric"ratesobjectOptionalThe rate units read, as units.rates.
ShowHide 3 child fields
oilstringRequiredIts rate unit.
gasstringRequiredIts rate unit.
waterstringRequiredIts rate unit.
well_countintegerOptional≥ 0
Wells it counts.
Errors
| Status | When |
|---|---|
| 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