Novi Forecasts API reference
Wells, subsurface grids and production forecasts for drawn horizontal wells.
Novi Forecasts API
AvailableWells, subsurface grids and production forecasts for drawn horizontal wells.
- Version
1.103.0- Base URL
https://your-company.novilabs.io/forecasts/api/v1
Every sample on these pages uses this host. It stays in this browser.
- Authentication
Send a Novi API token as a bearer token on every request.
A Novi API token, created in the Forecasts app under Settings > API tokens. Get an API token · Authentication
- OpenAPI
- forecasts.json OpenAPI 3.1.0, 2.6 MB
About this API
Forecast oil, gas and water from horizontal wells before they are drilled, in the basins GET /model-sets lists.
The API serves the same data and models as the Forecasts app: existing wells with their production, spacing neighbors and spacing features; subsurface grids for each formation; and forecasts for wells you design. A drawn well runs through spacing (its neighbors), spacing features (depletion and spacing at every ip_day), subsurface interpolation and the oil, gas and water models, and comes back with cumulative volumes by ip_day.
Conventions:
- JSON in and out, with snake_case names. POST /areas, POST /area-sets, POST /inventories/read, POST /pads/read, POST /completion-designs/read and POST /forecast-sources[/read] also take a multipart file upload.
- Units are in field names or descriptions: feet, bbl, mcf, bbl/ft and lb/ft.
GET /conventionslists them with the BOE ratio (6 mcf per bbl) and the P-level convention. - Points are
[lng, lat]arrays in request bodies and"lng,lat"strings in query parameters (WGS 84 degrees). - Volumes are cumulative by
ip_day(days since first production); rates are daily averages. - Every response carries
X-Request-Id(send your own to correlate). Errors share one envelope,{"error": {"code", "message", "details"}, "request_id"};details.fieldnames the input at fault.invalid_argument: 400, 401, 403, 405, 413 and 416. 405 answers a method the path lacks, with anAllowheader anddetails.allow.not_found: 404 and 410.conflict: 409, and 429 for POST /plans past one caller's unfinished plans, withRetry-After.internal: 500, and 502 when a model worker failed.unavailable: 503.
- Large lists page with
limitand an opaquecursor; passnext_cursorback until it is null. - Dataset reads, economics decks and the changelog carry an
ETagand answerIf-None-Matchwith 304; done or failed plan reads carry one withCache-Control: private, no-cache. Responses over 1 KB are gzipped when you sendAccept-Encoding: gzip. Browsers on sites outside Novi's domain are refused at the CORS preflight. - Forecasts of up to 50 wells run in the request (
POST /forecasts), or as a job withasync: true. - Plans of up to GET /dataset
limits.plan_wellsforecasts (10,000 by default) and exports of a done plan's tables run as jobs:POST /plansorPOST /exportsanswers 202; GET the job withwait=25untilstatusisdone, or name acallback_urlon a server that allows callbacks. POST /plans,POST /exportsandPOST /forecast-sourcestake anIdempotency-Keyheader: a retry with the same key and body returns what the first request made instead of starting again.- Completions are designs: a request's
designs(fluid and proppant per ft) apply to every well, and each well comes back with one forecast per design, in design order. With one design, a well, pad, layout or scenario can set its own (see WellInputfluid_bbl_per_ft).- Spacing and its features don't depend on completions, so every design shares them.
- Explanations are the models' own: SHAP per ip_day and the training wells the forecast leans on, with options
for the model's analog wells. Ask with
explain: trueon POST /forecasts, or per plan well and design. An analog spread is a spread of analog wells, not the model's uncertainty. - EUR (estimated ultimate recovery) is opt-in with
eur: true: Novi's type-curve decline fit extends the 3-year forecast, as Novi's earlier Forecast Engine runs it for planned wells. It is not a model output. POST /declines fits curves you already have. - Economics are the Pad Optimizer's simulated half-cycle economics (IRR, payback and NPV), priced on the server by POST /economics under the set's illustrative deck (GET /economics/deck), not a Novi default.
- P10/P90 bands are opt-in with
bands: true: a low (p10) and a high (p90) cumulative curve per stream from Novi's predrill bands. Percentiles follow Novi's convention: p10 is the low curve. - TIL dates schedule wells: a well's own
til_date, else its pad's or layout's, else its scenario's, else the request's, is its first day of production; blank is today. They order parents and children in spacing and set the dates the spacing features use. - Depletion chain: a dated plan feeds each planned well's P50 production to the later plan wells it is a parent
of, where the set's models read neighbors' production (GET /dataset
depletion_chain). - Model sets:
GET /model-setslists the datasets with their models this server can serve. Sendmodel_seton any dataset-scoped operation to use one; without it, the set GET /model-sets names asdefaultanswers.- Plans and exports made under a set keep to it, so their later calls need no
model_set. Each set keeps its own plans, exports (with their queue and limits) and forecast cache; plan chunks share one queue across sets.
- Plans and exports made under a set keep to it, so their later calls need no
Operations
Service
14Health, the dataset behind the API, its units and conventions, the field dictionary, what changed in each release and this document.
- GETCheck service health
/health - GETDescribe the dataset
/dataset - GETList formations
/formations - GETList releases and what changed
/changelog - GETGet units and conventions
/conventions - GETGet who this request is
/me - GETGet what fields and Legacy Forecasts names mean
/field-dictionary - GETGet this document
/openapi.json - GETList the model sets
/model-sets - GETDescribe a model set
/model-sets/{model_set} - GETList the forecast models
/models - GETDescribe a forecast model
/models/{model_num} - GETMeasure a model's accuracy on held-out wells
/models/{model_num}/evaluation - GETGet a model's SHAP baselines
/models/{model_num}/baselines
Wells
12Existing wells: attributes, production, spacing neighbors and spacing features.
- GETList wells
/wells - GETGet a well
/wells/{key} - GETGet a well's production
/wells/{key}/production - GETGet a well's spacing neighbors
/wells/{key}/spacing - GETGet a well's spacing features
/wells/{key}/features - POSTList the PDP wells near drawn wells
/pdp-wells - POSTList the wells in a unit
/wells/search - POSTSummarize a unit's wells, grids and completions
/units/summary - GETCount wells by value
/wells/facets - POSTBuild type curves from existing wells
/wells/typecurve - POSTGet several wells' production
/wells/production - GETGet a well's stored predictions beside its actuals
/wells/{key}/predictions
Subsurface
4Formation grids (structure, thickness, BVI) and interpolated values along a well path.
Design
18Inputs for drawn wells: completion defaults and designs, TVD estimates, filled layouts, gun barrels, pads, well inventories, areas and area sets read from boundary files, and the Texas land survey grid.
- GETGet default completions
/completions/defaults - POSTEstimate TVD for well paths
/tvd-estimates - POSTPlace wells in a gun barrel
/gun-barrels - GETGet the land survey grid in a bbox
/land-grid - POSTFill an area with wells
/layouts/fill - POSTRead areas from a shapefile, GeoJSON, KML or KMZ
/areas - POSTFill many areas with wells
/areas/fill - GETList area sets
/area-sets - POSTKeep areas by name
/area-sets - GETGet an area set
/area-sets/{id} - PATCHRename or share an area set
/area-sets/{id} - DELETEDelete an area set
/area-sets/{id} - GETList the inventory upload's columns
/inventories/columns - GETDownload an inventory template
/inventories/template - POSTDownload a plan's wells as an inventory file
/inventories/write - POSTRead planned wells from a file
/inventories/read - POSTRead pads and their wells from a file of pad outlines
/pads/read - POSTRead completion designs from a file
/completion-designs/read
Forecasts
3Forecasts for up to 50 drawn wells, each with every completion design, optionally explained, in the request or as a job; and POST /declines, which fits curves you already have.
Economics
5The Pad Optimizer's simulated economics: the deck it prices with, and IRR, payback and NPV at the deck's discount rate for scenarios of forecast wells.
Plans
21Development plans of up to GET /dataset limits.plan_wells forecasts (wells × designs; 10,000 by default), run as background jobs, with explanations per well.
- GETList recent plans
/plans - POSTStart a plan
/plans - DELETEDelete unfinished plans
/plans - GETGet a plan
/plans/{id} - PATCHRename or save a plan
/plans/{id} - DELETEDelete a plan
/plans/{id} - GETList a plan shares
/plans/{id}/shares - POSTShare a completed plan
/plans/{id}/shares - DELETERevoke a plan share
/plans/{id}/shares/{share_id} - GETOpen a shared plan
/shares/{token} - GETSummarize a plan's wells
/plans/{id}/stats - GETCount a plan's flagged wells by input and side
/plans/{id}/checks - GETSum a plan's oil, gas and water by pad and zone
/plans/{id}/rollup - GETRead each well's cumulative curves to EUR
/plans/{id}/curves - POSTCompare plans, scenarios or a forecast source
/comparisons - GETList the PDP wells near a plan or pad
/plans/{id}/pdp-wells - GETGet one plan well
/plans/{id}/wells/{index} - GETExplain a plan well
/plans/{id}/wells/{index}/explanations/{design} - GETRank a plan's drivers
/plans/{id}/drivers/{design} - GETBuild a type curve from a plan's forecasts
/plans/{id}/typecurve/{design} - GETExport a plan
/plans/{id}/export
Saved documents
5Tenant-scoped filter sets, completion designs, type curves, views, settings, assumption sets, column mappings and plan views.
Forecast sources
6Booked forecasts read from Val Nav, Novi, ComboCurve, Mosaic and ARIES files, kept per tenant, private to their creator by default, optionally linked to a plan.
Exports
7A done plan's tables as one zip, written by a queued job: presets or your own tables and columns, status and progress, and a download that resumes.
No operation matches that filter.