Skip to content
Developers
Get an API token

Get units and conventions

What every number in this API means: each quantity's unit, BOE (6 mcf of gas per bbl of oil) and the P-levels (P10 is the low curve and P90 the high, the reverse of SPE PRMS).

Get units and conventions

GET/conventions

What every number in this API means: each quantity's unit, BOE (6 mcf of gas per bbl of oil) and the P-levels (P10 is the low curve and P90 the high, the reverse of SPE PRMS). Read it once before reporting numbers.

Send a Novi API token as a bearer token on every request. Authentication
The answer

Also as Markdown sections, the text the Novi Forecasts MCP server and Claude skill show. It changes only with a deploy, so it carries an ETag. include=decline_profiles adds how Val Nav, Mosaic, ComboCurve and Novi turn decline segments into volumes.

Parameters

Query parameters

  • includestringOptional

    decline_profiles adds decline_profiles: for Val Nav, Mosaic, ComboCurve and Novi, the basis their files state declines in, the year length those declines are per, the month basis, how a period's volume is counted, what ratio segments decline with, whether a tool's own results back it, and the same as Markdown. Any other value is a 400 with details.field include.

    "decline_profiles"
  • model_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches the base dataset; once the server retires it, a 400 naming the set answering instead.
    • An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in details.allowed (published sets only once default is retired); a set that can't load, a 503 with the reason.
    • Plans and exports stay in their set: a call naming them (by path, plan, ids, source.plan, a scenario's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Responses

200 OK

Units and conventions.

  • api_versionstringRequired

    API version.

  • unitsobjectRequired

    The unit of each quantity in responses; rates are these per day.

    ShowHide 9 child fields
    • oilstringRequired

      Oil volumes.

    • gasstringRequired

      Gas volumes.

    • waterstringRequired

      Water volumes.

    • boestringRequired

      Barrels of oil equivalent.

    • lateral_lengthstringRequired

      Lateral length.

    • tvdstringRequired

      True vertical depth.

    • proppantstringRequired

      Proppant per lateral foot.

    • fluidstringRequired

      Fluid per lateral foot.

    • moneystringRequired

      Money, in economics.

  • boeobjectRequired

    Barrels of oil equivalent.

    ShowHide 2 child fields
    • gas_mcf_per_bblnumberRequired

      mcf of gas counted as one barrel of oil: BOE = oil bbl + gas mcf / this.

    • labelstringRequired

      How to label BOE, as BOE (6:1).

  • p_levelsobjectRequired

    P-level names: Novi's P10 is the low curve and P90 the high one, the reverse of SPE PRMS.

    ShowHide 3 child fields
    • lowanyRequired

      Always "P10"

      The low curve's name.

    • highanyRequired

      Always "P90"

      The high curve's name.

    • conventionstringRequired

      The convention in one sentence, as exports write it.

  • sectionsarray of objectsRequired

    The conventions in prose, in reading order.

    ShowHide 3 child fields in each item
    • idstringRequired

      Stable id, as units.

    • titlestringRequired

      Heading.

    • markdownstringRequired

      The section, in Markdown.

  • decline_profilesarray of objectsOptional

    With include=decline_profiles: how each tool turns decline segments into rates and volumes, in this order: valnav, mosaic, combocurve, novi.

    ShowHide 10 child fields in each item
    • idstringRequired

      The tool.

      "valnav""mosaic""combocurve""novi""aries"
    • titlestringRequired

      The tool's name.

    • declinesarray of stringsRequired

      The bases the tool's files state declines in: nominal (continuous), secant effective or tangent effective, each a fraction per year.

      "nominal""secant""tangent"
    • year_daysnumberRequired

      Days in the year those declines are per.

    • monthsstringRequired

      calendar for calendar months, 30-day for 30-day months from ip day 0.

      "calendar""30-day"
    • volumesstringRequired

      integral when a period's volume from oil, gas, water or condensate segments is the exact integral of the rate (the markdown says how a stream made from a ratio counts its days); start_of_day when each whole day counts the rate at its start.

      "integral""start_of_day"
    • ratio_slopestringRequired

      What ratio segments (GOR, OGR, CGR, WOR, WGR) decline with when a segment doesn't say: time, or the parent stream's cumulative volume.

      "time""volume"
    • verifiedbooleanRequired

      Whether the tool's own results back these conventions; verified_against says how far.

    • verified_againststring or nullRequired

      What the profile matches, in words; for an unverified one, what it was compared with, or null.

    • markdownstringRequired

      The profile in Markdown.

Conditional requests 304 Unchanged since the ETag in If-None-Match.

Errors

Shared errors400401403500503What they mean