Skip to content
Developers
Get an API token

Novi Forecasts API

Forecast oil, gas and water for planned horizontal wells, run development plans and export the results over REST.

View MarkdownOpen in Claude(opens in a new tab)

Forecast oil, gas and water for horizontal wells before they are drilled, from a script, notebook or pipeline. Describe a well by its surface hole, toe, landing zone and completion design; get cumulative volumes by day on production, with EUR and Low and High bands on request.

  • Look up existing wells: headers, production, spacing neighbors and the model’s inputs.
  • Forecast up to 50 drawn wells in one request, each with several completion designs.
  • Run development plans of thousands of wells as background jobs.
  • Read every well’s cumulative curves to EUR, a page at a time.
  • Export a plan as CSV and Parquet, or as ARIES, ComboCurve and Val Nav import files.
  • Keep another tool in step with your saved plans and Legacy Forecasts1, pulling only what changed.
  • Price scenarios with simulated half-cycle economics (IRR, payback, NPV).
Object What it is Read it with
Model set A basin dataset with its oil, gas and water models. Every dataset call takes model_set; without it the default set answers GET /model-sets
Existing well A well in the dataset, keyed by its wellbore key, with production and spacing GET /wells, GET /wells/{key}
Drawn well A well you plan: shl and bhl as [lng, lat], a target formation, and optional landing, TIL date, pad and name Request bodies of POST /forecasts and POST /plans
Design Fluid in bbl and proppant in lb per lateral ft. Each well is forecast once per design designs in a request; GET /completions/defaults
Scenario A named alternative in one request. Its wells never space against another scenario’s scenario on each well
Plan A background job that forecasts many drawn wells and stores the result POST /plans, GET /plans/{id}
Legacy Forecast One of your company’s earlier predrill forecast runs, served read only as a plan GET /plans?origin=all
Curve One well’s cumulative volume per stream, every 30 days to EUR GET /plans/{id}/curves
Export A zip of a done plan’s tables POST /exports, GET /exports/{id}
Forecast source A booked forecast file (Val Nav, ComboCurve, Mosaic, ARIES or Novi) to compare with plans GET /forecast-sources, POST /comparisons
How the Novi Forecasts API flows from wells to resultsDraw wells by surface hole, toe and target formation, with completion designs, or lay them out by filling an area or reading an inventory file. A model set is a basin dataset with its oil, gas and water models, and drawn wells space against its existing wells. Send wells to POST /forecasts to forecast up to 50 wells and get the answer in the request, or to POST /plans to run thousands of wells as a background job. A plan stores the result. From a done plan you read curves with GET /plans/{id}/curves (cumulative volume per stream every 30 days to EUR), export with POST /exports to ARIES, ComboCurve or Val Nav files or CSV and Parquet, or sync another tool by listing the plans changed since your last run with GET /plans?updated_from and reading their curves.Read curvesGET /plans/{id}/curvesCumulative volume perstream, every 30 days to EUR.ExportPOST /exportsARIES, ComboCurve or ValNav import files, or CSV andParquet.Sync another toolGET /plans?updated_fromList the plans changed sinceyour last run, then read theircurves.Forecast nowPOST /forecastsUp to 50 wells, answered inthe request.Run a planPOST /plansThousands of wells as abackground job that storesthe result.Draw or lay out wellsSurface hole, toe andtarget formation, withcompletion designs. Orfill an area or read aninventory file.Model setA basin dataset with itsoil, gas and watermodels. Drawn wellsspace against itsexisting wells.How the Novi Forecasts API flows from wells to resultsDraw wells by surface hole, toe and target formation, with completion designs, or lay them out by filling an area or reading an inventory file. A model set is a basin dataset with its oil, gas and water models, and drawn wells space against its existing wells. Send wells to POST /forecasts to forecast up to 50 wells and get the answer in the request, or to POST /plans to run thousands of wells as a background job. A plan stores the result. From a done plan you read curves with GET /plans/{id}/curves (cumulative volume per stream every 30 days to EUR), export with POST /exports to ARIES, ComboCurve or Val Nav files or CSV and Parquet, or sync another tool by listing the plans changed since your last run with GET /plans?updated_from and reading their curves.Draw or lay outwellsSurface hole, toe andtarget formation,with completiondesigns. Or fill anarea or read aninventory file.Model setA basin dataset withits oil, gas and watermodels. Drawn wellsspace against itsexisting wells.Forecast nowPOST /forecastsUp to 50 wells,answered in therequest.Run a planPOST /plansThousands of wellsas a background jobthat stores the result.Read curvesGET /plans/{id}/curvesCumulative volume per stream, every 30days to EUR.ExportPOST /exportsARIES, ComboCurve or Val Nav import files,or CSV and Parquet.Sync another toolGET /plans?updated_fromList the plans changed since your last run,then read their curves.

Send drawn wells and designs to POST /forecasts for an answer in the request, or to POST /plans for a background job you then read, export or sync.

https://<your-company>.novilabs.io/forecasts/api/v1

Use the host you sign in to Novi at. Every path in these docs is relative to this base. GET /openapi.json returns the OpenAPI 3.1 document your host runs.

  • JSON in and out, snake_case names. Some reads also take a file upload (multipart/form-data).
  • Oil and water in bbl, gas in mcf, lengths and depths in ft; field names carry the unit.
  • Points are [lng, lat] in bodies and "lng,lat" in query strings, WGS 84 degrees.
  • Volumes are cumulative by ip_day, days since first production. BOE is oil plus gas at 6 mcf per bbl.
  • GET /conventions has the full rules, including the P-level convention.

/api/v1 only grows; additions are opt-in. Some releases tighten validation, so a loosely accepted request can become an invalid-input error. GET /health returns your host’s API version. See Versioning.

Surface Status
REST API at /forecasts/api/v1 with API tokens Available
Claude skill Available
Hosted MCP server and the Claude Desktop extension Preview
Python and TypeScript SDKs Planned
  1. Legacy Forecasts are dynamic imports from Forecast Engine v1. ↩