Skip to content
Developers
Get an API token

Check service health

Whether the database, subsurface grids and model workers (spacing, calc, forecast) are ready, and the default model set when one is configured.

Check service health

GET/health

Whether the database, subsurface grids and model workers (spacing, calc, forecast) are ready, and the default model set when one is configured. status is degraded while anything is loading or down; forecasts need every worker ready.

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

app_version is this build and web the web UI release it serves. clients names the Claude Desktop extension (mcpb), Claude skill zip (skill) and hosted MCP endpoint (mcp, where offered) it serves, so a client can tell its user when theirs is out of date.

Legacy Forecasts

fe, on a server that reads them, counts those its background index has yet to read or failed to read, service-wide.

Responses

200 OK

Service health.

  • statusstringRequired

    ok when everything is ready, degraded otherwise.

    "ok""degraded"
  • versionstringRequired

    API version.

  • sample_databooleanRequired

    True when the API serves synthetic sample data.

  • datasetstring or nullRequired

    Dataset name.

  • uptime_sintegerRequired

    Seconds since the server started.

  • hostobjectRequired

    The machine the server runs on.

    ShowHide 2 child fields
    • cpusintegerRequired

      CPUs the server can use.

    • cpu_modelstring or nullRequired

      CPU model name, as the host reports it.

  • checksobjectRequired

    Component status.

    ShowHide 5 child fields
    • databasestringRequired

      Well database.

      "ok"
    • subsurfacestringRequired

      Packed subsurface grids.

      "ready""loading""unavailable"
    • spacing_and_featuresstringRequired

      Spacing and spacing feature tables for existing wells.

      "ok""missing"
    • workersobjectRequired

      Model workers.

      ShowHide 3 child fields
      • spacingstringRequired

        The spacing model worker.

        "ready""loading""down"
      • calcstringRequired

        The calc model worker.

        "ready""loading""down"
      • forecaststringRequired

        The forecast model worker.

        "ready""loading""down"
    • default_model_setobjectOptional

      Only when the server answers requests without model_set from a published set: that set's load state. While it's loading or unavailable, status is degraded and requests without model_set wait or answer 503.

      ShowHide 3 child fields
      • idstringRequired

        The configured default set id.

      • statusstringRequired

        The set's load state.

        "ready""loading""idle""unavailable"
      • errorstring or nullRequired

        Why the set is unavailable; null otherwise.

  • webobjectRequired

    The web UI release this server serves from its release channel: sha says which UI build its users get. It is as of the last channel read that succeeded (checked_at); a read that fails leaves it as it was and sets error.

    ShowHide 7 child fields
    • statusstringRequired

      Whether the server serves its web channel's newest release.

      • ok: it does.
      • held: the newest needs a newer API than this server's (newest.requires_api), so the server serves an older release, or its image's UI when sha is null.
      • unavailable: the channel has no release this API serves (none yet, or the served one was withdrawn), or the newest failed to load; the server serves an older release, or its image's UI when sha is null.
      • disabled: no web channel; the server serves its image's UI.
      "ok""held""unavailable""disabled"
    • shastring or nullRequired

      pattern ^[0-9a-f]{40}$

      Commit of the web UI release served (40 lowercase hex); null while the server serves the UI built into its image.

    • versionstring or nullRequired

      Version of the web UI release served, as 1.0; null when sha is.

    • requires_apistring or nullRequired

      Oldest API version (MAJOR.MINOR.PATCH) the release served needs; null when sha is.

    • checked_atstring or nullRequired

      Format date-time

      When the server last read its web channel (ISO 8601, UTC); null before the first read, and when disabled. A stale time means polling is failing: see error.

    • errorstring or nullRequired

      Why the last poll failed: the channel could not be read, the newest release this API serves did not load, or the assets of another release on the channel could not be checked (tabs still open on it may miss files). Null when the last poll succeeded, and when disabled. The server keeps serving what sha names either way.

    • newestobjectOptional

      The channel's newest release, sent only when it isn't the one served.

      ShowHide 3 child fields
      • shastringRequired

        pattern ^[0-9a-f]{40}$

        Its commit (40 lowercase hex).

      • versionstringRequired

        Its web UI version.

      • requires_apistringRequired

        Oldest API version it needs; above this server's version when status is held.

  • storageobjectOptional

    Only with a configured state store.

    ShowHide 2 child fields
    • kindstringRequired

      Adapter kind.

      "s3""fs""memory"
    • tenantstringRequired

      Instance default tenant.

  • app_versionstringOptional

    This build's version (VERSION, MAJOR.NN), as 0.36, as GET /changelog reports it. Absent, with clients, when the server can't read its VERSION.

  • clientsobjectOptional

    What each client of this API should run. Absent, with app_version, when the server can't read its VERSION.

    ShowHide 3 child fields
    • mcpbobjectRequired

      The Claude Desktop extension (.mcpb).

      ShowHide 4 child fields
      • versionstringRequired

        The extension this build serves, as its manifest version (semver, as 0.36.0). An extension older than this is out of date: tell the user to update from setup.

      • min_supportedstringRequired

        The oldest extension still supported (semver). Older ones may fail to load some tools: tell the user to update before going on.

      • downloadstringRequired

        Path of this build's extension file on this origin, under the server's base path, when it has one.

      • setupstringRequired

        Path on this origin of the API page, whose "Use it in Claude" section explains setup and links the download.

    • skillobjectRequired

      The Claude skill.

      ShowHide 2 child fields
      • versionstringRequired

        The build the skill zip comes from (VERSION, MAJOR.NN), as app_version: label the download with it.

      • downloadstringRequired

        Path of this build's skill zip on this origin, under the server's base path, when it has one. For Claude Code: unzip it into ~/.claude/skills/, so SKILL.md sits at ~/.claude/skills/novi-forecasts/SKILL.md.

    • mcpobjectOptional

      The hosted MCP endpoint's path on this origin, only where this server offers one. MCP clients reach it through the edge with a Novi API token as Authorization: Bearer.

      ShowHide 1 child field
      • pathstringRequired

        Path of the MCP endpoint on this origin, under the server's base path, when it has one; it answers JSON-RPC sent by POST.

  • feobjectOptional

    Only on a server that reads Legacy Forecasts: the background index across the service, counts only, as of its last complete scan; each field is null until this server has read the counts of a finished scan. It never changes status.

    ShowHide 3 child fields
    • pendinginteger or nullRequired

      Legacy Forecasts not yet read.

    • failedinteger or nullRequired

      Legacy Forecasts whose last read failed.

    • scanned_atstring or nullRequired

      Format date-time

      When the last complete scan ended (ISO 8601, UTC).

Errors

Shared errors500What they mean