# Novi Forecasts API

Source: https://developers.novilabs.com/forecasts/

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

- [Novi forecasting on novilabs.com](https://novilabs.com/energy-analytics/forecast-engine/): Machine-learning-driven per-well forecasts for drill schedules, PDP forecasts and asset evaluations.

## 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 Forecasts[^legacy], pulling only what changed.
- Price scenarios with simulated half-cycle economics (IRR, payback, NPV).

## Start here

  - [Quickstart](https://developers.novilabs.com/forecasts/quickstart/): Make a token, call the API and read a plan's curves.
  - [Authentication](https://developers.novilabs.com/forecasts/authentication/): API tokens, access and sign-in for MCP clients.
  - [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/): Pull only the plans that changed into another tool.
  - [MCP server and Claude skill](https://developers.novilabs.com/forecasts/mcp/): Ask questions of your plans from Claude.

## 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_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` |

<ForecastsFlow />

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

```text
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.

## 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 /conventions` has the full rules, including the [P-level convention](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/#low-mid-and-high).

## 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](https://developers.novilabs.com/platform/versioning/#novi-forecasts-api).

## Status

| 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] |

> **SDKs:**
> Until the SDKs ship, call the API with any HTTP client. Examples use `curl` and Python `requests`; the quickstart also
> shows TypeScript `fetch`.

[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
