Rename, share, link or pair a source
Change a forecast source's name, visibility, plan_id or pairs (at least one).
Rename, share, link or pair a source
/forecast-sources/{id}Change a forecast source's name, visibility, plan_id or pairs (at least one). A refused request changes nothing, the plan to link included; only the creator, signed in, can make a source private.
Links and pairs
plan_id links and saves a done plan the caller can read, as on create; null unlinks. Moving the link to another plan clears pairs unless the body sends new ones.
pairsmatches source Well IDs to the plan's well indexes (GET /plans/{id}/wells/{index}): one plan well per source well, at most the source's well count. Null clears them.- While the linked plan is gone (
plan_linked: false), newpairsneedplan_idtoo.
Conflicts
If-Match with the ETag changes only the version you read; a stale one is a 409 with details.etag. Without it, a change made between the server's read and its write is a 409 too.
Errors
Unknown fields are a 400 listing the allowed ones. A server without a state store answers 409 "Forecast sources need a state store; this server keeps plans in memory".
Parameters
Path parameters
idstringRequiredFormat
uuidForecast source id from POST /forecast-sources or GET /forecast-sources.
Header parameters
If-MatchstringOptionalThe source's ETag, including quotes.
Request body
application/json
The fields to change.
namestringOptional1 to 100 characters
The new name.
visibilitystringOptionalprivate (its signed-in creator only) or tenant.
"private""tenant"plan_idstring or nullOptionalFormat
uuidA done plan to link, which linking saves; null unlinks.
pairsobject or nullOptionalSource Well IDs to the linked plan's well indexes, as {"W-1": 0}; null clears them.
Responses
200 OK
The updated source and its ETag.
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.
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"
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.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | A stale If-Match, or without one a change made while the request ran ( |
| 413 | The request body is over 10 MB. |
Shared errors400401403500What they mean