Skip to content
Developers
Get an API token

Novi Forecasts API reference

Wells, subsurface grids and production forecasts for drawn horizontal wells.

Novi Forecasts API

Available

Wells, 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 /conventions lists 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.field names the input at fault.
    • invalid_argument: 400, 401, 403, 405, 413 and 416. 405 answers a method the path lacks, with an Allow header and details.allow.
    • not_found: 404 and 410. conflict: 409, and 429 for POST /plans past one caller's unfinished plans, with Retry-After. internal: 500, and 502 when a model worker failed. unavailable: 503.
  • Large lists page with limit and an opaque cursor; pass next_cursor back until it is null.
  • Dataset reads, economics decks and the changelog carry an ETag and answer If-None-Match with 304; done or failed plan reads carry one with Cache-Control: private, no-cache. Responses over 1 KB are gzipped when you send Accept-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 with async: true.
  • Plans of up to GET /dataset limits.plan_wells forecasts (10,000 by default) and exports of a done plan's tables run as jobs: POST /plans or POST /exports answers 202; GET the job with wait=25 until status is done, or name a callback_url on a server that allows callbacks.
  • POST /plans, POST /exports and POST /forecast-sources take an Idempotency-Key header: 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 WellInput fluid_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: true on 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-sets lists the datasets with their models this server can serve. Send model_set on any dataset-scoped operation to use one; without it, the set GET /model-sets names as default answers.
    • 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.

Operations

95 operations

Forecasts

3

Forecasts 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.