Skip to content
Developers
Get an API token

Quickstart

Create an API token, make your first call and read a done plan's oil and gas curves.

View MarkdownOpen in Claude(opens in a new tab)

This page takes you from no token to a done plan’s cumulative curves in three calls. You need a Novi login with access to Forecasts.

  1. Create a token. In the Forecasts app, open Settings, then API tokens. Name the token, pick how long it lasts (7, 30 or 90 days, 1 year, or a custom 1 to 365 days; 90 is the default) and create it. Copy it now: Novi shows it only once.

    The Create a token form: a name, and expiry choices of 7, 30 or 90 days, 1 year or custom, with 90 days selected.The Create a token form: a name, and expiry choices of 7, 30 or 90 days, 1 year or custom, with 90 days selected.
    After creating a token, Forecasts shows it once with a Copy token button and the note: Copy your new token now. Novi can't show it again.After creating a token, Forecasts shows it once with a Copy token button and the note: Copy your new token now. Novi can't show it again.

    If API tokens is missing from Settings, ask your company’s Novi administrator for the Access MCP permission.

  2. Set your base URL and token. Use the host you sign in to Novi at.

    Terminal window
    export NOVI_API_BASE="https://<your-company>.novilabs.io/forecasts/api/v1"
    # Paste the token at the prompt so it stays out of your shell history.
    read -rs NOVI_API_TOKEN && export NOVI_API_TOKEN
  3. Check who you are. GET /me answers with the account the token acts as.

    Terminal window
    curl -sS --fail-with-body \
    -H "Authorization: Bearer $NOVI_API_TOKEN" \
    "$NOVI_API_BASE/me"
    { "tenant": "example", "user": { "id": "7", "email": "user@example.com" }, "role": "customer" }
  4. List your done plans. origin=all includes your Legacy Forecasts1 beside the plans made in Forecasts. Each row’s origin.engine says which: v2 or fe.

    Terminal window
    curl -sS --fail-with-body \
    -H "Authorization: Bearer $NOVI_API_TOKEN" \
    "$NOVI_API_BASE/plans?origin=all&status=done&limit=5"
  5. Read a plan’s curves. GET /plans/{id}/curves returns each well’s cumulative volume every 30 days, to its EUR on a plan made with eur: true: cum[m-1] is the cumulative at day 30·m, so cum[11] is the volume to day 360.

    Terminal window
    PLAN_ID="<a plan id from the list>"
    curl -sS --fail-with-body --compressed \
    -H "Authorization: Bearer $NOVI_API_TOKEN" \
    "$NOVI_API_BASE/plans/$PLAN_ID/curves?limit=10"
    Cumulative oil by day online for each well in a done plan, in the Production tab of Forecasts.Cumulative oil by day online for each well in a done plan, in the Production tab of Forecasts.
    The plan's cumulative oil per well in the Forecasts app, first 3 years.
import os
import requests
BASE = os.environ["NOVI_API_BASE"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
def get(path, **params):
r = session.get(f"{BASE}{path}", params=params, timeout=60)
r.raise_for_status()
return r.json()
print(get("/me"))
plans = get("/plans", origin="all", status="done", limit=5)["plans"]
for plan in plans:
print(plan["id"], plan["name"], plan["origin"]["engine"])
if not plans:
raise SystemExit("No done plans yet: run one in the Forecasts app or with POST /plans.")
plan_id = plans[0]["id"]
params = {"limit": 100}
while True:
page = get(f"/plans/{plan_id}/curves", **params)
for well in page["wells"]:
oil = well.get("curves", {}).get("oil", {}).get("P50", {})
cum = oil.get("cum", [])
if len(cum) > 11 and cum[11] is not None:
print(well["label"], "oil to day 360:", cum[11], "bbl")
if page["next_cursor"] is None:
break
params["cursor"] = page["next_cursor"]

The TypeScript runs on Node 18 or later, which has fetch built in.

  1. Legacy Forecasts are dynamic imports from Forecast Engine v1. ↩