Novi Forecasts API
Forecast oil, gas and water for planned horizontal wells, run development plans and export the results over REST.
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.
What you can do
Section titled “What you can do”- 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).
Start here
Section titled “Start here”Core objects
Section titled “Core objects”| Object | What it is | Read it with |
|---|---|---|
| Model set | A basin dataset with its oil, gas and water models. Every dataset call takes model_; without it the default set answers |
GET / |
| Existing well | A well in the dataset, keyed by its wellbore key, with production and spacing | GET /, GET / |
| Drawn well | A well you plan: shl and bhl as [lng,, a target formation, and optional landing, TIL date, pad and name |
Request bodies of POST / and POST / |
| Design | Fluid in bbl and proppant in lb per lateral ft. Each well is forecast once per design | designs in a request; GET / |
| 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 /, GET / |
| Legacy Forecast | One of your company’s earlier predrill forecast runs, served read only as a plan | GET / |
| Curve | One well’s cumulative volume per stream, every 30 days to EUR | GET / |
| Export | A zip of a done plan’s tables | POST /, GET / |
| Forecast source | A booked forecast file (Val Nav, ComboCurve, Mosaic, ARIES or Novi) to compare with plans | GET /, POST / |
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.
Base URL
Section titled “Base URL”https://<your-company>.novilabs.io/forecasts/api/v1Use 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.
Conventions
Section titled “Conventions”- 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 /conventionshas the full rules, including the P-level convention.
Versioning
Section titled “Versioning”/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.
Status
Section titled “Status”| Surface | Status |
|---|---|
REST API at / with API tokens |
Available |
| Claude skill | Available |
| Hosted MCP server and the Claude Desktop extension | Preview |
| Python and TypeScript SDKs | Planned |
Footnotes
Section titled “Footnotes”-
Legacy Forecasts are dynamic imports from Forecast Engine v1. ↩